When designing forms in LiveCycle Designer ES that will eventually be rendered as a form guide by the server I regularly come across the need for script on the form to notify the form guide something needs to be done. One such case is the use of xfa.host.messageBox(). When this script is executed in a form guide the default Flex Alert is shown. While this is fine for quick informational messages it cannot be styled to match the look of my form guide nor can it handle any user response. This article covers one possible technique that can be used to allow your form scripting to send events to the form guide.
Step 1: xfa.host.name == "Flash"
This one line of script will very quickly become your friend when scripting a form that may be rendered as a form guide. Keying on the current host name allows you to target your script to only run in certain environments. This technique is not only valuable to ensure scripting outside of the supported xfa subset can still be executed in Acrobat/Reader it also opens the door for some inventive scripting when the form is being hosted in Flash (ie. form guide). One such door that opens is the ability to enter ActionScript directly in your form design script that will only get executed when in a form guide context.
Step 2: Add ActionScript to your form design script
Let's look at a case where the client-side click event of a button in your form design has the following script.
//Show Yes/No message box
var ans = xfa.host.messageBox("My Text" , "My Title", 2);
if (ans == 3)
{
// No is selected
}
else
{
// Yes is selected
}
In order to get a similar result in the form guide where the user gets presented with a Yes/No message box that must be answered an event can be fired. On the same click event we can add the following script.
if (xfa.host.name == "Flash")
{
this.dispatchEvent(new XfaModelEvent("showCustomDialog", false, false, "My title", "My text", null);
}
This ActionScript will fire an event on the form guide that can be listened for and acted upon accordingly. The name of the event, showCustomDialog, could be any string you wish. You could also fire events with multiple names fro myour form script for any number of desired behaviours.
Step 3: Create a Popup Manager in Flex
In order for this technique to work your form guide will need to reference a custom Flex library that includes a custom guide layout (ie. Wrapper).
First, I'll explore the creation of a Xfa Popup Manager in Flex. There are many ways you could write your Flex code to display popups requested from scripting in your form design. This method is one such approach but could be altered to suit your individual needs. Here are the basic steps I will be following.
- Create a class called XfaPopUpManager
- Create a static public function called "manage" that takes a Page as input
- Set up listeners for all panel items on the current page
- Handle popup events when they occur
- Listen for popup close events
And here is the abbreviated class code.
public class XfaPopUpManager
{
private var popup:Alert;
static public function manage (oPage:Page):XfaPopUpManager
{
return new XfaPopUpManager(oPage);
}
public function XfaPopUpManager(oPage:Page):void
{
addPopupListeners(oPage);
}
/**
* Creates listeners in order to provide a custom popup dialog for
* those fields that dispatch a "showCustomDialog" XfaModelEvent at runtime.
*/
public function addPopupListeners(oPage:Page):void
{
for each (var item:PanelItem in oPage.layout.getPanelItems())
{
if(item.boundData != null && item.boundData.hasEventListener("showCustomDialog") == false)
{
item.boundData.addEventListener("showCustomDialog", popupHandler);
}
}
}
/**
* show popup has been requested - present a dialog.
*/
protected function popupHandler(oEvent:Event):void
{
if (displayPanelItems[oEvent.currentTarget] != null)
{
var title:String = "";
var msg:String = "";
if (oEvent is XfaModelEvent)
{
title = XfaModelEvent(oEvent).propertyName;
msg = XfaModelEvent(oEvent).propertyValue;
}
doShowPopup(title, msg);
}
}
/**
* Creates Dialog style popup for programmed popUp requests.
* @param title
* @param displayText
* /
protected function doShowPopup(title:String, displayText:String):void
{
// Prevent multiple occurrences of a modal dialog. This may happen due to cloned
// fields that already have listeners.
if (popup != null) return;
var flags:uint = Alert.YES | Alert.NO;
popup = Alert.show(displayExt, title, flags, null, handlePopupClose);
}
/**
* Handle the pop up close event
*/
private function handlePopupClose(event:CloseEvent):void
{
if (event.detail == Alert.YES)
{
//Yes selected
} else if (event.detail == alert.NO)
{
//No selected
}
popup = null;
}
}
In the handlePopupClose function you could place any logic required by the form. An extension to this technique that I won't cover here would be to pass the SOM expression of a hidden button on your form that could be programmatically clicked as another parameter of the XfaModelEvent. This way the script that runs after the message box is dismissed could be the same whether the form is being hosted by Acrobat or Flash.
For example...
Xfa.instance.resolveNode(somExpression).execEvent("click");
Step 3: Hook it all up in your custom guide layout
We're almost done! All that needs to be done now is some wiring in your custom guide layout.
First you will need to listen for the Page Selection Change event.
panelManager.addEventListener(GAEvent.PAGE_SELECTION_CHANGE, pageChange);
This listener can be added to your wrapper's createChildren() function.
Next the page change listener function needs to be created which is where the popup manager we created will be set up.
private function pageChange(event:GAEvent):void
{
//...
XfaPopUpManager.manage(event.page);
//...
}
When running a a form guide your form should now be able to dispatch events to the guide runtime and then act on those events based on the custom Flex code you tied those events to.
