Form Events

 <  Day Day Up  >  

There are six form events:

  • OnLoad ” Occurs when a document is loaded.

  • OnClick ” Occurs when a button form control is clicked.

  • OnSwitchView ” Occurs when a user switches views or the appearance of a view is changed.

  • OnSubmitRequest ” Occurs when the user attempts to submit the XML data from a form.

  • OnVersionUpgrade ” Occurs when there is a mismatch between the version of a form ( .xml file) and its corresponding form template ( .xsn file).

  • OnAfterImport ” Occurs after a form has been merged with another form.

Each of these events is described in the following sections.

The OnLoad Event

The OnLoad event occurs after a form has been loaded, but before the default view has been initialized . Thus, the OnLoad event gives the developer the opportunity to make checks or to initialize aspects of the form before it is displayed to the user.

To create scripting code that handles the OnLoad event, select Tools, Script, On Load Event. The Script Editor opens with the skeleton of a function or subroutine automatically created, depending on whether you have selected to use JScript or VBScript for the form template.

One use of the OnLoad event is to check whether a form has been digitally signed. Depending on circumstances, it might make sense to not allow the XML of the form data to be modified. This can be achieved with code like this:

 XDocument::OnLoad(eventObj){ // Check if the form has been digitally signed if (XDocument.IsSigned)  return; // If the form hasn't been signed then other script code // can go here } 

Notice that because the OnLoad event occurs in relation to an XDocument object, the function name recognizes it.

Another possible use of the OnLoad event might be to display an important message to users:

 XDocument::OnLoad(eventObj){ XDocument.UI.Alert(""An important user information message goes here.""); } 

The OnClick Event

The OnClick event is available only on button form controls in InfoPath 2003. Event handlers for the OnClick event may be created in either VBScript or JScript by using the InfoPath user interface. Right-click on the button form control and select Button Properties. In the Button Properties window, create a meaningful label and Script ID for the form control and (checking that Script is selected in the drop-down menu) click on the Microsoft Script Editor button. The Script Editor opens with an automatically created skeleton function or subroutine.

The object passed to the event handler for an OnClick event is a DocActionEvent object.

The OnClickSwitch.xsn form template, which is included in the download, uses event handlers that respond to the OnClick event on a button on each of two simple views to allow the user to switch between the two views.

The code for one of the event handlers for OnClick is shown here:

 function ReturnToDefault::OnClick(eventObj) {  XDocument.View.SwitchView("View 1"); } 

Another possible use for the OnClick event would be to check that all form controls in a view have been filled in (either filled in at all or filled in correctly) before the user is allowed to, for instance, switch views.

The OnSwitchView Event

The OnSwitchView event occurs when the user elects to switch between views available in a form template. An event handler that responds to the OnSwitchView event might be useful when, for example, the form developer has provided a custom task pane to give guidance on how to fill in form controls in a particular view and wants to ensure that the custom task pane is open whenever the view is displayed.

To add scripting code that responds to the OnSwitchView event, select Tools, Script, On Switch Views Event. (Notice that the menu uses "On Switch Views" (separate words and plural), whereas the event is one word ( OnSwitchView and singular). The Script Editor opens with an automatically created skeleton for the OnSwitchView event.

One possible use for the OnSwitchView event is to provide information to a user ”for example, specific information about the view to which the user has switched.

The OnSubmitRequest Event

The OnSubmitRequest event is fired either from the InfoPath user interface (you select Script in the drop-down menu in the Button Properties window, or the user selects Submit on the File menu) or programmatically using the XDocument.Submit() method when you choose to add script code to submit the form data using a button form control.

The argument to the event handler for the OnSubmitRequest event is a DocReturnEvent object. The ReturnStatus property of the DocReturnEvent object indicates whether submission was successful.

The OnVersionUpgrade Event

The use of W3C validation, rules-based validation, and scripted validation in InfoPath form templates raises the issue of keeping validation rules on a user's machine correctly synchronized with the XML structure expected to be submitted to the server-side process.

Consider the situation in which a form template is downloaded and a blank form is saved to a user's machine before a lengthy business trip. A cached version of the form template is stored on the user's hard disk. The longer the trip, the more likely it becomes that the form template at the published location might be changed. Of course, if the business situation has been well thought out, published form templates are unlikely to change frequently; but with ongoing changes in business focus, there will come a time when the published form template changes.

However, the user who has been offline for, let us say, several days, is unaware that the expected structure of the XML data has changed. When the user returns to base or otherwise obtains an Internet connection and attempts to open the form with a view to submit it, an error could potentially occur, depending on the type of change made in the published form template. This is where the version of the published form template and the version of the form the user intends to submit are compared. If the versions of the form on the user's machine and the form template at its published location do not match, the OnVersionUpgrade event occurs.

If the developer has provided an event handler for the OnVersionUpgrade event, the XML DOM of the form on the user's machine is upgraded:

 function XDocument::OnVersionUpgrade(eventObj) {  // Test if a <FaxNumber> element node exists  if (!XDocument.DOM.selectSingleNode(""/Contact/Details/FaxNumber""))  {  // If there is no <FaxNumber> element node then  try  {  // First create the new <FaxNumber> element node  var objNewFaxNode =  XDocument.DOM.selectSingleNode("/Contact/Details").ownerDocument.createElement."FaxNumber");  // Then add the new element node to the DOM  XDocument.DOM.selectSingleNode("/Contact/Details").appendChild(objNewFaxNode);  // Set the ReturnStatus to true, indicating success  eventObj.ReturnStatus = true;  } // end try  catch(ex)  {  XDocument.UI.Alert("The <FaxNumber> element could not be added");  // Set ReturnStatus to false indicating failure  eventObj.ReturnStatus = false;  } // end catch  } } 

If the event handler for OnVersionUpgrade in the later version of the form template successfully adds the needed new element node corresponding to a FaxNumber element in the previous example, the data from the form can be successfully submitted because the form now corresponds to the structure expected by the revised published form template.

The example shown addresses a very simple change in the DOM structure. It makes sense to keep version changes of form templates to a minimum so that the code needed for the event handler for the OnVersionUpgrade event is kept simple. An important consideration to keep in mind if multiple versions of a form may exist is that any changes in the DOM in the OnVersionUpgrade event handler must be carried out in an order that allows operations to succeed. For example, if the original change to the form template added a Details element and then a later version added a FaxNumber element, you must be sure that you add a FaxNumber element node (which is a child node of Details ) only after it has been confirmed that a Details element node exists or has been added.

The OnAfterImport Event

The OnAfterImport event must be created manually, and you cannot use the InfoPath user interface to create a skeleton event handler for the event. The OnAfterImport event fires when a form is imported into another form.

The OnAfterImport event is relevant when you want to combine the XML data from several InfoPath forms.

 <  Day Day Up  >  


Microsoft Office InfoPath 2003 Kick Start
Microsoft Office InfoPath 2003 Kick Start
ISBN: 067232623X
EAN: 2147483647
Year: 2004
Pages: 206

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net