Designer Action Builder

 

LiveCycle Designer Action Builder

J.P. Terry

www.smartdoctech.com

 

J.P. Terry is the CEO of SmartDoc Technologies (www.smartdoctech.com), a leading provider of solutions with Adobe LiveCycle and Adobe Experience Manager (AEM) document services. SmartDoc has developed paperless systems for Fidelity Investments and Merrill Lynch and is an Adobe Business Partner. SmartDoc has offices in New York; New Jersey; and Beijing, China. J.P. is an ACI (Adobe Certified Instructor) and an ACE (Adobe Certified Expert) in Adobe LiveCycle technology and the author of 3 Adobe Press books including Adobe LiveCycle Designer, 2nd Edition (November, 2013).

Prerequisite knowledge

Some experience with Adobe LiveCycle Designer

Required Adobe products (retail)

  • Adobe LiveCycle Designer
  • Adobe Acrobat

Sample files:

The sample file for this example is part of the book’s sample files package that can be found at:

www.smartdoctech.com/support

www.smartdoctech.com

 

Contents 
 

How it works

Exercise 1: Adding a Message Box for a Form Submission

Exercise 2: Highlighting Required Fields

Exercise 3: Calling a Script Object Function

The Limits of Action Builder 

 

Introduction 

If you need the benefits of scripting but don’t have the time to master JavaScript, Designer’s Action Builder may be the tool you’re looking for. Action Builder is a script-creating assistant that you can access in Designer by selecting Tools > Action Builder. You select form objects, conditions, and results and Action Builder generates the script for you. For instance, you can select a Button object and indicate that you want an action performed when the button is clicked (Figure 1).

 

Figure 1: Designer’s Action Builder with message box action.
Figure 1: Designer’s Action Builder with message box action.

 

You can define the result of the action as a message box. Action Builder will generate the script and add it to your Button object’s click event in the Script Editor. When a user clicks the button at runtime, the pop-up message box will appear.

 

How it works

You use the Action Builder to specify one or more conditions and one or more results that should occur when the conditions are met. Designer will interpret your actions and associated results and create JavaScript for your form. This JavaScript is added at the beginning of the event in your Script Editor before any script that you manually add. Designer treats an Action Builder script as a managed script and it monitors the script for changes. If there are no changes, you can go back to the Action Builder and edit the action that generated the script. However, if you edit the script manually in the Script Editor, Designer will break the link between the script and the action in your Action Builder dialog box. In this case, you are free to work with the script as if it was entered manually. Designer will stop monitoring the script and display a message in the Log tab of the Report palette.

 

Exercise 1: Adding a Message Box for a Form Submission

Follow these steps to use Action Builder to create a script that will display a message box when the form is ready to be submitted. All sample files are from, “Adobe LiveCycle Designer, Second Edition” and can be downloaded for free from www.smartdoctech.com/support.

1.    Open the changeOfBeneficiaryActions.xdp form from the Samples folder.

2.    Select Tools > Action Builder to open the Action Builder dialog.

3.    Click the Add a new action button

4.    Double click on (New Action) in the Actions list and rename the action to Submit Form.

5.    Create a condition by clicking the object link in the Condition panel.

6.    Select the submitForm button in the Select an Object dialog and click OK. A condition has been created.

7.    Click the green plus sign next to Condition (Figure 1) to add a second condition.

8.    Click (object) in the second Condition.

9.    Select the approved check box in the Select an Object dialog and click OK. A second condition has been created. A warning has also been added to the two conditions to let you know that you now have multiple trigger conditions for one action.

10. Change the “is clicked” property to “is checked” in the second condition. By changing this condition you are eliminating the second trigger condition, therefore the warning is removed.

11. Select Show a Message Box from the Result drop down.

12. Enter “Your form is ready to be submitted.” as the message.

13. Enter “Ready for submission” as the title and click OK. You can also change the message box icon here if you wish but the default one is perfectly fine.

14. Select Preview PDF to see your script in action.

15. Select the I approve these updates check box.

16. Click the Submit Form button. You will see the message box (Figure 2).

 

Figure 2: Your users will see this message box at run-time.
Figure 2: Your users will see this message box at run-time.

 

