Basic Scripting
Scripting in LiveCycle Designer is simple enough that you can begin today but robust enough that you won't be bored even after years of programming. If you don't know any JavaScript, don't worry, the examples in this book will help get you started. If you are a JavaScript god, that's great, LiveCycle Designer gives you a chance to show off your divine powers.
Let's begin by looking at two examples that illustrate how simple and how complicated JavaScript can be in your LiveCycle Designer forms. After looking at these two examples, I'll discuss the basics of creating variables and referencing Designer objects.
Your First Scripts
Many prebuilt scripts are available in the Designer program and in the Help System. This section covers the predefined scripts that are built into the Designer program.
Predefined scripts on the Insert menu
Some basic scripts are built into the objects on the Insert menu. Follow these steps to learn more about the basic scripts contained on the Insert menu.
- Add a Text object to a blank form. Type the following phrase into your Text object: My form currently has X page(s).
- Highlight the "X" in your Text object and select Number of Pages from the Insert menu. Designer changes your X to a Numeric Field object represented by the "##" characters (Figure 4.7).
Figure 4.7 Inserting a Number of Pages script into a Text object.
- Select this Numeric Field object, and you will see that Designer has added the following script to its Layout Ready event:
this.rawValue = xfa.layout.pageCount();
This script calls the pageCount property of the Layout DOM and assigns the value to the rawValue property of the current object, which is the Numeric Field. The keyword "this" always refers to the current object in Designer JavaScript. - Select Preview PDF. You should see the following line of text: My form currently has 1 page(s).
- Go back to Design View and select Insert > New Page.
- This time when you select Preview PDF, you should see that your text has changed from 1 page(s) to 2 page(s). You can follow this method to review the other scripts that are predefined in the Insert menu objects.
Predefined scripts in Custom Objects
Some scripts are also built into the objects in the Custom Objects section of the Library palette. The Email object contains a more advanced script than those previously discussed. Drag and drop the Email Address object onto your form. Select the validate event for this object, and you'll see the script in the script editing field of your Script Editor (Figure 4.8).
Figure 4.8 The validation script for the Email Address custom object.
This multiline script begins to hint at some of the power of Designer scripting. The goal of this script is to validate the email address that a user enters. Here's how it works:
- A form filler enters an email address into the text field. The validate event of the text field fires when the user exits the field by tabbing, pressing the Enter key, or selecting another object.
- The script runs when the validate event is fired. The script first creates a new regular expression object and assigns it to the variable r.
- The script then assigns a regular expression to r by using the compile method of r.
- The form filler's entry is now tested against the regular expression by calling the test method of the variable r. The results of this text are stored in a new variable called result.
- If the entry matches the regular expression, the result variable is set to True and the validation passes. However, if the entry does not match the regular expression, the validation fails and the script returns the value of False. If the validation fails, the user will see the Validation Script Message appear in a pop-up message box (Figure 4.9).
Figure 4.9 The Validation Script Message appears to the user in a warning message (left) and to the form designer on the Value tab of the Object palette (right).
Properties
So far, you have been setting the property values for your form objects through the interface tools at design time. You can also set and get these properties through script at runtime. Open the form that you created from the XML Schema in Chapter 2, "Form Creation." You will use this form to work through some examples of setting and getting object properties through scripting.
Setting properties
Before you begin, move all of the objects so they are aligned in a vertical column. Add two new Text Field objects called currentShirtSize and previousShirtSize directly below the shirt size Drop-down List object. Reorder the objects in your Hierarchy menu so it matches the order on your form. Your form and Hierarchy palette should look like Figure 4.10.
Figure 4.10 The new hierarchy and layout of your form.
- Drag and drop a Button object onto your form and name it setProperties. Set the caption of the button to Set Properties in the Object palette.
- The Username object has a default value of "your name here." You can change this value with script by setting the rawValue property of the Username object. Select the setProperties Button object and select the click event from the Script Editor's Show menu. Type in the following line of JavaScript.
username.rawValue = "John Warnock";
As you typed the period after the object name, you might have noticed Designer's statement completion functionality. When you enter a period directly following an object or property name, Designer displays a list of available properties and methods. The statement completion list only appears when you access objects, properties, and methods of the XML Form Object model. It lists context-sensitive properties and methods of standard JavaScript. - Type in another script directly below your previous script. Be sure to end each line with a semicolon:
username.font.typeface = "Courier New";
- Select Preview PDF, and you will see that the Username object now displays a value of "John Warnock" in the Courier New typeface.
- Add the following lines of script to set other property values:
pantsWaist.border.edge.color.value = "255,0,0"; pantsLength.presence = "hidden" numberOfPants.presence = "invisible"
- To set the date, you need to first create a new JavaScript Date object and assign it to a variable named d. In the second line of script, you will call the toString() method of your Date object and assign the value to the rawValue property of your orderDate object:
var d = new Date(); orderDate.rawValue = d.toString();
- The final two scripts set the caption and background properties of a text field. Add these two lines to your setProperties click event to highlight the Username field in yellow and set its caption to "Full Name":
username.caption.value.text.value = "Full Name"; username.ui.textEdit.border.fill.color.value = "255,255,0";
Getting properties
You can also use script to get object properties at runtime. You saw an example of this earlier in the chapter in your first script example from the Insert menu:
this.rawValue = xfa.layout.pageCount();
Two other scripts that are already in your form retrieve form object properties. These scripts are in the validate event of the pantsLength and pantsWaist text fields. You saw how these scripts worked when you first previewed this form in Chapter 2. Since they are similar, let's look at the script in the pantsLength object. If a user enters a number lower than 28 or higher than 40 into the pantsLength text field, the validation will fail and a warning message box will appear (Figure 4.11).
Figure 4.11 A warning message box.
Select the pantsLength text field and look at the script in the validate event:
this.isNull || (this.rawValue >= 28 && this.rawValue <= 40);
This script retrieves two properties of the text field: the isNull property and the rawValue property. The JavaScript keyword "this" always refers to the current object, which in this case is the pantsLength text field. The double pipe "||" between the two statements is the JavaScript logical OR operator. The script will validate to True if either statement is true. In this case, if the text field is null or the text field contains an entry between 28 and 40, the script will return True. Because you are using the OR operator, you only need one statement to evaluate to true in order for the field to pass the validation.
The warning message is system generated. You can add a custom message by entering a sentence into the Validation Script Message field on the Value tab of the Object palette. Enter the following Validation Script Message to make your form a little more user friendly: Sorry, we don't have that size. Please enter a length between 28 and 40. You can improve this interaction even more by providing notification before correction, as discussed in Chapter 2.
Getting and setting properties
The following example pulls everything together by getting and setting property values. Open the file formFromASchema_withVariables from your Samples folder.
- Select the shirtSize Drop-down List object and locate the change event under the Show menu.
- You will see the following script that gets and sets property values:
currentShirtSize.rawValue = xfa.event.newText; previousShirtSize.rawValue = xfa.event.prevText;
These scripts get a property value from the xfa.event object and use it to set the rawValue property of a text field. More detail about the xfa.event object is provided in the upcoming section "The Form Object Model." - Select Preview PDF and make a few different choices in the shirtSize Drop-down List. You will see that the currentShirtSize text field is populated with the current choice, and the previousShirtSize text field is populated with the previous choice (Figure 4.12).
Figure 4.12 The script runs on the change event of the Drop-down List.
Variables
A variable is a symbolic representation that refers to a place in computer memory that holds a value. Variables are advantageous because they enable you to define a value in one location but refer to it from many. When you need to change the value, you do not need to go back to each variable reference. You only need to go back to the one location where the variable is defined to make your change. All other locations that refer to the variable will be updated. This section focuses on the following two primary variable types:
- Form variables: Are declared and assigned in the Variables tab of the Form Properties dialog box.
- Script variables: Are declared and assigned in your scripts.
Form variables
A form variable typically acts as a placeholder for a value that you might have to change in the future. For instance, you can create form variables for state tax rates (Table 4.1). When you need to calculate the sales tax, you reference the form variable in your script. When you need to change the tax rate, all you have to do is open the form variable in the Form Properties dialog box and make the change (Figure 4.13). Because you referenced the form variable, not a specific numeric value, you do not need to update the tax rate in multiple locations on your form. Form variables are global in nature, which means that you can access them from any part of your form. The values of your form variables will reset each time the form is opened.
Table 4.1. State Sales Tax
State |
Current Value |
Future Value |
Connecticut |
5 % |
Probably higher |
New Jersey |
6 % |
Probably higher |
New York |
7 % |
Probably higher |
Figure 4.13 Entering a form variable into the Form Properties dialog box. Your form variable values will be reset to their original values each time the form is opened.
Follow these steps to create a form variable:
- Select File > Form Properties.
- Select the Variables tab and click the green button with the plus sign.
- Enter varUsername as your variable name and then enter Charles Geschke as your variable value (Figure 4.13).
You can now make a reference to this variable from anywhere on your form. Go back to your setProperties button and change the Username script so it refers to this variable:
username.rawValue = varUsername.value;
This example uses two different property values to refer to similar information. When you need to access the value of an XFA field or form object, use the .rawValue property. When you need to access the value of a JavaScript variable or object, use the .value property.
If you are working in FormCalc, you can retrieve the value of the variable without explicitly referencing a value property:
order.#subform[0].fromVariable::click: - (FormCalc, client) ----- username.rawValue = varUsername
- Select Preview PDF and click the Set Properties button. You will see that the new value is "Charles Geschke."
Even though you were able to create a form variable without scripting, you must use scripting to work with your variables in the following ways:
- To access the value of your variable
- To change the value of your variable at runtime
- To apply the value of your variable to a form object
Open the file formFromASchema_withVariables.pdf from your Samples folder. In this example, you will see how the state tax rates are entered as form variables. You will also see two other form variables that track the shirts and pants inventory.
- Select File > Form Properties and click the Variables tab to review the form variables (Figure 4.14).
Figure 4.14 The form variables from formFromASchema_withVariables.pdf.
- Select Preview PDF and click the State Drop-down List object. When you select a state, the state tax amount will populate the tax text field.
- Go back to Design View and select the State Drop-down List object. You will see the following script in the change event of the Show menu:
if(xfa.event.newText == "Connecticut"){ tax.rawValue = ct.value; }else if(xfa.event.newText == "New Jersey"){ tax.rawValue = nj.value; }else if(xfa.event.newText == "New York"){ tax.rawValue = ny.value; }
Notice that each state instance in the script refers to the state variable, not a numeric value. - Select File > Form Properties and click the Variables tab to change the tax rates in your form variables. I bet you always wanted the power to change tax rates!
- Select Preview PDF and click the State Drop-down List object. This time, the tax text field will be populated with the new values that you entered in the form variable.
- While you are in Preview PDF mode, enter 251 in the Number of Pants text field. You will see a message box informing you that your number is too large (Figure 4.15).
Figure 4.15 This custom message was set in the Value tab of the Object palette.
- Go back to Design View and select the numberOfPants text field. You will see the following script in the validate event of the Show menu:
this.rawValue <= totalPants.value;
Notice again that your script refers to the form variable. If your inventory changes, you can easily change this variable and your form's functionality will automatically be updated.
Script variables
Unlike form variables, script variables are local in nature. A local variable is used only within the scope of the script in which it is declared. If a variable is declared in one script and then referenced in another script, an error will occur. Local variables are used when their stored values are not needed after the script is completed. Once the script is finished, the memory that was assigned to the local variable is released and is able to be used for other purposes, helping to improve form performance.
You declare a script variable before it is first used in your script. The following example uses the JavaScript var operator to declare a variable named testVar. Once declared, the value of the variable is set to the rawValue of the text field:
var testVar; testVar = textField1.rawValue;
Thereafter, you can reference or change the variable at any point throughout the script.
Referencing Objects
You have been writing code to reference objects in all of your previous scripting examples. This section covers the various ways that you can reference an object in Designer scripting. Although there are some minor differences, FormCalc and JavaScript both follow the same syntax when referencing objects. The syntax for referencing objects is described in this section and object structure is covered in the "Form Object Model" section.
Open the Purchase Order form in Designer and add a new button to the commentsHeader subform directly below Button3. Name your new button, "exampleButton" (Figure 4.16). It is very important for the examples in this section that this button be put in the commentsHeader subform.
Figure 4.16 Add an Example Button to your Purchase Order form.
Fully qualified reference
A fully qualified reference uses the complete form hierarchy beginning with the xfa root node. The advantage of a fully qualified statement is that it will work every time regardless of where the script that contains the reference is written. A fully qualified reference for the exampleButton (Figure 4.16) looks like this:
xfa.form.form1.purchaseOrder.commentsHeader.exampleButton
- Select your exampleButton and write the following script in the click event:
xfa.form.form1.purchaseOrder.commentsHeader.Button3.presence = "invisible";
- Select Preview PDF, and you will see that the Add Comments button disappears when you click the Example Button.
- Go back to Design View and put the same script into the click event of the Add Item button (Button1 in the form hierarchy).
- Select Preview PDF, and you will see that the Add Comments button disappears even though the script is running from a different place on the form. This works because you are using a fully qualified object reference.
Abbreviated reference
Even though fully qualified references will always work, they usually take longer to write than abbreviated references. The reference syntax for an abbreviated reference is shorter than a fully qualified reference for one of the following reasons:
-
Relative positioning: You can use an abbreviated reference if two form objects exist in the same container like a subform or a page. For instance, in the purchase order example, the Example Button and the Add Comments button both exist on the commentsHeader subform. You can change your script in the exampleButton's click event to the following abbreviate reference:
Button3.presence = "invisible";
This works in the exampleButton because of its relative position to the Add Comments button, but it will not work in the Add Item button's click event. In fact, if you put the abbreviated reference at the beginning of the script, not only will this line of script fail, but the entire block of script will not execute. The JavaScript interpreter will not step over an improper statement; it will step out of the routine altogether. If you move the improper abbreviated reference to the end of the code block, you'll see that the previous lines will execute, but the interpreter will still hang on the abbreviated reference.
You can create a proper abbreviated reference from the Add Item button to the Add Comments button by referring to the first container object that they have in common. For instance, the following script will work from the Add Item button:
purchaseOrder.commentsHeader.Button3.presence = "invisible";
-
Use of shortcuts: FormCalc has built-in shortcuts that reduce the effort required to write references. For instance, the $host shortcut references the host object. Replace the script of your exampleButton with the following line of code:
$host.messageBox("hello world")
Remember, you need to change the Language to FormCalc. Many more FormCalc shortcuts are documented in the Help System.
The current object
Both FormCalc and JavaScript use shortcuts to refer to the current object. You have already used JavaScript's shortcut "this"; FormCalc's shortcut is the "$" symbol. You can add the following code to the initialize event of your Example Button to customize the tool tip.
JavaScript:
exampleButton::initialize: - (JavaScript, client) this.assist.toolTip.value = "This is the Example Button";
FormCalc:
exampleButton::initialize: - (FormCalc, client) $.assist.toolTip.value = "This is the Example Button";
Unnamed objects
I recommend providing meaningful names to your form objects. However, occasionally you may come across unnamed objects in Designer. If you need to refer to an unnamed object in a script, you should precede it with the # sign. Follow these steps to create an unnamed object and properly refer to it with a script:
- Create a blank form with the default options including the Print and Email buttons. Set your default scripting language to FormCalc. The page subform is unnamed (Figure 4.17).
Figure 4.17 The hierarchy of a blank form shows an unnamed subform object.
- Select the form1 object at the top of the hierarchy and enter the following script into the initialize event:
form1::initialize: - (FormCalc, client) -------------------- xfa.form.form1.#subform.PrintButton1.presence = "invisible"
As you typed the line into the Script Editor, you should have noticed that the unnamed object appeared in the beginning of the statement completion list. All unnamed objects will appear in the beginning of the list and will be preceded by the # symbol. - Select Preview PDF, and you will see that your syntax is correct because the Print button is invisible.
- Switch back to Design View and select the form1 object again. This time, switch the Language to JavaScript. When you select Preview PDF, this script will not work because JavaScript cannot correctly interpret the # symbol. When working with unnamed objects in JavaScript, you must use the resolveNode method of the xfa object. The following script will work:
form1::initialize: - (JavaScript, client) -------------------- xfa.resolveNode("xfa.form.form1.#subform.PrintButton1").presence = "invisible"
Notice that the reference path that is passed to the resolveNode method is surrounded by quotes.
Multiple objects with the same name
LiveCycle Designer also supports the creation of multiple objects with the same name. When multiple objects have the same name, each has a different occurrence number represented by a number in brackets directly following the object name.
- Drag and drop a text field onto your blank form.
- Copy and paste the text field a few times, and you will see that Designer puts an occurrence number at the end of each name (Figure 4.18).
Figure 4.18 You can see the occurrence numbers for your objects in the Hierarchy palette.
- Select your form1 object and click the initialize event in the Script Editor.
- Switch back to FormCalc and enter the following script:
xfa.form.form1.#subform.TextField1[0].rawValue = "First" xfa.form.form1.#subform.TextField1[1].rawValue = "Second" xfa.form.form1.#subform.TextField1[2].rawValue = "Third"
- Select Preview PDF to see that each of your text fields have a different value.
You will also need to use the xfa.resolveNode method if you are working with multiple objects of the same name because JavaScript cannot interpret the occurrence number syntax. The following code will work in JavaScript:
xfa.resolveNode("xfa.form.form1.#subform.TextField1[0]").rawValue = "First" xfa.resolveNode("xfa.form.form1.#subform.TextField1[1]").rawValue = "Second" xfa.resolveNode("xfa.form.form1.#subform.TextField1[2]").rawValue = "Third"
You can find a more advanced example of how occurrence numbers work in the purchase order example. The following script is FormCalc:
// Verify at least one instance of the numAmount field exists. if (exists(detail[0].numAmount) == 1) then Sum(detail[*].numAmount) endif