Using jQuery in PeopleSoft: Introduction

At my company, management decisions have kept most of our PeopleSoft applications on PeopleTools versions prior to 8.50. So we haven't been able to take advantage of the new AJAX features that come with the most recent versions of Tools. However, we are now working on a application that will be exposed to an large audience outside of our corporate firewall. We realized that we would like our users to have a modern browser experience including: dynamic page updates, client-side validation, modal dialog boxes. How can we do this with PeopleTools 8.49? The answer is to do our own JavaScript programming.

Having done some JavaScript for my wife's business web site GetRolling.com, I realized that using "straight" JavaScript to program modern features is a lot of work, so we went looking for a framework. We quickly settled on jQuery, a popular, open-source JavaScript library with lots of support and many add-ons. We had also heard that Oracle was using jQuery with the most recent versions of  PeopleTools (true?), so it would help "future-proof" our experience.

The core strength of jQuery is its selectors, which allow you to easily select and act on one or more DOM objects without having to traverse the DOM hierarchy. The multitude of selector options can be a bit daunting at first, but after learning some common patterns, I found them to be very efficient. While the jQuery project provides plenty of documentation on their site, I found this Ref Card from DZone very handy when trying to figure out how to write my selectors.

A key concept is that your jQuery code should be wrapped in document ready block:

$(document).ready(function(){
    // your code
});

This ensures that you code does not get called until the DOM is loaded in the browser and ready. You will use $(selector) throughout your jQuery code. $() is just shorthand for the core function jQuery(). jQuery also makes liberal use of anonymous functions like the function(){...} above.


Getting Started


I'll skip the traditional HelloWorld as it's not very instructive for our use and get right to a concrete example. Let's say you want to validate a user entry immediately after the user leaves the input field. In PeopleTools, you would need to add FieldChange PeopleCode to the field and uncheck "Allow Deferred Processing."  This would force the page to be submitted to the server whenever the field value is changed so that the validation PeopleCode can run. This can be very disruptive to the user experience and place extra load on the server.

With jQuery, we could write this (USA-centric) code:

$(document).ready(function(){
    $('#ADDRESS_ZIP_CODE').change((function () {
    if($(this).val().length < 5) { 

alert("Please enter a valid Zip Code"); } }); });

What's happening here? # is the id selector. The fragment $(#'ADDRESS_ZIP_CODE') "selects" the object with an id='ADDRESS_ZIP_CODE'. After the DOM is ready, jQuery adds an anonymous function to the onChange event of this object that happens to be a text input element. When the value of the input is changed, the function is called. Inside the function, $(this) refers to the selected object. val() returns the value attribute string and .length is the standard JavaScript length property of the string. As you can see, you can write some very concise code with jQuery.

Here is another handy example I use in PeopleTools grids.

$('input:text[id^=HOURS]').each(function(index) {
  // your code
}

This selects each of the input text elements whose id attribute starts with HOURS. each() iterates through each element in a loop. In a PeopleTools grid, each field id is suffixed with $i where i is the row number, e.g., HOURS$2, so you can see how useful this can be.

In future blogs I'll describe some more powerful things you can do with jQuery, but I'd like to use the rest of this blog to show how to get this code on to your page.

The basic mechanism I use is to write the JavaScript in an application designer HTML object and use page activate PeopleCode to put that HTML into an HTML Area that I've included on the page. The position of the HTMLArea does not seem to matter much, but I try to place it near the top of the page.

It's important to include a reference to the jQuery library in your code. Here's an example of how it looks:


<script src="/rhijs/jquery-1.4.2.min.js" type="text/javascript"></script>

<script type="text/javascript" >
$(document).ready(function(){
 $('#ADDRESS_ZIP_CODE').change((function () {
  if($(this).val().length < 5) {
   alert("Please enter a valid Zip Code");
  }
 });
});
</script>


I had my admin put the file jquery-1.4.2.min.js on our web server in a custom directory so it can be referenced by my pages. This is the "minified" version of the library. The code is nearly impossible to read, but the file is much smaller to load and should be used for production. There also a standard version with the full source that can be used for reference and debugging: jquery-1.4.2.js.

If you don't have access to your web server, a good option, if your network allows, is to hot link to a CDN as described here: http://docs.jquery.com/Downloading_jQuery#CDN_Hosted_jQuery

The basic PeopleCode to include your JavaScript in your PeopleSoft page is:

MY_REC_DERIVED.HTMLAREA1.Value = GetHTMLText(HTML.MY_JQ_ZIP_VALIDATE);

A powerful technique is to use the text replacement functionality of GetHTMLText to "customize" your code on the fly. For instance, instead of hard coding the error message in the JavaScript, we could modify the alert line to read:

 alert("%BIND(:1)"); // note the quotes around the bind

and change our PeopleCode to:

Local string &invalidZipMsg =  MsgGet(29000, 85, "Message not found");
MY_REC_DERIVED.HTMLAREA1.Value = GetHTMLText(HTML.MY_JQ_ZIP_VALIDATE,&invalidZipMsg);

That's it for now. In future blogs I'll introduce a technique that allows you to intercept calls to delivered JavaScript, so you can trigger your own validation and verification code; show you how to format input; how to create your own modal dialogs; and how to add an Auto-Complete textbox to your page. I'll also discuss some tools that are essential to your success in browser JavaScript programming.

I'm certainly not the first one to use JavaScript with PeopleSoft. There are plenty of examples on the Internet. I'm in special debt to Jim Marions' blog and his new book PeopleSoft PeopleTools Tips & Techniques.