Actions are form-initiated acts that execute automatically. They can be of any of the following types:
- cancel - Closes the form; if any changes were made to the form since the last save or submit, then the user is informed that the form has changed and is allowed to choose whether the cancellation will proceed.
- link - Performs all requests specified by the url options in the current item.
- replace - Performs a link followed by a cancel.
- submit - Initiates the form processing applications identified in the url options of the current item.
- done - Performs a submit followed by a cancel.
- print - Prints the form on a local printer.
- display - Displays an enclosed file. The web browser will choose the appropriate viewer according to the file's MIME type.
- pagedone - Moves to the page specified in the url option. This closes the current page and replaces it with the new page. All fields containing error checking on the current page must be correctly filled out before it can be closed.
- (no type) - If you omit the type for an action, it will still work, but instead of predefined behaviour, you can write custom computes that will allow you to do anything you like to the form when the action is activated (within the bounds of what is possible in XFDL, of course.)
You can configure your actions to occur only once, or to repeat at specified time intervals. If the action
occurs only once, you can set a time delay on its execution. For more information on automatic actions
and time delays, see the XFDL Specification.
Actions are frequently used in XFDL almost as a function in a procedural language would be. You can
define a series of operations, store variables and “call” the action from the form. Actions are
particularly useful in this sense when you need to do something that a form item cannot do - for
example, an item cannot delete itself, so if you have a “delete row” button at the end of every row in a
table, you will need to set up an action that will, given a row number, delete all the items in that row.
<custom:delete_row xfdl:compute=”toggle(activated,’off’,’on’) == ‘1’ ? destroy(‘itemref_’ +. row_to_delete,’item’)... + set(‘active’,’off’) : ‘’”></custom:delete_row>
The important things to note here are as follows:
- When you use an action like this, its default active state must be ‘off’ and it must be set to run once with a delay of zero. This run-once setting actually means ‘run once, when active is turned on’ so this provides an easy way to control when the action fires.
- The action must turn itself off when it has completed its operations, so it can be turned on again when needed.
When another form item needs to “use” the action, it will typically first pass any information the action
needs (in the above example, the row number) then it will set the action’s ‘active’ option to ‘on’, like
<custom:set_action xfdl:compute=”toggle(activated,’off’,’on’) == ‘1’ ?
set(‘delete_row_action.active’,‘on’) : ‘’”></custom:set_action>
You can also use custom actions to mimic “background” processes on the form. The example form
provided, actionClock.xfd, does this by having an automatic action fire once every second and update a
label item with the current time.
Open the form to see what it does, then open the form in the Designer to look at the action’s source
code. Since actions have no visible components to select in the Designer, it will be necessary to select
the Page or Form code view and move to the "Clock_Action" action to see the compute. Alternatively,
you can open the "Tree View" and select the "Clock_Action" action, then hit F9, or simply open the
form in a text editor.