How to communicate across the frames in a User desktop
Summary
The User portal is made up of HTML frames. Sometimes it is desirable to modify one frame based on the events that happen in another.
Generally, it is tedious to define JavaScript event handlers that recognize events that happen in other frames. However, two out-of-the-box functions in the sendEvent API (part of DesktopWrapper) can simplify this task: registerEventListener() and sendEvent().
Suggested Approach
The Process Commander desktop portals are made up of frames, and sometimes it is necessary to modify one frame based on the events that happen in another. Two standard JavaScript functions can simplify this task.
The registerEventListener function
registerEventListener(string Event Name, object Function name, object Event Data)
The JavaScript function registerEventListener() registers a function to be invoked whenever a specific event occurs. Since registerEventListner() is at the parent-level node of the desktop, it can 'listen' to events from all frames.
The function takes three parameters:
- Event name- a string representing a type of event. The name can be any string, and must be in quotes. To avoid conflicts with standard event names and create a safe namespace, prefix your event names with your organization (i.e., "MYCOMPANYunique_event_name" )
- Function name- the name of a JavaScript function to be invoked when the event specified in the first parameter occurs
- Event Data (optional) - reference to serialized data passed along to the function (i.e., the name of a predefined JavaScript object)
The sendEvent function
sendEvent(string Event Name, object Event Data, mode, delay)
Executing the sendEvent()function causes the registered listener to be invoked. The function takes four parameters:
- Event name- a string representing a type of event. The event should already be registered.
- Event data(optional) - serialized data for the listening function
- Mode(optional) - determines timing of the execution of the listening function. There are five available modes:
- ASYNC (default)
- SYNC
- ASYNC_REPLACE
- ASYNC_COPY
- ASYNC_COPY_REPLACE
- Delay (optional) - milliseconds until execution of the listening function. The default value is 10 milliseconds.
Pizza with extra toppings
Now let's look at a practical example: a flow named OrderPizza. Inside OrderPizza, there is a subflow named WithExtraToppings; a screen flow.
Each flow action displays a single ingredient name (i.e., onions, anchovies). The user indicates Yes or No with a radio button and then clicks NEXT>> to see the next available ingredient on the next flow action.
The user interface requirement is to present a list of Yes ingredients in a gadget that appears in the collapsible navigation pane (the left portion of the screen), and to update the list each time the user clicks NEXT>>.
1. Defining the Gadget
A Data-Gadget rule named (what else!) ExtraToppings has been defined. The gadget has been added to the Process Work portion of the user's portal (Data-Portal!WorkUserDD), so it is displayed throughout the flow process. This rule contains the following HTML code:
<script>
registerEventListener("myPizzaExtraToppingsUpdate", showToppings, "objPizza");
function showToppings(objPizza) {
document.getElementById("toppingsList").innerHTML=objPizza.text
}
</script>
<html>
<div id="toppingsList">
</div>
</html>where myPizzaExtraToppingsUpdateis the name of the event that will cause showToppings() to be executed. The objPizza.text property becomes the source of HTML for the toppingsList element.
2 Sending the event from the Perform harness
Each flow action updates a page list embedded in the pyWorkPage page, named extraToppings. Each page of extraToppings has two properties: ingredientName and addToPizza(yes/no).
The Perform harness contains a section rule named toppingsCollection. This section contains the following HTML code:
<script>
function PizzaObj() {
this.text = document.getElementById("choiceOfToppings").innerHTML;
}
function processMarkup() {
objPizza = new PizzaObj();
sendEvent("myPizzaExtraToppingsUpdate"", objPizza);
}
</script>
<body onload="javascript:processMarkup();">
<div id="choiceOfToppings" style="display:none">
{WITH Page pyWorkPage}
{foreach in=.extraToppings}
<UL>
{WHEN .addToPizza == "yes"}
<LI>{$THIS.ingredientName} </LI>
{/when}
</UL>
{endforeach}
{endWITH}
</div>
</body>where:
PizzaObj() is a JavaScript object type that serializes the data used by the registered (listening) function.
PizzaObj() has one property named text. The text property contains the markup text (HTML) that will be 'shipped' over to the ExtraToppings gadget in the left frame of the portal.
The function processMarkup() creates an instance of PizzaObj() named objPizza. Any HTML code in the choiceOfToppings element becomes serialized data in objPizza. Note that the HTML in this section of the harness does not display, but it is refreshed whenever the primary form (flow action) is submitted to the server
Results
When the user clicks "NEXT>>", sendEvent() triggers the previously-registered function showToppings, which takes the HTML from the object (objPizza) and writes it in the toppingsList area of the ExtraToppings gadget.