Building actions in forms

Combining conditions
Build an action
Rename an action
Revert to the default name
Edit an action
Remove an action
Build a custom result
Setting the zoom level in a PDF form

Use the Action Builder dialog box on the Tools menu to build common interactive capabilities in forms, without writing scripts. Using actions, you can control how you present form objects and data and how the objects and data respond to form filler interaction.

Here are examples of what you can do with actions:

Add buttons that a form filler can click to add or remove sections in the form or rows in a table.
Set the value of a field, such as prepopulating a date/time field object with the current date or a numeric field object with a specific value.
Set the background color of fields.
Hide or show objects or set the focus to a specific field.
Create custom actions by using scripting objects and the function within the scripts.
Build actions within fragments.

Note: To display the actions within a fragment file in the Action Builder dialog box, you must embed the fragments file within the Adobe XML Form (XDP) document or edit the fragment in Designer. The Action Builder dialog box does not display actions within a fragment that you create in a fragment library.

Note: Actions may not work with HTML forms and Guides.

You can add actions to most form fields and objects.

When you click the object link in the Action Builder dialog box, the Select an Object dialog box appears, displaying the objects in the form that you can select to create a condition or result.

You build actions by adding one or more conditions that must be met, and one or more results that occur when the conditions are fulfilled. You can build simple actions with just one condition, where the results begin when that condition is met. Alternatively, you can combine multiple conditions to build more complex actions, where the results can begin at different times depending on the conditions you add.

Designer generates a script for each action and monitors the scripts for changes. If Designer detects that the script has been modified, it performs the following actions:

Stops monitoring the script, giving the form author ownership of the script.
Displays a message on the Log tab in the Report palette, indicating that the script is no longer managed and can be edited.

Designer does not modify unmanaged script in any way.

Designer inserts the script that it generates for an action at the beginning of the script in the Script Editor, before any unmanaged scripts.

The Report palette lists warning messages about broken actions. Broken actions occur when an object that was used to create a condition or result is deleted from the form. Broken actions are indicated in the Action list. A missing object link also appears next to the relevant condition or result. Double-click the warning message in the Report palette to open the Action Builder dialog box and highlight the broken action.

Note: Designer does not monitor changes that you make to radio buttons and choice lists. If you change the items in the list, reorder items, change the display text or save value, or delete a radio button, the action can break without generating a broken action warning.

Combining conditions

If you combine a trigger condition with other conditions, the trigger condition must be met last. Only the trigger condition can start the action results, after all other conditions are met first. As a result, you can add only one trigger condition to an action. For example, you cannot build an action with two trigger conditions, where the form filler is required to click a button and click a check box at the same time. The Action Builder dialog box displays an error message if you add more than one trigger condition to an action. However, keep in mind that an action does not require a trigger condition. You can build an action without adding a trigger condition. If you do not add a trigger condition to an action, the conditions can be met in any order. Any one of the conditions in the action can display the results, after all other conditions are met.

When you add multiple conditions to an action, the Action Builder dialog box sorts the list of conditions, as shown below. The trigger condition (if you have added one) appears at the top of the list. All other conditions are grouped under the trigger condition. The and/or link appears next to the grouped conditions. The and/or link is not available with the trigger condition. When you select and, all conditions in the group must be met before the actions results occur. When you select or, at least one of the conditions in the group must be met before the action results occur.

View full size graphic

A. Trigger condition B. And/or toggle link

Build an action

When you build an action, you add one or more conditions and one or more results. The results occur when the conditions are fulfilled. You can add as many conditions and results as you need. However, you can add only one trigger condition to an action, because the trigger condition must be met last. For example, you cannot build an action where the form filler must click a button and a check box at the same time, to initiate the results. The Action Builder dialog box displays an error message if you add more than one trigger condition to an action.

Note: If you build an action using the ‘is changed’ option for a condition, when the form is viewed in Acrobat or Adobe Reader, the results may not be applied until the field is exited.

