Jelly: User Interaction...

[SlightlyLoony]

Throughout this series, I've been using UI Pages as my examples — but to this point I haven't mentioned one of the main purposes that people want UI Pages: the ability to interact with a user. So today I'm going to show you a very simple example of how that might be done. I've deliberately kept this example stripped to the basics in order to highlight the bits I'm showing you. In the world of HTML, that means it's ugly as sin — try to ignore that (or fix it up yourself!) and concentrate on the mechanics.

Our goal today: we need an order form for hamburgers, for our very simple gourmet hamburger business. Our chef will let you ask for anything you want on your burger, but he delivers it the way he decides to. The burgers are a fixed price: $27.89 (they're really good!), which is about the same in Euros these days. So our order form needs only one input: the number of burgers you want. When you submit your order, we compute the extended price, the tax (8.75% here in San Diego), and the total. Here's the example page, which is named order_form:

<?xml version="1.0" encoding="utf-8"?>
<j:jelly>
       <g2:evaluate>
               var isAnswer = (jelly.sysparm_answer != null);
               isAnswer;
       </g2:evaluate>
       <j2:if>
               Number of burgers you want: <input id="number_of" type="text" />

               <input id="enter_number" type="submit" />
         

                     $('enter_number').onclick = function(event) {
                             window.location = 'order_form.do?sysparm_answer=true${AMP}' +
                                       'sysparm_number=' + $('number_of').value;
                     }
             
       </j2:if>
       <j2:if>
               <g2:evaluate>
                       var qty = jelly.sysparm_number - 0;
                       var ext = qty * 27.89;
                       var tax = ext * 0.0875;
                       var tot = ext + tax;
                       var extStr = ext.toFixed(2);
                       var taxStr = tax.toFixed(2);
                       var totStr = tot.toFixed(2);
               </g2:evaluate>
               Your delicious burgers will be ready shortly after you fork over the cash.   You owe us:

               $[extStr] for the burgers

               $[taxStr] for the tax man

               $[totStr] due to us, now, in small unmarked bills and coins
       </j2:if>
</j:jelly>

Most of that you should be able to understand right now. The only thing I've really added to the Jelly is a couple of Jelly variables whose names start with sysparm_ instead of jvar_ (but they're Jelly variables nonetheless). More on those a little further along in this post. Right now I want to tell you a little bit about how UI Pages actually work in the ServiceNow system.

When you define a UI Page, you define more than the Jelly — you also give that UI Page a name (and there are other fields that I'm not going to describe today). That name is how you get the UI Page to display — it becomes part of the URI. For example, I named this UI Page order_form, and to ask for it I use the URI /order_form.do. The ".do" after the UI Page's name is the standard way on the ServiceNow platform to construct a URI that runs a UI Page (or other things, but those are topics for another day). It's important that the name you pick for your UI Page be different than the name of any other UI Page or other valid URI, otherwise you might get something unexpected when you use that URI!

Just like any other URI, you can include query parameters in your ServiceNow URIs. But...there's a convention you need to follow to make these query parameters available to your Jelly pages — the names of those query parameters need to start with sysparm_. When they do, the ServiceNow platform will automagically copy them into Jelly variables — those same Jelly variables that I mentioned earlier. So, for example, a URI that looks like this:

/order_form.do?sysparm_answer=false&sysparm_number=5

Will result in two Jelly variables appearing in your order_form UI Page: sysparm_answer (with a value of "false") and sysparm_number (with a value of 5).

Now, armed with this knowledge, take a close look at the example Jelly above. The first evaluate tag is just testing to see if the sysparm_answer parameter was present. If we request the order_form UI Page with no query parameters, then the result of this evaluate will be false; otherwise it's true:

       <g2:evaluate>
               var isAnswer = (jelly.sysparm_answer != null);
               isAnswer;
       </g2:evaluate>

Just after that evaluate, we have a couple of if tags. Check out what they're doing:

       <j2:if>
               ...
       </j2:if>
       <j2:if>
               ...
       </j2:if>

Basically they divide our single UI Page into two: one that renders if there wasn't a sysparm_answer parameter, the other if there was. Now let's look inside the piece that only renders when there is no sysparm_answer parameter:

               Number of burgers you want: <input id="number_of" type="text" />

               <input id="enter_number" type="submit" />
         

                     $('enter_number').onclick = function(event) {
                             window.location = 'order_form.do?sysparm_answer=true${AMP}' +
                                       'sysparm_number=' + $('number_of').value;
                     }
             

This just puts up a really dumb little form to capture the number of burgers the user wants to order. But look in the script: when the user clicks on the submit button, that script constructs the URI to go right back to our order form — but this time with query parameters. Now let's look at the piece that only renders when there are query parameters:

               <g2:evaluate>
                       var qty = jelly.sysparm_number - 0;
                       var ext = qty * 27.89;
                       var tax = ext * 0.0875;
                       var tot = ext + tax;
                       var extStr = ext.toFixed(2);
                       var taxStr = tax.toFixed(2);
                       var totStr = tot.toFixed(2);
               </g2:evaluate>
               Your delicious burgers will be ready shortly after you fork over the cash.   You owe us:

               $[extStr] for the burgers

               $[taxStr] for the tax man

               $[totStr] due to us, now, in small unmarked bills and coins

In this evaluate tag we compute the extended price, the sales tax, and the total. Just below that, we render the results so that our customer can pay us.

What I did here with a single UI Page could just as easily have been done with two completely separate UI Pages — which way to go is a design choice that's entirely up to you. Generally I prefer the page-for-each-function style (which would take two pages here), but your mileage may vary.

So there you go — UI Pages that actually interact with a user! What more could you possibly want?