Working With Form Actions

To add or edit a form action:

1. Open the form.
2. Click the Actions tab in the form Property Editor.
3. To add a new behavior, click New. To edit an existing behavior, click Edit.
   The Form Actions dialog opens. There are five sections in the dialog:

   • When is used to define events. At least one "When" statement is required.
   • If is used to define conditions.
   • Then is used to define actions. At least one "Then" statement is required.
   • Add Else If provides additional conditions to evaluate if all of the previous conditions evaluate to "false."
   • Add Else provides an action to take if all "Else If" statements evaluate to "false."
   • Click the X to delete a condition or action statement. If you remove a condition, the specified action is always executed.
4. Click Add Event, Add Condition, or Add Action to create statements for the events, conditions, and actions that form the action expression. To edit an existing statement, click the links and change values.

   If you create multiple conditions within a single section, by default, the statements are connected with AND logical operators. To switch to OR logical operators, hover over the section, select the down arrow that appears at the top right of the section, and then select 'Or Conditions'. To switch to AND logical operators, select 'And Conditions'. All conditions within a single section will use the logical operator you selected; you cannot combine AND and OR logical operators within a single section.

   If you create multiple events within a single section, the statements are connected with OR logical operators.

5. The statement can include links, such as a field, expanded, or <. For example, if you click the a field link, a list of fields is presented and you can select or search for a field. If you click the expanded link, a list containing "expanded" and "collapsed" is presented. If you click <, a list of conditional operators is presented. Click each link and make a selection to complete the statement.
   Important: Design elements such as fields and controls must exist on the form before they can be used in events or actions. An exception to this is a condition that specifies a field value, such as Age > 40.
   Note: If a rule is used in a condition, and the rule uses an application variable, an administrator can override the value of the variable at the project level in SBM Application Administrator. For more information, see the SBM Application Administrator Guide or online help.

   In some cases, a dialog box prompts you to provide additional information. The following table describes the dialog boxes.

   Link Text	Description
   a regular expression	Select Custom and enter the regular expression in the box; or select a predefined expression, such as Match an email address. Select the Ignore case check box if you want to make the regular expression case insensitive.
   a time	Select Specific time and enter or scroll to the appropriate time; or select Now. Click Clear to remove your selection and return the time to its default value.
   a color	Select a color from the color palette. Click More Colors for additional colors and the ability to use the RBG model to specify numeric values. To reopen the palette and change a color, click the RGB value in the statement.
   a string	To display specific text, enter the text. To use an empty string, select Empty string.
   a value	The dialog box depends on the design element. For example: For a Text field, enter specific text, insert a string reference (see Using the String Builder Tool), or select Empty string. For a Binary/Trinary field, select one of the values. For a Selection field or an input control such as a list box, move fields from the Available Values box to the Selected Values box. If more than 10 values are available, you can search for values to add to the statement. For a User or Multi-User field, you can select "None" or "Current User." For a JavaScript, enter the source code in the box if you need to extend the functionality provided by the wizard. The user will not see the source code. If a JavaScript is used in a condition ("a JavaScript evaluates to true or false"), use the following syntax: return expression; Note: If a JavaScript has no more than one semicolon, the system will prepend return if it is missing. Alternately, you can use the string builder tool to insert references to table fields and form controls. For information about this tool, see Using the String Builder Tool. Important: If the code you type in this field includes any opening or closing braces ("{" or "}"), precede each of them with a backslash ("\"). Otherwise, SBM Composer tries to interpret the text inside of the braces as the name of a field or control on the form. This prevents the form from working properly. (If you paste the brace, you are prompted whether you want a backslash to be added. If you use the Treat '{' as a literal option in the string builder tool, a backslash is automatically added.) If you are using string substitution to initialize a JavaScript string constant, you must use the STRING_ESC() macro. This ensures that special characters are correctly encoded for use in this context. Use the string builder tool instead of including references to controls, fields, or other form artifacts in the JavaScript source code. When you create a generic form action or custom control, do not reference another control that exists on the form because the form action or custom control will be portable across forms that may not have the same fields and controls.

6. The Enabled check box is selected by default if the action expression is valid. If you do not want the action to be used right away, clear this check box.
7. Click the OK button to complete the expression and add it to the Actions tab so it can be used by the form.

You can copy expressions within a form action and then modify them. For example, if you have an expression that enables certain fields depending on the value of a selection field and you want other fields to be enabled when the selection field contains a different value, you can duplicate the expression and modify the condition, action, or both as needed.

To copy an expression:

1. Select the action and then click Edit.
2. Rest your cursor over the section with the "if" and "then" statements and then click the down arrow at the top right of the selected section.
3. Do one of the following:
   • Select Copy Conditions and Actions to new Else If if you want to copy both the conditions and the actions.
   • Select Copy Actions to new Else if you want to copy only the actions.
4. Modify the new expressions as needed.