The FILE_EDIT Widget

The FILE_EDIT widget allows a user to edit a Microsoft Word document on their local computer and then save it to the server. A document can be created automatically from a template where the template details can be set before the document is presented to the user for editing.

A UIM page containing the FILE_EDIT widget will only operate in the main content panel of the application. If such page is opened in a modal window then the modal will close immediately and the page will be loaded in the main content panel.

The widget uses a Java applet to manage the interaction between the user's browser and Word. Only the source and target documents and the template details are required. If key details, or other data, are required by the server interfaces that handle the document, these should be provided by page parameters and page-level connections.

Each time the document is saved in Word, the submit button for the page is activated automatically. This triggers the ACTION phase but returns to the same page rather than opening the page linked to by the submit button. Only when the Word document is closed will the next page be opened. This behavior requires that the server interface for the ACTION phase allows multiple invocations for the same editing session and that it saves the document to the database on each invocation.

The first time the Word document is loaded successfully with the template details, it is automatically saved to the server before further editing.

When editing the document, the user has the option to save it. This triggers the normal saving behavior and the page will not be changed when the ACTION phase completes. After the document has been closed, the ACTION phase will be triggered again to open the next page, but this time the server interface will not be invoked and the document (which has already been saved) will not be saved again. Because the server interface is not invoked, it is not permitted to use any property of the ACTION phase server interface in a SOURCE connection of the submit button's LINK element. Typically, the submit button will return to the previous page and will not need a LINK element, so this limitation should have little impact.

Using the FILE_EDIT widget is simple. The WIDGET element should have the TYPE attribute set to FILE_EDIT. Two WIDGET_PARAMETER elements are required:

Table 1. Parameters to the FILE_EDIT Widget
Parameter Name	Required	Description and Connections
`DOCUMENT`	Yes	Defines the source document (usually a template) and the target to which to write the saved document. The parameter must contain a `CONNECT` element with a `SOURCE` set from a `DISPLAY` phase sever interface and a `TARGET` set from an `ACTION` phase sever interface. Both fields should be Word documents. The data-type for both the source and target document must be SVR_BLOB.
`DETAILS`	Yes	The template details that should be set in the document before presenting it to the user for editing. The parameter must contain a `CONNECT` element with a `SOURCE` set from a `DISPLAY` phase sever interface. The details are in XML format, described below. The data-type for the template details must be SVR_BLOB.

The template details must be provided in a simple XML format. An example of the format is shown below:

Figure 1. Sample Template Details

<?xml version="1.0" encoding="UTF-8"?>
<FIELDS>
  <FIELD NAME="personName" VALUE="John Smith"/>
  <FIELD NAME="AddressLine1" VALUE="1 Main Street"/>
  <FIELD NAME="AddressLine2" VALUE="Newtown"/>
  <FIELD NAME="AddressLine3" VALUE="Erehwon"/>
</FIELDS>

It is recommended that your XML uses UTF-8 encoding to handle multi-byte characters. To preserve the correct encoding it is important that any code that manipulates the XML honors the encoding of the document. If the encoding is not honored, this can lead to characters being displayed incorrectly when opened in Microsoft Word.

Each FIELD element identifies the name of a field in the document template and the value to which it should be set.

While editing the document in Word, navigation within the originating browser window is disabled. An alert message will be displayed if any attempt is made to navigate from the page. If the originating browser window is closed, the Word document will stay open, but the editing session will be terminated. Any unsaved changes will not be persisted in database.