For each condition you add, click the object link to open the Select an Object dialog box and choose an object. The Select An Object dialog box only shows the objects in the form that you can use for a condition or result. For each result you add, you select an option in the Select a Result list, and then choose various other options depending on the object. The options available for each result vary depending on the object you select.

Note: If you build an action that adds or removes instances of subforms, be sure to name each subform object. If the action references any unnamed subforms, the action could fail.

Keep in mind that the following results are not compatible with HTML forms or guides.

Attach a File to the Form
Close the Form
Go to a Specific Page
Reset All the Fields in the Form
Save the Form
Set the Zoom Level

Designer generates a default name for each action, which consists of the object name followed by the scripting event that the condition is generated within (<name of object>.<name of scripting event>).

For information on events, see Events.

Note: If you create an action in the Enter event and run the form in Acrobat 7.1.3, the background or foreground color of the field does not change until the user exits the field.

Select Tools > Action Builder.
Click the Add A New Action button.
In the Condition area, click the Add A Condition button.
Click the object link.
Select the object for the condition. Repeat steps 3 and 4 as needed. If you add three or more conditions, the and/or link appears next to the conditions. Click the link to change the relationship between the conditions as needed.
In the Result area, click the Add A Result button.
In the Select a Result list, select a result and then choose options as needed. Repeat steps 6 and 7 as needed.

Rename an action

Click the action name and type a new name. You can give two or more actions the same name.

Revert to the default name

Delete the new name.

Edit an action

Use the Actions dialog box to view and edit the actions in a form. Actions are listed on the left side of the dialog box, and the conditions and results for the selected action appear on the right. Add, delete, and modify condition and results as needed.

For existing conditions, the Select an Object dialog box only shows the object associated with that condition and other objects of the same type. To change the object type for an existing condition, delete the condition and then create another condition.

For existing results, the Select an Object dialog box shows all objects in the form that you can select for a result. To change the object for an existing result, select a different object.

Select Tools > Action Builder.
Under Actions, select an action, and select options as needed.

Remove an action

You can remove an action from a form at any time.

Select Tools > Action Builder.
Under Actions, select the action to remove.
Click the Remove An Existing Action button.

Build a custom result

You can create a custom result for an action by using a script object that contains a function. A script object is an object you can use to store JavaScript functions and values separately from any particular form object.

Note: Designer does not validate parameters and return values. Ensure that the parameters you type are correct and the return value is valid.

Select Tools > Action Builder.
Click the Add A New Action button.
In the Condition area, click the Add A Condition button.
Click the object link.
Select an object for the condition. Repeat steps 3 and 4 as needed. If you add three or more conditions, the and/or link appears next to the conditions. Click the link to change the relationship between the conditions as needed.
In the Result area, click the Add A Result button.
In the Select a Result list, select Call A Script Object Function.
Click the Call Script Object link and, under Variables, select the script object.
Select a function from the list.
Type the parameters in the box. Example: Call script *(script object)* function (function name) with parameters *(funcParam1, funcParam2)* and "(No Return Result)".
(Optional) Select Assign Return Result To, click the object link, and select an object for the return result.

For more information, see Creating and Reusing JavaScript Functions .

Setting the zoom level in a PDF form

When a user opens a PDF form in Acrobat or Adobe Reader, they see the initial view of the document. You can build an action to set the initial viewing area of a PDF to a specific zoom level or page magnification. For example, you can set the zoom level to a specific percentage of the page size or to automatically fit the width or height of the page.

Select Tools > Action Builder.
Click the Add A New Action button.
In the Condition area, click the object link.
In the Select An Object dialog box, select the name of the form at the top of the form hierarchy. The default name is form1.
Click OK.
In the Condition area, select When Form <form name> Has Finished Loading.
In the Select a Result list, select Set The Zoom Level.
In the Set Zoom To list, select the option you want.
Click OK.