Exercise 2: Highlighting Required Fields

In the exercise, you will use Action Builder to highlight required fields in your form.

1.    Select Design View to start this exercise.

2.    Select Tools > Action Builder.

3.    Click Add a new action and name it showRequiredFields.

4.    Create a condition by clicking the object link in the Condition panel.

5.    Select the showRequiredFields Button object in the header subform of page1 and click OK.

6.    Create a result by selecting “Set the Background Color of a Field” in the dropdown list.

7.    Click the object link and select the primaryName object.

8.    Select yellow in the drop-down color list.

9.    Click OK to complete your action. Designer automatically adds custom JavaScript to your button’s click event.

10. Select the showRequiredFields button and review the JavaScript in the button’s click event. The majority of the lines are JavaScript comments.

11. Select the Preview PDF tab to see the new script in action. When you click the showRequiredFields button, the primaryName field changes to yellow.

12. You can add additional results to the same condition by returning to the Action Builder. Select Design View and click Tools > Action Builder.

13. Select the showRequiredFields action.

14. Click the green plus sign on the right to add a new result. Repeat steps 6–8 for the other fields in the primaryItem subform, and click OK in the Action Builder dialog box when you are done.

15. Select the showRequiredFields button and review the JavaScript in the button’s click event of the Script Editor. If you don’t see the Script Editor, select Window > Script Editor.

16. Select the Preview PDF tab to see the new script in action.

 

Exercise 3: Calling a Script Object Function

In the exercise, you will use Action Builder to call a Script Object Function from a button’s click event.

1.    Select Design View to start this exercise.

2.    Select Tools > Action Builder.

3.    Click Add a new action and name it callSOFunction

.4.    Create a condition by clicking the object link in the Condition panel.

5.    Select the callSOFunction button on the signature form and click OK.

6.    Create a result by selecting “Call a Script Object Function” in the dropdown list.

7.    Click the object link, select the required Script Object and click OK.

8.    Select the requiredValidation function from the drop-down list. You don’t need to worry about the parameters or the return object. Click OK to finish your action.

9.    Select the Preview PDF tab to see the new script in action.

10. Click the “Call SO Function” button and you will see a message box and the required fields highlighted in yellow.

 

The Limits of Action Builder

Although Action Builder is a useful tool, an experienced JavaScript programming can create JavaScript that is more efficient and easier to manage. Follow these steps to see an example of the type of script that Action Builder creates.

1.    Select Design View to start this exercise.

2.    Select the callSOFunction button in the signature subform at the bottom of your form.

3.    Go to the Script Editor and select the click event in the drop-down list in the upper left of the Script Editor.

Action Builder added the following script to the click event.

//+ GENERATED - DO NOT EDIT (ID:98ED712F-1855-448B-99FF-C08B70BFB1EE CRC:1298018225)

//+ Type: Action

//+ Result1: Custom("$Node2","requiredValidation","","noreturn")

//+ Node2: form1[0].#variables[0].required[0]

//+ Node1: form1[0].page1[0].signature[0].callSOFunction[0]

//+ Condition1: Button("$Node1","click")

//+ ActionName: callSOMethod

this.resolveNode("required").requiredValidation();

//-

 

Although this script works, it relies on the .resolveNode() method which is less efficient than calling the function of the script object directly with this line of JavaScript.

required.requiredValidation()

 

As a best practice, you should limit the number of times you call the .resolveNode() and .resolveNodes() methods in your scripts. This is particularly important when your form has many objects and a deep subform hierarchy. By using direct paths in your JavaScript, your host application (Acrobat or Reader) will not need to iterate through a complex form structure in order to resolve the node reference. As you work with Action Builder, you will see that it relies heavily on the .resolveNode() method. However, if you are new to JavaScript and you want to add automated feature to your LiveCycle Designer forms, Action Builder is a very useful tool. You can think of it as your personal JavaScript Assistant.

 

Where to go from here

For more information and exercises on LiveCycle Designer, see J.P.’s new Adobe Press book, “Adobe LiveCycle Designer, Second Edition”. You can download the sample file for this exercise at www.smartdoctech.com/support.