Availability

Introduction

The Action editor allows you to implement simple actions in your form. The basic philosophy goes as follows:

• React to an event occurring on the form, such as the form being loaded or a user action
• Call an HTTP or database service
• passing in parameters from the form
  
• receiving parameters back from the service
• Use the returned parameters to update the form

NOTE: Actions are tightly coupled with services. In the future, support might be added for actions which do not require services.

Basic action configuration

This is the meaning of the fields of the dialog:

• Action Name. This is the name of the action, as seen by Form Builder. Must start with a letter, and may not contain spaces.
• React to. The event which starts the action. Can be one of the following:
• Value Change. A control's value has changed.
  
• Value Change or Form Load. A control's value has changed OR the form just finished loading.
  
• Activation. A button has been clicked, or the "Enter" key has been pressed in a text line.
  
• Form Load. The form just finished loading.
• Condition. [SINCE: 2011-12-01]
• Run always. Run the action independently from the form mode.
• Run on creation only. Run the action only in creation mode, that is when the user creates new data, as opposed to editing, viewing, emailing, or generating a PDF.
• Control. Except for the Form Load event which does not depend on a particular control, this specifies which control the action reacts to.
  
• Service to Call. The service to call as a response to the action.

Like for services, once your action is defined, the Save buttons saves it to the form. You can come back to it and modify it later by clicking on the Edit icon next to the action name. You can also delete the action using the trashcan icon.

Passing parameters to the service

• Set Service Request Values.
• Used with HTTP services only
• Function: uses the value of a control and stores that value into the body of the XML service request.
• Source Control. Specifies the control whose value must be used.
  
• Destination XPath Expression. The expression must point to an element or attribute node of the request body defined in the HTTP service under "XML Request Body"
• You can add as many such rows as you want using the "+" button, and remove existing entries with the trashcan icon.
  
• Set Database Service Parameters.
• Used with database services only.
• Function: uses the value of a control and sets that value as the Nth query parameter of the database service.
• Source Control. Specifies the control whose value must be used.
• Parameter Number. To set the first query parameter, use the value "1" (without the quotes), the second, "2", etc.
  
• You can add as many such rows as you want using the "+" button, and remove existing entries with the trashcan icon.

Handling the service response

The following is used if the service call is successful:

• Set Response Control Values.
  
• Function: uses a value returned by the service to set a control's value.
• Destination Control. Specifies the control whose value must be set.
• Destination XPath Expression. The expression must point to an element or attribute node of the response body returned by the service.
  
• You can add as many such rows as you want using the "+" button, and remove existing entries with the trashcan icon.
• Set response Selection Control Items.
• Function: uses values returned by the service to set a selection control's set of items (itemset) with them.
• Destination Selection Control. Specifies the selection control whose items must be set. Only selection controls appear in this list.
• Items.
• The XPath expression must point to a set of element or attribute nodes of the response body returned by the service.
• For each node returned, an item is created.
  
• Label. The XPath expression must return the text of the label for an item. It is relative to the item expression.
  
• Value. The XPath expression must return the text of the value for an item. It is relative to the item expression.
• All the previous items of the selection control are replaced with the items specified here.
  
• You can add as many such rows as you want using the "+" button, and remove existing entries with the trashcan icon.

Examples

The following screenshot shows a simple action posting a status update to Twitter:



In this example:

1. The action is named "tweet"
2. It reacts to the activation (click) of the "Tweet!" button (with name "tweet-button")
3. [SINCE: 2011-12-01] It always run (as opposed to running only upon creation)
4. When the button is activated, it calls the service named "twitter-update"
5. Before calling the service, but after activation of the button, the value of the field "Tweet Here" (with name "twitter-message") is used to set the value of the <status> element of the request body, as specified in the service.
6. No action is taken upon receiving a response from the service.
   

If the field "twitter-message" contained the string "Excited today about the new Orbeon Forms release", the service's request body will look like this:

How that XML document is actually sent to the service depends on the parameters set in the HTTP Service Editor dialog. For example, the XML document might be POSTed to the service as is, or it might be serialized as HTML form data.

The following shows a call to a service which returns new items for a selection control:


In this example:

1. The action is named "populate"
2. It reacts to the activation (click) of the "Populate" button (with name "populate-button")
3. When the button is activated, it calls the service named "echo-service" (which just returns the data that was sent to it)
   
4. Before calling the service, but after activation of the button, the value of 4 fields is read and set into the request body
5. When the service call successfully returns
• All the elements /items/item are iterated and one item is created for each of those
  
• For each one, the label and value children elements are used to determine the item label and value
• The items are set on the "Values" control (with name "list")
  

For example, if the response looks like this:


Three items are set on the "Values" control in the order returned by the "Items" XPath expression:

• One with label "Cat" and value "cat"
• One with label "Dog" and value "dog"
• One with label "Bird" and value "bird"

Namespace handling