Defining Ajax Event Page Element Properties

This topic provides an overview of defining Ajax events as layout page element properties and describes how to:

  • Define Ajax events for page element properties.

  • Pass parameters in Ajax events.

  • Perform partial-page refreshes and updates using Ajax events.

This topic also provides an example of defining an Ajax event to update a field on a page.

The Ajax event is a general purpose event which allows you to pass any arguments to the server and return any data in a format of HTML, JSON, or XML.

An Ajax event can be invoked using a POST or GET and can be tied to any page element where you can define JavaScript events.

The Understanding Defining JavaScript Event Page Element Properties topic lists the page elements where you can define JavaScript events.

Ajax Events and Partial Page Refreshes and Updates

Using Ajax events allows you to perform partial page refreshes and updates very easily. For example the following available Mobile Application Platform APIs can be used:

  • GenLayoutHTML - enables you to get a snippet of generated HTML for the same layout or any other layout to pass back to the client.

    You can also send back a snippet of HTML defined within a container on a page.

  • GenLayoutDoc - enables you to call a layout that returns the Document object that was used to invoked the MAP application. This allows you to run MAP application business logic and return simply the data generated instead of the actual HTML. This method can be used to call an AJAX event directly by populating the PAGE_ID and LAYOUT_ID with the correct parameters.

    Note: If the Content Type is HTML then the data will not properly parse when loading the Document as the Content Data must be either XML or JSON.

You can also send back a snippet of HTML defined within a container on a page.

Ajax Events and Serialization

When defining Ajax events you have the option to perform data serialization if data you are passing is not PeopleSoft document data, or have the framework perform the serialization into a Document within the PeopleCode event.

Field or Control

Definition
Input Data – Serialization

You can use the unique system-generated value in the Form ID field in your JavaScript to serialize all the inputs on the page.
Input Data – No Serialization

If you select no serialization for data input, the framework does not attempt to serialize the name/ value pairs from the JavaScript into the defined PeopleSoft document for the layout.

To get the contents of the data passed, use the GetAJAXNonSerializedData method of the Map object. You can also get parsed input data by using the following methods of the Map object: GetNumberofAJAXParms, GetAJAXName, GetAJAXValue, GetAJAXValuebyName; and the AJAXUrl method of the MapElement object.

Output Data – No Serialization

If you select no serialization for output data the contents of what is passed back is returned as-is to the client. If you choose no serialization, then the contents passed back are dependent on the content type you select in the Content Type field when defining the Ajax event in the properties page for the element.

To define an Ajax event as a page element property you must at a minimum perform the tasks shown in the following list. There is no particular order for completing them.

  • Access the JavaScript Events section of the properties page for the element. Several fields appear in the Ajax Event section on the element properties page that are important when creating the JavaScript event:

    • Ajax URL – You must include the system-generated value that appears in this field in your JavaScript so it can call to invoke the Ajax event.

    • Ajax URL – You must include the system-generated value that appears in this field in your JavaScript so it can call to invoke the Ajax event.

  • Create a JavaScript function using the Layout Designer – JavaScript page, or ensure that the function is defined in the template assigned to the layout or page via the Template Designer – JavaScript page.

  • Use PeopleSoft Application Designer to create an application class to run when the Ajax event is called.

  • Use the JavaScript Events section on the properties page for the element o define the event.

To access the JavaScript Events section on the properties page for a page element, select PeopleTools > Mobile Application Platform > Layout Designer, and in the Layout grid click the Properties link for the page element to which to add the Ajax event.

The Ajax Event section is collapsed by default. Click the arrow next to the box label to expand the section.

Image: Ajax Event section of the page element properties page

This example illustrates the fields and controls for defining Ajax events. You can find definitions for the fields and controls later on this page.

Ajax Event section of the page element properties page

Field or Control

Definition
JavaScript Event

Select a JavaScript event from the drop-down list.
JavaScript Value

Enter the JavaScript function name. Remember to add the argument list to a function, as necessary.

Package, Path, Class ID, Method

Enter the details of the application class if you choose to have the system perform serialization of data or to perform partial page updates/refreshes.

  • Package. Enter the name of the application package that contains the method to invoke.

  • Path. Enter the names of each sub-package in the application class hierarchy that define the location of the application class. Separate sub-package names by a colon. If the class is defined in the top-level application package, enter or select the colon.

  • Class ID. Enter the name of the application class that contains the method to invoke.

  • Method. From the drop-down list select the method to invoke.
Pending Approval

This field is currently not used and is reserved for future use.
Use Exception Layout

If you check this box and an Exception Layout is defined for the Layout, then if an exception is thrown the MAP framework will invoke the defined Exception Layout.
Content Type

From the drop-down list, select the format of any returned data. The options are:

  • HTML. (Default.)

  • JSON.

  • XML.
Input No Serialization

If you check this box the system does not perform serialization on input data.
Output No Serialization

If you check this box the system does not perform serialization on output data.
Container Label ID

Displays the system-generated container ID of the container you select using the Select Container link. Use the ID in your JavaScript code to send back HTML data contained in containers on a page when an Ajax event is invoked.

Select Container

Click the link to access the Select a Container Label page to choose the container from which to get data.
Ajax URL

Displays the system-generated URL that the JavaScript must call to invoke the Ajax event.
Form ID

Displays the system-generated ID to include in JavaScript to serialize Ajax event input data.

To pass specific parameters in Ajax events use name value pairs with the name the ID of the element when coding the function on the Layout Designer – JavaScript page.

The following JavaScript code shows an example of passing parameters in an Ajax event: 

$.post("/PSIGW/RESTListeningConnector/QE_LOCAL/DEMO_LAYOUT.v1/1/4", { 
prim_string__1 : "John", prim_string__2 : "bill"}).done(function(data) 
{  alert("Data Loaded: " + data);});

In the example prim_string__1 and prim_string__2 are the element IDs. This code would pop-up an alert with the returned data.

To perform page refreshes and updates using Ajax events, create a JavaScript event calling the unique system-generated URL that appears in the Ajax URL field in the Ajax Event section in the properties page for the element. This will properly call the application class assigned to the event.

To send back a snippet of HTML that is defined within a defined container on the page, click the Select Container link in the Ajax Event section in the properties page for the element to select the container. The Select a container label page appears.

Image: Select a container label page

The Select a container label page displays all containers defined on the mobile application page.

Select a container label page

All of the containers defined on the page appear in the list.

To perform partial page refreshes and updates using Ajax events, following the steps outlined in the Defining Ajax Events as Page Element Properties section in this topic, with the following additional steps:

  1. Select the container that contains the data to refresh/update.

    1. In the Ajax Events section on the page element properties page, click the Select Container link. The Select a container label page appears.

    2. Select the container that contains the data for partial page refresh/update or the HTML snippet to send back and click the OK button.

      The container ID appears in the Container Label ID field.

  2. Use the Container Label ID value in your JavaScript code to send back HTML data contained in the container when the Ajax event is invoked.

  3. When you define the Ajax event in the page element properties page, from the Content Type drop-down list, select HTML.

In the Ajax Events section of the properties page for a push button the following information is defined:

Image: Example: Ajax Events section

The Ajax Event section of the page illustrates sample data for defining an Ajax even to update a field on a page.

Example: Ajax Event section

On the Layout Designer – JavaScript page, enter the following JavaScript code:

function UpdateField(){
$.post("/PSIGW/RESTListeningConnector/QE_LOCAL/DEMO_LAYOUT.v1/
map_button_1/-10", $("#DEMO_LAYOUT_page1_form").serialize()), 
function(result){$("span").html(result)});
}