Designer Scripting Basics, Study notes of Design

Download Designer Scripting Basics and more Study notes Design in PDF only on Docsity! Designer Scripting Basics Md | AEM 6.2 Forms Last updated 5/24/16 Legal notices For legal notices, see http://help.adobe.com/en_US/legalnotices/index.html. Scripting with FormCalc and JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Using FormCalc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Using built-in functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Creating basic calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Using JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Creating scripts using JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Enforcing strict scoping rules in JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 To attach a JavaScript script to an object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Naming variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 To define a text variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 To define a text variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 To view a text variable definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 To view a text variable definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 To delete a text variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 To delete a text variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Using variables in calculations and scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Referencing Objects in Calculations and Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Referencing object properties and values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Referencing unnamed and repeated objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 Referencing the current object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 FormCalc reference syntax shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Creating and Reusing JavaScript Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 To create a script object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 To add script to a script object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 To reference JavaScript functions stored in a script object . . . . . . . . . . . . . . . . . . . . 98 Using Script Fragments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Script fragment properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 To create a script fragment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 To insert a script fragment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Debugging Calculations and Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 Designer Report palette warning and validation messages . . . . . . . . . . . . . . . . . . . 103 Providing debugging feedback using the messageBox method . . . . . . . . . . . . . . . . . 103 FormCalc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 Output information into a text field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 JavaScript Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 Debugging tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107iii Working with a Host Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 Host scripting model properties and methods . . . . . . . . . . . . . . . . . . . . . . . . . . 111 Comparing the host scripting model functionality . . . . . . . . . . . . . . . . . . . . . . . . 112 Working with the Event Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 Event model properties and methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 Moving from Scripting in Acrobat to Designer . . . . . . . . . . . . . . . . . . . . . . . . . 116 Converting Acrobat forms that contain scripts . . . . . . . . . . . . . . . . . . . . . . . . . . 117 Using JavaScript objects from Acrobat in Designer . . . . . . . . . . . . . . . . . . . . . . . 117 JavaScript objects from Acrobat supported in Designer . . . . . . . . . . . . . . . . . . . . . 118 Examples of Common Scripting Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 Changing the background colors of fields, fillable areas, and subforms . . . . . . . . . . . . 134 Hiding and showing objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 Excluding an object from the tabbing order . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 Changing the visual properties of an object on the client . . . . . . . . . . . . . . . . . . . . 141 Getting the current or previous value of a drop-down list . . . . . . . . . . . . . . . . . . . . 145 Preserving rich text formatting when copying field values . . . . . . . . . . . . . . . . . . . 146 Adjusting the height of a field at run time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 Setting a field as required at run time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 Calculating the field sums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 Highlighting fields in response to form filler interaction . . . . . . . . . . . . . . . . . . . . 150 Resetting the values of the current subform . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 Changing the presence of a form design object . . . . . . . . . . . . . . . . . . . . . . . . . . 154 Using the properties of the instance manager to control subforms . . . . . . . . . . . . . . . 155 Using the methods of the instance manager to control subforms . . . . . . . . . . . . . . . . 157 Using the instance manager to control subforms at run time . . . . . . . . . . . . . . . . . . 160 iv About This Document1. About This Document Welcome to Designer Scripting Basics. Scripting Basics provides you with an overview of how you can use Designer calculations and scripts to develop and extend forms created in Designer. You can use calculations and scripts to perform these types of actions: • Change the behavior and appearance of objects at run time • Control the presentation of field values • Provide interaction with form fillers using dialog boxes and visual cues • Automate form filling • Control the hosting environment • Interact with web services • Interacting with databases and populate forms with data from data sources 1.1. Purpose and scope Scripting Basics is intended for form authors and form developers interested in using calculations and scripts to extend their Designer forms. It is assumed that you have a working knowledge of scripting languages, especially JavaScript™, as well as object models. You should also be familiar with Adobe® Acrobat® Professional or Acrobat Standard and be comfortable working in a structured XML environment. Scripting Basics provides the following information: • An introduction to using Designer calculations and scripts to extend your forms • Easily understood, detailed information and examples of the Designer calculation and scripting features • References to other resources where you can learn more about Designer scripting and related technologies After reading this guide, you should be equipped to start using Designer calculations and scripts. During the development process, you will find that the descriptions and examples in this guide will provide you with enough direction and background to enable you to successfully complete your projects.1 Scripting Using Designer 2If you add this script to the calculate event for NumericField1, when you open the form for the first time, NumericField1 displays the value 2. This indicates that the calculate event occurred twice in the sequence of events that occurred when the form was opened. RELATED LINKS: Events Objectsthat support calculations and scripts Understandingrelationships between objects in the ObjectLibrary 2.2. Objects that support calculations and scripts The following table provides a quick reference of scripting support for the standard objects that are included in the Library palette in Designer. Objects that support calculations and scripts Objects that do not support calculations and scripts Barcodes Circle Button Content Area Check Box Line Date/Time Field Rectangle Decimal Field Image Signature Field Subform Sets Drop-Down List Table sections Email Submit Button Text HTTP Submit Button Image Field List Box Numeric Field Paper Forms Barcode Password Field Print Button 4 Scripting Using DesignerRELATED LINKS: Understandingrelationships between objects in the ObjectLibrary 2.3. Understanding relationships between objects in the Object Library When you create calculations and scripts in Designer, you should be aware that the objects on which you are adding scripts are actually defined as XML objects in the underlying XML Forms Architec- ture. That means while the Standard tab of the Object Library palette contains a wide variety of objects, many of those objects are defined by the same XML object. As a result, the various scripting properties and methods that are available are based on the definition of the XML object, and not the object in the Object Library palette. Objects available in the Standard tab of the Object Library palette that are based on the same base XML object definition share a set of common properties and methods. If you are referring to the Scripting Objects section, you determine the set of properties and methods available based on the corresponding base XML object. Similarly, each base XML object definition contains a child object that specifically controls the visual appearance of the Designer object. For example, if you want to browse the properties and methods that are available for a Date/Time Field object in Designer, you would start with the field object. If you want to browse the corre- sponding XML object that controls the visual appearance of the Date/Time Field, view the dateTimeEdit object. The table below illustrates the mapping between objects that you see in the Standard tab of the Object Library palette in Designer, and the corresponding XML Form Architecture object. Radio Button Reset Button Subform Table (including body rows, header rows, and footer rows) Text Field Objects that support calculations and scripts Objects that do not support calculations and scripts Standard Object Library Object XML Form Architecture Object (Base) XML Form Architecture Object (UI) Barcodes field barcode5 Scripting Using Designer 2RELATED LINKS: Objectsthat support calculations and scripts 2.4. Script Editor The Script Editor is where you create, modify, and view the calculations and scripts of a particular form. For example, you can use the Script Editor to write a simple calculation that adds two numeric Button field button Check Box field checkButton Date/Time Field field dateTime Decimal Field field numericEdit Signature Field field signature Drop-Down List field choiceList Email Submit Button field button HTTP Submit Button field button Image Field field imageEdit List Box field choiceList Numeric Field field numericEdit Paper Forms Barcode field barcode Password Field field passwordEdit Print Button field button Radio Button field checkButton Reset Button field button Subform subform N/a Table (including body rows, header rows, and footer rows) subform N/a Text Field field textEdit Standard Object Library Object XML Form Architecture Object (Base) XML Form Architecture Object (UI) 6 Configuring Designer for Scripting3. Configuring Designer for Scripting 3.1. To show the Script Editor 1) Select Window > Script Editor. NOTE: You can use the Expand button to quickly dock or undock the Script Editor when it is displayed in the Designer workspace. 3.2. To change from single-line to multiline view 1) Drag the Script Editor palette bar until the palette is the required size. NOTE: Multiline view adds the All Events and Events with Scripts options to the Show list. The All Events option displays all of the events for a particular form design object, even if the events do not contain any calculations or scripts. The Events with Scripts option displays only those events of a particular object that contain calculations or scripts. 3.3. To set the default scripting language for new forms 1) Select Tools > Options. 2) Click Workspace. 3) In the Default Language For New Forms list, select the default scripting language for new forms. 3.4. To set the default scripting language for the current form 1) Select File > Form Properties. 2) Click the Defaults tab. 3) In the Default Language list, select the default scripting language for the currently displayed form.9 Configuring Designer for Scripting 33.5. To set the default scripting language for the current form 1) Select Edit > Form Properties. 2) Click the Defaults tab. 3) In the Default Language list, select the default scripting language for the currently displayed form. 3.6. To set the default scripting language for a form template 1) Create a new form design. 2) Select File > Form Properties. 3) Click the Defaults tab. 4) Select your default scripting language from the Default Language list. 5) Make a backup of the original form template file located in the Templates folder where Designer is installed. 6) Save the new form design as a TDS file and overwrite the corresponding form template. For example, save the file as Letter.tds and overwrite the Letter.tds file located in Templates\Blank folder. 3.7. To set the default scripting language for a form template 1) Create a new form design. 2) Select Edit > Form Properties. 3) Click the Defaults tab. 4) Select your default scripting language from the Default Language list. 5) Make a backup of the original form template file located in the Templates folder where Designer is installed. 6) Save the new form design as a TDS file and overwrite the corresponding form template. For example, save the file as Letter.tds and overwrite the Letter.tds file located in Templates\Blank folder. 10 Configuring Designer for Scripting3.8. To set the default processing application 1) Select File > Form Properties. 2) Click the Defaults tab. 3) Select your default processing application from the Default Run At list. NOTE: This procedure only sets the value of the default processing application for the current instance of the form. To avoid changing the default processing application each time you create a form, you must modify the corresponding form template file that is used to create a new form design. 3.9. To set the default processing application 1) Select Edit > Form Properties. 2) Click the Defaults tab. 3) Select your default processing application from the Default Run At list. NOTE: This procedure only sets the value of the default processing application for the current instance of the form. To avoid changing the default processing application each time you create a form, you must modify the corresponding form template file that is used to create a new form design. 3.10. To change the default processing application for a form template 1) Create a new form design. 2) Select File > Form Properties. 3) Click the Defaults tab. 4) Select your default processing application from the Default Run At list. 5) Make a backup of the original form template file located in the Templates folder where Designer is installed. 6) Save the new form design as a TDS file and overwrite the corresponding form template. For example, save the file as Letter.tds and overwrite the Letter.tds file located in Templates\Blank folder.11 Configuring Designer for Scripting 3You may also find it useful to change the default options for the Script Editor to make it easier to debug your calculations and scripts. These options are in the Workspace panel of the Options dialog box, which is available by selecting Tools > Options and then selecting Workspace from the list on the left. For example, you can choose to display line numbers in the Script Editor or change the formatting of FormCalc or JavaScript syntax. XML Source tab The XML Source tab contains the form design’s XML code. The XML source code defines all aspects of the form. You can use the XML Source tab to view the XML Form Object Model structure of a form design and to understand the relationships between objects and properties. In the XML source, the XML element names are equivalent to the object names in the XML Form Object Model, and attributes are equivalent to properties. When you select an object in the Hierarchy palette and then click the XML Source tab, the first line of the corresponding element is highlighted. The object name in Designer, as listed in the Hierarchy palette, becomes the value of the name attribute in the XML source. You can set options in the Tools > Options dialog box for viewing the source in the XML Source tab, such as showing or hiding line numbers and setting the syntax coloring. It is recommended that you do not edit the XML source code directly. Workspace location Purpose 14 Creating Calculations and Scripts4. Creating Calculations and Scripts Designer provides a wide range of calculation and scripting features that you can use to perform a variety of tasks. For example, the following script changes the color of a text field border and the font size of the text field value: TextField1.border.edge.color.value = "255,0,0"; TextField1.font.typeface = "Courier New"; More complex forms can take advantage of scripting to perform data source connectivity and data manipulation at run time. For examples of common scripting tasks, see Examplesof Common Scripting Tasks. Creating calculations and scripts in Designer involves following a general process each time you attach a calculation or script to an object. Although not all aspects of the process are required each time you create a calculation or script, following the process helps to eliminate potential errors and unexpected results. In general, each time you create a calculation or script, you perform the following tasks: • Select the object to which you want to attach a calculation or script. Although you can create calculations and scripts that manipulate almost any object on your form design, not all form design objects support form events. For a list of standard objects included in the Object Library palette in Designer that support scripting, see Objectsthat support calculations and scripts. • Write your calculation or script in the script editing field of the Script Editor. • Test the calculation or script either by using the Preview PDF tab or in your test environment. 4.1. Naming conventions for form design objects and vari- ables When creating calculations or scripts to enhance your form, be aware of the form design object and variable names on your form. In general, avoid using the names of XML Form Object Model prop- erties, methods, and objects for form design objects and variables. Using XML Form Object Model property, method, or object names can result in calculations and scripts not executing properly. For example, if you create a new text field named x within a subform object named Subform1, you access the text field object using the following syntax: Subform1.x.[expression] However, subform objects already have an XML Form Object Model property named x that represents the horizontal position of the subform on the form design.15 Creating Calculations and Scripts 4To avoid naming conflicts, you need to choose field naming conventions that differ from the XML Form Object Model naming conventions. For example, you can use any of the following field names for the text field in the example above: • horizontalValue • x_value • xLetter • hValue For more information and a list of the XML Form Object Model property, method, and object names, see Scripting Reference. RELATED LINKS: Namingvariables CreatingCalculations and Scripts 4.2. Choosing a scripting language Designer supports scripting with both FormCalc and JavaScript. Each scripting language presents its advantages that you should be aware of before you write any scripts on your form. FormCalc is a calculation language that includes a wide range of built-in functions to simplify the most common form functionality. For example, you can use FormCalc financial functions to eval- uate the size of a loan payment based on the principle amount, interest rate, and number of payment periods. JavaScript is a more powerful and diverse scripting language, intended to give you more flexibility and leverage your existing scripting knowledge. For example, you can reuse your existing JavaScript functions in Designer to reduce the amount of new scripting you need to create. NOTE: Designer supports JavaScript version 1.6 or earlier. You can choose the scripting language that is used for new forms in the Workspace panel in the Options dialog box, and for the current form on the Defaults tab in the Form Properties dialog box. The scripting language that is displayed in the Language list in the Script Editor matches the scripting language option you select as the default for new forms. However, if you change the scripting language setting for the current form, the scripting language that is displayed in the Language list changes similarly for new scripts on new events. Changing the scripting language option in the Form Properties dialog box does not change the scripting language that was used for existing scripts. If an event already contains some script and that script is deleted, the Script Editor continues to use that scripting language for the duration of your Designer working session. 16 Creating Calculations and Scripts4) In the Run At list, select where you want the script to execute. For example, for the new button object, select Client. You can choose to run calculations or scripts on your client-based application (for example Acrobat or a web browser) or on your server-based process (for example, Adobe document services). When set to Client, processing of calculations and scripts initiates after the form renders. When set to Server, processing of calculations and scripts initiates during the form rendering process. Previewing your form by using the Preview PDF tab simulates opening the form in Acrobat; therefore, scripts set to run at Client or Client and Server execute. NOTE: Selecting Client And Server from the Run At list causes a script to execute in either the client application or the server application, depending on which application is used to process the form. 5) In the Script Source field, insert your FormCalc calculation or JavaScript script. You can take advantage of the statement completion functionality of Designer to help you create reference syntaxes for your calculation or script. For example, add the following JavaScript script to the new button object: xfa.host.messageBox("Hello World!", "Creating a new script", 3); 6) After you complete your form design, test and debug your calculations and scripts before putting them into production. For example, for the new button object, preview the PDF of the form using the Preview PDF tab. Click the button object to display the message box specified in step 5. For more information about the Designer objects that support scripting, see Objectsthat support calculations and scripts. RELATED LINKS: UsingFormCalc UsingJavaScript Events Touse statement completion to create calculations andscripts Determiningwhen to run your calculation or script Toview scripting events and scripts Determiningwhere to run your calculation or script Testingand debugging calculations and scripts19 Creating Calculations and Scripts 44.5. To find text or other items You can quickly search for every occurrence of a specific word or phrase when you are in the XML Source tab or in the Script Editor. 1) In the XML Source tab or the Script Editor, select Edit > Find or right-click for the context menu. 2) In the Find What box, enter the text that you want to search for. 3) Select any other options that you want. 4) Click Find Next. To cancel a search in progress, press Esc or select the Cancel button. IMPORTANT: Although it is possible to edit XML source code directly in the XML Source tab, it is recommended that you do not make any changes unless you are familiar with the Adobe XML Forms Architecture. For more information about the XML Forms Architecture, see the Developer Center. RELATED LINKS: CreatingCalculations and Scripts To create a calculation orscript t Toreplace text or other items Touse statement completion to create calculations andscripts Determiningwhen to run your calculation or script Toview scripting events and scripts Determiningwhere to run your calculation or script Testingand debugging calculations and scripts 4.6. To replace text or other items You can automatically replace text. For example, you can replace Corp. with Corporation. 1) In the Script Editor, select Edit > Replace. 2) In the Find What box, enter the text that you want to search for. 3) In the Replace With box, enter the replacement text. 4) Select any other options that you want. 5) Click Find Next, Replace, or Replace All. 20 Creating Calculations and Scripts6) To cancel a search in progress, press Esc or select the Cancel button. To replace text that appears in scripts attached to multiple objects on your form, select the root subform of your form (by default: form1) and select Show Events for Child Objects and then perform the procedure above. IMPORTANT: Although it is possible to edit XML source code directly in the XML Source tab, it is recommended that you do not make any changes unless you are familiar with the Adobe XML Forms Architecture. For more information about the XML Forms Architecture, see the Developer Center. RELATED LINKS: CreatingCalculations and Scripts Tofind text or other items 4.7. To use statement completion to create calculations and scripts The statement completion functionality within the Script Editor lets you build your calculations and scripts interactively. When writing a calculation or script, each time you enter a period (.) immediately following a form object or property name, the statement completion functionality displays a list of available methods and properties. If the statement completion list does not appear, verify that you have typed the object or property name correctly and that the object is within the scope of the object where you are creating your script. For more information about referencing objects in calculations and scripts, see ReferencingObjects in Calculations and Scripts. 1) Type the name of a form design object, property, or a valid FormCalc shortcut, followed by a period. 2) Select the method or property you want to apply for the form design object and continue writing the script. To close the statement completion list without selecting a function, press the Esc key. The list of available XML Form Object Model properties changes depending on the form design object or property that appears before the period. NOTE: The statement completion list appears only when accessing objects, properties, and methods in the XML Form Object Model. It does not appear when working with standard JavaS- cript objects or methods. RELATED LINKS: Referencingobject properties and values21 Creating Calculations and Scripts 44.10.2. To view a scripting event for a container object and its children in the Script Editor 1) If it is not already in multiline mode, expand the Script Editor to display multiple lines of script and ensure that the Show Events for Child Objects option is selected. 2) Select a container object, such as a subform. 3) In the Show list, select a valid scripting event. The events appear in the script editing field of the Script Editor, separated by the reference syntax for each event. Note that certain events only apply to specific types of objects. When you select a script event, the script editing field of the Script Editor only displays valid instances of the event. For example, if you select a subform that contains a drop-down list and select the preOpen event, the Script editor displays a single entry representing the drop-down list. This is because the preOpen event only applies to drop-down lists. Alternatively, selecting the enter event displays two entries, one for the drop-down list and one for the subform. NOTE: The Show list denotes events that contain scripts using a trailing asterisk (*) after the name of the event. If an event contains a script, when you select the event from the Show list, the source appears in the script editing field of the Script Editor. 4.10.3. To view all scripting events for a single object in the Script Editor 1) Select an object in your form. 2) In the Show list, select All Events. The events appear in the script editing field of the Script Editor, separated by the reference syntax for each event. 4.10.4. To view all scripting events for a container object and its children in the Script Editor 1) If it is not already in multiline mode, expand the Script Editor to display multiple lines of script and ensure the Show Events for Child Objects option is selected. 2) Select a container object, such as a subform. 3) In the Show list, select All Events. The events appear in the script editing field of the Script Editor, separated by the reference syntax for each event. 24 Creating Calculations and Scripts4.10.5. To view all scripts for a single object in the Script Editor 1) Select an object that has scripts attached. 2) In the Show list, select Events With Scripts. The scripts appear in the script editing field of the Script Editor, separated by the reference syntax for each event. 4.10.6. To view all scripts for a container object and its children in the Script Editor 1) If it is not already in multiline mode, expand the Script Editor to display multiple lines of script and ensure that the Show Events for Child Objects option is selected. 2) Select a container object, such as a subform. All events for the container object and any child objects appear in the Script Editor. 3) In the Show list, select All Events. The scripts appear in the script editing field of the Script Editor, separated by the reference syntax for each event. 4.11. Determining where to run your calculation or script For each calculation and script created in Designer, you must specify the location where you want the calculation or script to run. Unless you are using server-based processing such as Forms, you should ensure that all of your calculations and scripts are set to run on the client application (for example, on Acrobat, a web browser, or the Mobile Workspace app). NOTE: FormCalc calculations and scripts do not work on forms rendered as HTML and are ignored during form filling. If you are using server-based processing, you can choose between running calculations on the client application, or running them on the server. By choosing to have calculations and scripts run on the server, you are choosing to run the scripts at a specific point during the form-rendering process. For more information, see Determining whento run your calculationor script. If you choose Client And Server from the Run At list, your calculation or script is available to both client and server-based applications. This option is useful, for example, if you do not know whether your users will have client or server applications when they attempt to use your form. It is also useful if you want certain form objects to behave one way to a client application and another to a server-based application.25 Creating Calculations and Scripts 4RELATED LINKS: Events Determiningwhen to run your calculation or script Toview scripting events and scripts 4.12. Testing and debugging calculations and scripts After you create your calculations or scripts and tested your form design, you may discover scripting errors or unexpected field values as a result of scripting syntax errors. Designer includes three primary methods for testing and debugging your calculations and scripts: • Using the Designer workspace palettes. For more information, see Usingthe workspace to debug calculations and scripts . • For JavaScript only, using the JavaScript Debugger to assist you in testing your scripts. For more information about using the debugger, see JavaScript Debugging. • Using the host model and event model properties and methods to troubleshoot your form. The host model and event model provide functionality that lets you interact with either the host application or the various form events. These models are useful for returning information that can assist you in debugging calculation and scripts. For example, the following script returns a message at run time indicating the name of the event on which the script is placed. This indicates that a particular event has fired: xfa.host.messageBox(xfa.event.name) // FormCalc xfa.host.messageBox(xfa.event.name); // JavaScript Another example of using the host model and event model methods is to obtain the value of a field on an interactive form before a user manually changed it. This is useful for observing how the objects on your form design respond to user-entered data: xfa.host.messageBox(xfa.event.prevText) // FormCalc xfa.host.messageBox(xfa.event.prevText); // JavaScript RELATED LINKS: Usingthe workspace to debug calculations and scripts Workingwith a Host Application Workingwith the Event Model 26 Events5. Events Every calculation or script you attach to a form object is associated with a specific event. An event is defined as a particular occurrence or action that can change the state of a form and, when the change of state occurs, automatically invoke a calculation or script associated with the event. Events occur at various times, from the beginning of the form rendering process when merging data with a form design, all the way through to a form filler interacting with objects on a form in a client application. By applying calculations and scripts to specific events, you can control every aspect of how you present form objects, as well as form data, and how the objects and data respond to form filler inter- action. A single change of state or form filler action may trigger multiple events. For example, tabbing from the current field to the next field triggers both the exit event for the current field and the enter event for the next field. If the current and next fields are in different subforms, a total of four events are triggered; namely, exit events for the current field and subform, and enter events for the next field and subform. In general, each of the different categories of form events follow a predictable ordering. 5.1. Types of events Form events fall into one of the following categories: Process events This type of event initiates automatically as the result of an internal process or action related to objects on a form. For example, if a form filler clicks a button that adds a new page to the form, the initialize, calculate, validate, and layout:ready process events initiate automatically for the new page. Interactive events This type of event initiates as a direct result of form filler actions. For example, if a form filler moves the pointer over a field on a form, the mouseEnter event initiates in response to the action. Application events This type of event initiates as a result of the actions that either a client application or a server application performs. For example, you can create a calculation or script to perform a task immediately after the form is saved by using the postPrint event. RELATED LINKS: Process events Interactive events29 Events 5Application events 5.2. Process events Process events initiate automatically as the result of an internal process or action related to a form or objects on a form. These events initiate immediately following significant form changes; for example, after a form design is merged with data or after the form pagination process finishes. Process events also initiate immediately after interactive events initiate. For example, immediately after any interactive event initiates, the calculate event initiates followed by the validate event. The following list contains the process events, which are available from the Show list in the Script Editor: • calculate • form:ready • indexChange • initialize • layout:ready • validate Process events can initiate many times as a result of dependencies; that is, actions associated with a single event that ultimately initiates one or more additional events. Using an example of a form filler clicking a button to reveal a previously hidden portion of the form, after the form filler clicks the button, not only does a series of interactive and processing events initiate for the button itself, but a number of process events for the new subform initiates as well. The following image represents the general flow of events leading up to a PDF form opening in Acrobat or Adobe Reader. After the form opens in Acrobat or Adobe Reader, these process events may still initiate as the result of changes made to the form. For example, the calculate, validate, and layout:ready events for an object initiate immediately after some interactive events occur; therefore, calculations and scripts attached to the processing events will run multiple times. 30 EventsRELATED LINKS: Interactive events Application events calculate event docReady event form:ready event indexChange event initialize event layout:ready event validate event Determining when to run your calculation or script 5.3. Interactive events Interactive events initiate as a direct result of form filler actions, which makes these events useful for a variety of calculation and scripting tasks. For example, you can add a script to the mouseEnter event for a text field that changes the border color of the field to blue and a script to the mouseExit event that changes the border color back to the original color. This action creates a highlighting effect when form fillers move the pointer over the field to visually assist them while filling the form. Interactive events are also useful for changing form data in response to a form filler selection. For example, you can add a script to the change event for a drop-down list that updates the data values in multiple fields in response to the value the form filler selects in the drop-down list. The following list contains the interactive events, which are available from the Show list in the Script Editor: • change • click • enter • exit • mouseDown • mouseEnter • mouseExit • mouseUp • postOpen • postSign31 Events 5 34 preSave calculate validate lavout:readv Events 5If a form filler saves the form in Acrobat or Adobe Reader, the preSave event initiates imme- diately before the save operation, followed by the calculate, validate, and layout:ready events, in that sequence for all objects on the form. The same event sequence initiates if the form contains a script that programmatically saves the form. A similar sequence of events occurs for each of the other application events previously listed. RELATED LINKS: docClose event postPrint event postSave event postSubmit event prePrint event preSave event preSubmit event 5.5. calculate event 5.5.1. Description Initiates in the following situations: • When your form design and data merge into your finished form. • When a change occurs to any value that the calculation is dependent on, such as the value of a particular field, unless the form filler has manually overridden the calculated value. As a result, the object will display the return value of the event. The properties for manually overridden fields are located in the Value tab of the Object palette. • When a field loses focus; for example, when a form filler clicks or uses the Tab key to exit a field. When using the calculate event to perform calculations or scripts, consider the following potential issues: • Calculations and scripts on the calculate event must not make any changes to the structure of the form, except for the form field and data values. • Content inserted by the calculate event must conform to the associated validations for the object; otherwise, validation errors will occur. • Calculations and scripts must not include an infinite loop because it causes the form to update the value continuously. For example, a script that increments the value of a field as part of a looping expression, such as a while or for loop, could create an infinite loop. 36 EventsNOTE: Scripting against an object's 'this.rawValue' does not work. Use the event model prop- erty $event.fullTextinstead to get the object's current value. For a detailed example of using the change event, see Gettingthe current or previous value of a drop-down list. RELATED LINKS: Events Interactive events 5.7. click event 5.7.1. Description Initiates when a mouse click occurs within the region. When a click event initiates for a text or numeric field, calculations or scripts execute immediately. However, the value of the field does not change in response to calculations and scripts until the field loses focus. NOTE: You cannot place a calculation or script on the click event of a submit button because the calculation or script will override the submission action. Instead, place any calculations and scripts on the preSubmit event for a submit button. For more information about form submission actions, see the Designer Help. 5.7.2. Type Interactive event 5.7.3. Support 5.7.4. Version XFA 2.1 Client application Availability Acrobat and Adobe Reader yes HTML browser yes39 Events 55.7.5. Example Use this event for performing an action as a direct response to a form filler clicking a button or selecting a radio button or check box on a form. For example, you can use the click event for a check box to hide and show a field on the form. For a detailed example of using the click event, see Changingthe visual properties of an object on the client. RELATED LINKS: Events Interactive events preSubmit event 5.8. docClose event 5.8.1. Description Initiates at the very end of processing a form, only if all form validations complete with no errors. 5.8.2. Type Application event 5.8.3. Support 5.8.4. Version XFA 2.1 Client application Availability Acrobat and Adobe Reader yes HTML browser no 40 Events5.8.5. Example This event initiates too late to modify a saved form and is intended to provide the ability to generate an exit status or completion message. For example, you can use the docClose event to display a message to a form filler indicating that the form is completed. RELATED LINKS: Events Application events Process events 5.9. docReady event 5.9.1. Description Initiates immediately after the form opens in Acrobat or Adobe Reader. 5.9.2. Type Application event 5.9.3. Support 5.9.4. Version XFA 2.1 5.9.5. Example This event is the first one that initiates after the form opens in Acrobat or Adobe Reader. Any calcu- lation or scripting tasks that require the full form, or that should only run once when the form filler Client application Availability Acrobat and Adobe Reader yes HTML browser no41 Events 5For a detailed example of using the exit event, see Highlightingfields in response to form filler interaction. RELATED LINKS: Events Interactive events 5.12. form:ready event 5.12.1. Description Initiates after the form design and data are merged, the finished form exists in memory, and the initialize, calculate, and validate events are complete. NOTE: The form:ready event only applies to Design View objects, and does not apply to Master Page objects (see Processevents). 5.12.2. Type Processing event 5.12.3. Support 5.12.4. Version XFA 2.1 5.12.5. Example You can use this event to perform tasks after the form design and data are merged but before the layout is established. For example, you can use this event to customize the ordering or placement of subforms on your form before the form is paginated and rendered. Client application Availability Acrobat and Adobe Reader yes HTML browser no 44 EventsRELATED LINKS: Events 5.13. full event 5.13.1. Description Initiates when the form filler attempts to enter more than the maximum allowed amount of content into a field. For example, if the Limit Length property for a field is set to 5, and a form filler attempts to enter the string abcdef, the full event initiates when the form filler types the letter f. NOTE: The Limit Length property for a field is located in the Field tab in the Object palette. 5.13.2. Type Interactive event 5.13.3. Support 5.13.4. Version XFA 2.1 5.13.5. Example Use this event to indicate to a form filler that a field has reached its maximum capacity. For example, you can output a message to the form filler indicating that the field is full and provide any steps that should be taken to correct the issue. RELATED LINKS: Events Interactive events Client application Availability Acrobat and Adobe Reader yes HTML browser no45 Events 55.14. indexChange event 5.14.1. Description Initiates as a result of a subform being inserted, moved, or removed from the form by merging new data with the form or by using scripting. Keep in mind that the indexChange event does not fire when deleting the last row of a table. NOTE: This event is received only by the subform instances that are controlled by the instance manager; the event is ignored for subform sets. 5.14.2. Type Processing event 5.14.3. Support 5.14.4. Version XFA 2.5 5.14.5. Example You can use this event to set properties based on the instance value of a particular object. For example, you can use this event to coordinate the shading of alternate rows in a table. RELATED LINKS: Events Process events Client application Availability Acrobat and Adobe Reader yes HTML browser no 46 EventsProcess events 5.17. mouseDown event 5.17.1. Description Initiates when a form filler presses the mouse button at the same time that the pointer is within a field. NOTE: When a mouseDown event initiates for a text or numeric field, calculations or scripts run immediately. However, the value of the field does not change in response to calculations and scripts until the field loses focus. When a mouseDown event initiates for a signature field, the event initiates before the signature process begins. 5.17.2. Type Interactive event 5.17.3. Support 5.17.4. Version XFA 2.1 5.17.5. Example You can use this event to perform an action as a direct response to a form filler clicking a button, or selecting a radio button or check box on a form. For example, you can use the mouseDown event for a check box to hide and show a field on the form. This event is conceptually similar to the click event and has a similar purpose. RELATED LINKS: Events Client application Availability Acrobat and Adobe Reader yes HTML browser yes49 Events 5Interactive events click event 5.18. mouseEnter event 5.18.1. Description Initiates when the form filler moves the pointer into the area of the field, without necessarily pressing the mouse button. This event is not initiated when the pointer moves into the field for a different reason; for example, because an overlapping window closes. 5.18.2. Type Interactive event 5.18.3. Support 5.18.4. Version XFA 2.1 5.18.5. Example You can use this event to provide visual feedback to a form filler in conjunction with the mouseExit event. For example, you can use this event to change the border or background color of an object to help visually indicate to form fillers that they are working in a specific field. For a detailed example of using the mouseEnter event, see Highlightingfields in response to form filler interaction. RELATED LINKS: Events Client application Availability Acrobat and Adobe Reader yes HTML browser no 50 EventsInteractive events 5.19. mouseExit event 5.19.1. Description Initiates when a form filler moves the pointer out of the field, even if the form filler is pressing the mouse button. It is not initiated when the pointer moves out of the field for a different reason; for example, because an overlapping window opens. 5.19.2. Type Interactive event 5.19.3. Support 5.19.4. Version XFA 2.1 5.19.5. Example You can use this event to provide visual feedback to a form filler in conjunction with the mouseEnter event. For example, you can use this event to return the border or background color of an object to its original value to help visually indicate to form fillers that they are no longer working in a specific field. For a detailed example of using the mouseExit event, see Highlightingfields in response to form filler interaction. RELATED LINKS: Events Client application Availability Acrobat and Adobe Reader yes HTML browser no51 Events 5Interactive events 5.22. postPrint event 5.22.1. Description Initiates immediately after the rendered form is sent to the printer, spooler, or output destination. 5.22.2. Type Application event 5.22.3. Support 5.22.4. Version XFA 2.1 5.22.5. Example You can use this event to display information messages to the form filler after the form is printed. For example, you can create a script on the postPrint event to remind form fillers what steps they need to take to submit the form by hand. RELATED LINKS: Events Application events Client application Availability Acrobat and Adobe Reader yes HTML browser no 54 Events5.23. postSave event 5.23.1. Description Initiates immediately after a form filler saves a form in PDF or XDP format. This event does not initiate when you export a subset of the form (for example, only form data) to XDP. 5.23.2. Type Application event 5.23.3. Support 5.23.4. Version XFA 2.1 5.23.5. Example You can use this event to display information messages to the form filler after the form data is saved. For example, you can create a script on the postSave event to remind form fillers how much time remains for them to successfully complete and submit the form. RELATED LINKS: Events Application events Client application Availability Acrobat and Adobe Reader yes HTML browser no55 Events 55.24. postSign event 5.24.1. Description Initiates immediately after a form filler performs an action that applies a digital signature to a form. NOTE: This event applies only to the Signature Field object. 5.24.2. Type Interactive event 5.24.3. Support 5.24.4. Version XFA 2.8 5.24.5. Example You can use this event to inform a user about any restrictions that are imposed now that the form is digitally signed. RELATED LINKS: Events Interactive events Client application Availability Acrobat and Adobe Reader yes HTML browser no 56 Events5.27. prePrint event 5.27.1. Description Initiates immediately before the process of rendering a form for printing begins. You cannot cancel printing using this event. IMPORTANT: Avoid using this event to hide or show form objects. For example, if a form filler has already digitally signed the form, using this event to hide all button objects prior to printing will impact the state of the signature. 5.27.2. Type Application event 5.27.3. Support 5.27.4. Version XFA 2.1 5.27.5. Example You can use this event to change the presence of an object to prevent it from printing. For example, you can use this event to hide text or instructions intended for the form filler to use while filling the form online. RELATED LINKS: Events Application events Client application Availability Acrobat and Adobe Reader yes HTML browser yes59 Events 55.28. preSave event 5.28.1. Description Initiates immediately before form data is saved in PDF or XDP format. This event does not initiate when the form data or another subset of the form is exported to XDP. 5.28.2. Type Application event 5.28.3. Support 5.28.4. Version XFA 2.1 5.28.5. Example You can use this event to change form data immediately before the data is saved. For example, you can create a script on the preSave event to scan the data and display a reminder message to the form filler if certain required fields remain empty. RELATED LINKS: Events Application events Client application Availability Acrobat and Adobe Reader yes HTML browser yes 60 Events5.29. preSign event 5.29.1. Description Initiates immediately before a form filler performs an action that applies a digital signature to a form. NOTE: This event applies only to the Signature Field object. 5.29.2. Type Interactive event 5.29.3. Support 5.29.4. Version XFA 2.8 5.29.5. Example You can use this event to validate the data that the digital signature covers or to provide any infor- mation to a user before they apply the digital signature. RELATED LINKS: Events Interactive events Client application Availability Acrobat and Adobe Reader yes HTML browser no61 Events 55.31.5. Example You can use this event to verify object values, particularly in situations where object data must conform to specific rules. For example, you can create a script on the validate event to verify that a total cost field on a purchase order form does not have a negative value. For a detailed example of using the validate event, see Settinga field as required at run time. RELATED LINKS: Events Process events 64 Scripting with FormCalc and JavaScript6. Scripting with FormCalc and JavaScript Although FormCalc and JavaScript are intended for two different types of users, there is some overlap between the types of built-in functions they offer. The following table lists all available Form- Calc functions and whether a comparable function exists within JavaScript. For more information about FormCalc functions and their parameters, see Built-infunction syntax. FormCalc function Description JavaScript method equivalent Abs(n1) Returns the absolute value of a numeric value or expression. Math.abs(n1) Apr(n1, n2, n3) Returns the annual percentage rate for a loan. None At(s1, s2) Locates the starting character position of a string within another string. String.search(s1) Avg(n1 [, n2... ] ) Evaluates a set of number values and/or expressions and returns the average of the non-null elements contained within that set. None Ceil(n1) Returns the whole number greater than or equal to a given number. Math.ceil(n1) Choose(n1, s1 [, s2... ] ) Selects a value from a given set of parameters. None Concat(s1 [, s2... ] ) Returns the concatenation of two or more strings. String.concat(s1, s2 [, s3 ... ]) Count(n1 [, n2...]) Evaluates a set of values and/or expressions and returns the number of non-null elements contained within the set. None CTerm(n1, n2, n3) Returns the number of periods needed for an investment earning a fixed, but compounded, interest rate to grow to a future value. None65 Scripting with FormCalc and JavaScript 6Date() Returns the current system date as the number of days since the epoch. Date.getDate() The JavaScript Date object does not use the epoch as a reference point. Date2Num(d1 [, f1 [, k1 ] ] ) Returns the number of days since the epoch, given a date string. The JavaScript Date object does not use the epoch as a reference point. DateFmt([ n1 [, k1 ] ] ) Returns a date format string, given a date format style. None Decode(s1 [, s2 ] ) Returns the decoded version of a given string. Partial support JavaScript only supports URL encoded values that contain no escape characters. Encode(s1 [, s2 ] ) Returns the encoded version of a given string. Partial support JavaScript only supports URL encoded values that contain no escape characters. Eval() Returns the value of a given form calculation. eval(s1) Exists(v1) Determines whether the given parameter is a valid reference syntax to an existing object. None Floor(n1) Returns the largest whole number that is less than or equal to the given value. Math.floor(n1) Format(s1, s2) Formats the given data according to the specified picture format string. None FV(n1, n2, n3) Returns the future value of consistent payment amounts made at regular intervals at a constant interest rate. None Get(s1) Downloads the contents of the given URL. None HasValue(v1) Determines whether the given parameter is a valid reference syntax with a non-null, non-empty, or non-blank value. None FormCalc function Description JavaScript method equivalent 66 Scripting with FormCalc and JavaScriptReplace(s1, s2 [, s3 ] ) Replaces all occurrences of one string with another within a specified string. String.replace(s1, s2) Right(s1, n1) Extracts several characters from a given string, beginning with the last character on the right. String.substring(n1, n2) Round(n1 [, n2 ] ) Evaluates a given numeric value or expression and returns a number rounded to the given number of decimal places. For more accurate results, set a legacy flag in xfa.xci. To switch to the default behavior, remove the legacy flag. Math.round(n1) Rtrim(s1) Returns a string with all trailing white space characters removed. None You can use JavaScript regular expressions to perform this operation. Space(n1) Returns a string consisting of a given number of blank spaces. None Str(n1 [, n2 [, n3 ] ] ) Converts a number to a character string. FormCalc formats the result to the specified width and rounds to the specified number of decimal places. String(n1) or Number.toString(radix) Stuff(s1, n1, n2 [, s2 ] ) Inserts a string into another string. None Substr(s1, n1, n2) Extracts a portion of a given string. String.substring(n1, n2) Sum(n1 [, n2... ] ) Returns the sum of the non-null elements of a given set of numbers. None Term(n1, n2, n3) Returns the number of periods required to reach a given future value from periodic constant payments into an interest-bearing account. None FormCalc function Description JavaScript method equivalent69 Scripting with FormCalc and JavaScript 6RELATED LINKS: Using FormCalc 6.1. Using FormCalc FormCalc is a simple yet powerful calculation language modeled on common spreadsheet software. Its purpose is to facilitate fast and efficient form design without requiring a knowledge of traditional scripting techniques or languages. Using several of the built-in functions, inexperienced FormCalc users can quickly create forms that save users from performing time-consuming calculations, vali- Time() Returns the current system time as the number of milliseconds since the epoch. Date.getTime() The JavaScript Date object does not use the epoch as a reference point. Time2Num(d1 [, f1 [, k1 ] ] ) Returns the number of milliseconds since the epoch, given a time string. None TimeFmt([n1 [, k1 ] ] ) Returns a time format, given a time format style. None UnitType(s1) Returns the units of a unitspan. A unitspan is a string consisting of a number followed by a unit name. None UnitValue(s1 [, s2 ] ) Returns the numeric value of a measurement with its associated unitspan after an optional unit conversion. None Upper(s1 [, k1 ] ) Converts all lowercase characters within a string to uppercase. String.toUpperCase() Uuid(n1) Returns a Universally Unique Identifier (UUID) string to use as an identification method. None Within(s1, s2, s3) Returns true (1) if the test value is within a given range, and false (0) if it is not. String.search(s1) WordNum(n1 [, n2 [, k1 ] ] ) Returns the English text equivalent of a given number. None FormCalc function Description JavaScript method equivalent 70 Scripting with FormCalc and JavaScriptdations, and other verifications. This way, you can create a basic set of rules for the form design that allows the resulting form to react according to the data it comes into contact with. Within Designer, FormCalc is the default scripting language in all scripting locations with JavaScript as the alternative. For information on setting your default scripting language, see ConfiguringDe- signer for Scripting. IMPORTANT: If you are developing forms for use with a server-based process (for example, using Foms), with the intent of rendering your forms in HTML, you should develop your calculations and scripts in JavaScript. FormCalc calculations are not valid in HTML browsers, and are removed prior to the form being rendered in HTML. FormCalc treats each new line in the Script Editor as a new expression to evaluate. RELATED LINKS: Using JavaScript 6.2. Using built-in functions The built-in functions that comprise FormCalc cover a wide range of areas, including mathematics, dates and times, strings, finance, logic, and the web. These areas represent the types of functionality that usually occur in forms. The purpose of the functions is to provide quick and easy manipulation of form data in a useful way. At the most basic level, a calculation can consist of only a single FormCalc function. However, a single FormCalc function can use other FormCalc functions as parameters. 6.2.1. To attach a FormCalc function to an object You can add a FormCalc function to any form design object that allows calculations and scripts, excep for the script object. 1) Make sure that you have the multiline version of the Script Editor displayed in the Designer workspace. 2) Select a field on your form. 3) In the Show list, select the calculate event. 4) Click the Functions icon or F10 to display a list of FormCalc functions. 5) Select the appropriate function and press Enter. 6) Replace the default function syntax notation with your own set of values. 7) Click the Preview PDF tab to test the form.71 Scripting with FormCalc and JavaScript 6Then, when you click the Preview PDF tab to view the completed form, the value of the simple expression appears in the text field. If the value does not appear in the preview, ensure that your simple expression appears in the calcu- late event of the form design object. Also, ensure that you installed Designer and Acrobat correctly. RELATED LINKS: Using FormCalc Using JavaScript 6.4. Using JavaScript To allow form designers more flexibility and scripting power, Designer supports the use of JavaS- cript version 1.6 or earlier in all situations that support scripting. Form developers who are familiar with JavaScript can apply their existing expertise directly to Designer. Designer provides several properties and methods that enhance JavaScript so that you to access field and object values. These properties and methods combined with the Designer reference syntax provide you with easy manipulation of form values and data. NOTE: The Script Editor does not provide syntax error checking for scripts created using JavaScript. In addition, statement completion options do not appear for standard JavaScript objects or methods. RELATED LINKS: Creating scripts using JavaScript 74 Scripting with FormCalc and JavaScript6.5. Creating scripts using JavaScript Creating scripts in Designer using JavaScript is similar to creating JavaScript in other applications. You can take advantage of previous knowledge of JavaScript concepts, reuse JavaScript functions using the Designer script object, and take advantage of JavaScript language functionality. However, notice that although previous JavaScript knowledge is transferable, to effectively use JavaScript on your form design, you must understand how to construct Designer reference syntax. Specifically, you must know how to correctly use the XML Form Object Model reference syntax to access objects on your form design. This table outlines the key concepts for developing scripts in JavaScript for Designer. The table also provides the location for more information on each concept within the Designer Help . In addition to the resources available in the Designer Help , the Developer Centercontains extensive scripting resources and documentation. RELATED LINKS: Enforcing strict scoping rules in JavaScript To attach a JavaScript script to an object Using JavaScript 6.6. Enforcing strict scoping rules in JavaScript When working with JavaScript in forms, it is important to declare objects and variables within the scope they are intended. Globally declaring objects or variables unnecessarily can cause performance problems. Strict scoping was introduced in Designer 8.1 to improve the run time and memory usage of a form. Strict scoping is enabled, by default, in Designer, for new forms. For old forms the option to enable strict scoping is available. Key concept For more information see... Creating references to object properties and values, including using the resolveNode method. Referencingobject properties and values resolveNode Touse statement completion to create calculations and scripts Using the host and event models to test and debug your form. Testingand debugging calculations and scripts Referencingobject properties and values Using a script object to reuse your existing JavaScript functions. Creatingand Reusing JavaScript Functions75 Scripting with FormCalc and JavaScript 66.6.1. What is scope in JavaScript? Scope works outwardly so that everything within curly brackets ({}) can see outside them. However anything outside the curly brackets cannot access anything inside them. In the following example, the first curly bracket opens the function scope and the second one closes it. Everything between the curly brackets is within the scope of foo (). The scope in the following example is valid because var nFooVar = nOutsideVar inside the curly brackets can see var nOutsideVar = 2 outside the curly brackets. In contrast, the following example shows an invalid scope because var nOutsideVar = nFooVar cannot access var nFooVar =4 within the curly brackets. Scope in scripting describes pieces of scripts that can access pieces. TShe pieces of script can be vari- ables or functions. 6.6.2. What is scope XML? Scope in a form design is about hierarchy. For example, to access the subform inside in the following XML source, you must type outside.inside. <subform name=“outside”> <subform name=“inside”> 76 Scripting with FormCalc and JavaScript6.6.7. To enable strict scoping 1) Select File > Form Properties and click the Run-time tab. 2) Select Enforce Strict Scoping Rules In JavaScript , if the option is available, and then click OK. NOTE: If the option to enforce strict scoping rules is not available in the Run-time tab, then strict scoping is already enabled. RELATED LINKS: Using JavaScript To attach a JavaScript script to an object 6.7. To attach a JavaScript script to an object You can add a JavaScript script to any form design object that allows calculations and scripts, including the script object. 1) Make sure that you have the multiline version of the Script Editor displayed in the Designer workspace. 2) Select a field on your form. For example, add a new text field to your form design. 3) In the Show list, select a valid event. For example, using the new text field, select the docReady event. 4) In the Run At list, select where you want the script to execute. For example, for the new text field, select Client. 5) Click the Functions icon or F10 to display a list of JavaScript functions. 6) Select the desired function, and press Enter. 7) Replace the default function syntax notation with your own set of values. Alternatively, you can create your own script manually in the Script Source field of the Script Editor. For example, in the new text field, add the following JavaScript to the Script Source field: this.border.fill.color.value = "255,0,0"; 8) Click the Preview PDF tab to test the form. The text appears red for the new button object when the form is displayed in the Preview PDF tab. RELATED LINKS: Using JavaScript79 Variables 77. Variables You can define form variables in Designer to store specific information in a central, accessible loca- tion. A variable typically acts as a placeholder for text that you might have to change in the future. Form variables in Designer are always of the type "string". For example, a variable can store the text of a message box title. When the text needs to change, all you have to do is open the affected form or template and update the text once through the variable definition. Designer automatically propa- gates the new text across all instances of the inserted variable. Keep in mind that form variables are defined outside of the Script Editor, and are accessible by scripts on all objects on a form, as opposed to scripting variables that you create in a specific Form- Calc or JavaScript script. You can create, view, and delete variables without using scripting. However, you must use scripting to access the values stored by variables and manipulate them, or to apply the values to objects on your form. NOTE: Form variable values reset each time you open a form. Before you create a variable, decide the name of the variable and the text that it will contain. Variable definitions are saved with the form or template. 7.1. Naming variables At run time, naming conflicts occur when the names of variables are identical to those used as XML Form Object Model properties, methods, or form design field names. These conflicts can cause scripts to return unexpected values; therefore, it is important to give each variable a unique name. Here a couple of examples: • Use the variable name fieldWidth and fieldHeight instead of x and y. • Use the form design object name clientName instead of name. NOTE: Variable names are case-sensitive and should not contain spaces. 7.2. To define a text variable 1) Select File > Form Properties. 2) In the Variables tab, click New (Insert) . 3) In the Variables list, type a unique name for the variable and press Enter. Variable names are case-sensitive and should not contain spaces. 80 Variables4) Click once in the box to the right and type the text you want to associate with the variable. The variable appears in the Hierarchy palette at the form level. A.New form variable 7.3. To define a text variable 1) Select Edit > Form Properties. 2) In the Variables tab, click New (Insert) . 3) In the Variables list, type a unique name for the variable and press Enter. Variable names are case-sensitive and should not contain spaces. 4) Click once in the box to the right and type the text you want to associate with the variable. The variable appears in the Hierarchy palette at the form level. A.New form variable81 Referencing Objects in Calculations and Scripts 88. Referencing Objects in Calculations and Scripts Although both FormCalc calculations and JavaScript scripts have rules for structuring code, both rely on the same reference syntax when accessing form object properties and values. The XML Form Object Model provides a structured way to access object properties and values through a compound naming convention with each object, property, and method separated by dot (.) characters. In general, each reference syntax has a similar structure divided into the following sections: • The names of the parent objects in the form hierarchy that is used to navigate to a specific field or object. You can use the Hierarchy palette and Data View palette to determine the location of an object relative to other objects in the form and in any associated data. • The name of the object you want to reference. • The the name of the property or method you want to access. This section may also include XML Form Object Model objects that precede the property or method in the structure but that do not appear as objects in the Hierarchy palette. For example, the following illustration shows the reference syntax for accessing the value of a text field on a form design that uses the default object-naming conventions: A. Form hierarchy objects B. Object name C. Property or method name NOTE: By default, the subform object that represents the first page of a new form is unnamed. In the reference syntax above, the unnamed subform is represented by #subform. The reference syntax notation structure varies slightly, depending on the specific situation. For example, a fully qualified reference syntax works in any situation; however, in some cases, you can use a shortened reference syntax or a reference syntax shortcut to reduce the size of the syntax. 84 Referencing Objects in Calculations and Scripts8.1. Referencing object properties and values The reference syntax you use to access or modify object properties and values takes one of the following forms: Fully qualified Reference syntax includes the full object hierarchy, beginning with the xfa root node. The fully qualified syntax accurately accesses the property or value of an object regardless of where the calculation or script that contains the reference syntax is located. Abbreviated The reference syntax is shortened either because of the relative positioning of the calculation or script that contains the reference syntax and the object syntax references, or because short- cuts are used. In general, although an abbreviated reference syntax is faster to create, the disad- vantage is that it works only as long as the objects remain in the same positions relative to each other. For example, this illustration shows the hierarchy of a sample purchase order form. This illustration shows a fully qualified reference syntax, for both FormCalc and JavaScript, to access the value of the txtCondition field. This reference syntax could be used as part of a calculation or script on any object on the form.85 Referencing Objects in Calculations and Scripts 8A. Root Node B. Model C. Form design root node D. Page object E. Subform name F. Object name G. Property or method name NOTE: Even though the reference syntax is common to both FormCalc and JavaScript, you must observe the conventions for each scripting language. For example, the reference syntax in the example above works as is for FormCalc; however, you would need to include a trailing semicolon (;) character for JavaScript. If two objects exist in the same container, such as a subform, they are referred to as sharing the same context. Where objects exist in the same context, you can use an abbreviated reference syntax that includes only the name of the object followed by the property or method you want to access. For example, using the example from above, the following abbreviated reference syntax accesses the value of the txtCondition field from any of the fields in the total subform: txtCondition.rawValue If two objects exist in different containers, they do not share the same context. In this case, you can use an abbreviated reference syntax; however, the syntax must begin with the name of the highest level container object that the two objects do not have in common. For example, using the hierarchy above, the following abbreviated reference syntax accesses the value of the address field from the txtCondition field: header.address.rawValue Due to the way the XML Form Object Model is structured, some object properties and methods exist on child objects of the objects on the form. These child objects exist only as part 86 Referencing Objects in Calculations and Scripts8.3. Referencing the current object If you want to change properties or values of the current object using calculations or scripts attached to the object itself, both FormCalc and JavaScript use unique shortcuts to reduce the size of the refer- ence syntax. FormCalc uses the number sign ($) character to denote the current object, and JavaS- cript uses the keyword this. For example, the following reference syntax returns the value of the current object: $ // FormCalc this.rawValue // JavaScript Similarly, you can use the dollar sign ($) shortcut and the keyword this to replace the name of the current object when accessing object properties in calculations and scripts. For example, the following reference syntax changes the tool tip text associated with the current object: $.assist.toolTip.value = "This is some tool tip text." // FormCalc this.assist.toolTip.value = "This is some tool tip text."; // JavaScript RELATED LINKS: ReferencingObjects in Calculations and Scripts Referencingobject properties and values Referencingunnamed and repeated objects FormCalcreference syntax shortcuts 8.4. FormCalc reference syntax shortcuts To make accessing object properties and values easier, FormCalc includes shortcuts to reduce the effort required to create references. This section describes the reference syntax shortcuts for Form- Calc. 8.4.1. Current field or object Refers to the current field or object Notation $ Example $ = "Tony Blue"89 Referencing Objects in Calculations and Scripts 8The above example sets the value of the current field or object to Tony Blue. 8.4.2. Data model root of xfa.datasets.data Represents the root of the data model xfa.datasets.data. Notation $data Example $data.purchaseOrder.total is equivalent to xfa.datasets.data.purchaseOrder.total 8.4.3. Form object event Represents the current form object event. Notation $event Example $event.name is equivalent to xfa.event.name For more information see Working with the Event Model. 8.4.4. Form model root Represents the root of the form model xfa.form. 90 Referencing Objects in Calculations and ScriptsNotation $form Example $form.purchaseOrder.tax is equivalent to stating xfa.form.purchaseOrder.tax 8.4.5. Host object Represents the host object. Notation $host Example $host.messageBox("Hello world") is equivalent to xfa.host.messageBox("Hello world") For more information, see Working with a Host Application. 8.4.6. Layout model root Represents the root of the layout modelxfa.layout. Notation $layout Example $layout.ready is equivalent to stating91