Publishers of technology books, eBooks, and videos for creative people

Home > Articles > Web Design & Development > PHP/MySQL/Scripting

This chapter is from the book

The Form Object Model

The Adobe XML Form Object Model is based on XFA (the Adobe XML Forms Architecture). The Form Object Model organizes all of the objects and properties of your form into a tree structure. The XFA object is the top-level object, and there are a series of child Document Object Models (DOMs). This section provides information and scripting examples for the different DOMs. You'll find that scripting is easier in Designer once you have a working knowledge of the object model.

The Adobe XML Form Object Model is a topic that deserves its own book. In fact, Adobe has provided two very long technical reference guides to the object model:

  • "Adobe XML Form Object Model Reference for LiveCycle Designer 8.0"
  • "Adobe XML Form Object Model Reference for LiveCycle Designer 7.1"

In the "Navigating the reference documents" section, I'll show you how to retrieve valuable scripting information from these documents.

Understanding the Object Model

The XML Form Object Model is made up of a series of DOMs. Each DOM organizes various objects and properties in computer memory as a tree structure. Each DOM is a child of the root XFA DOM. By navigating these structures with your scripts, you can access the exact object and property you need. But before we look at the specific objects and properties, let's look at the big picture of how the DOMs work together. Figure 4.19 shows the organization of the DOMs included in the XML Form Object model.

Figure 4.19

Figure 4.19 The DOMs of the XML Form Object Model.

The XFA DOM

The XFA DOM is the wrapper for all the other DOMs. You have already been using xfa as the root element in all of your fully qualified scripting expressions. For instance, you have already written the following scripts:

  • xfa.event.newText: This script calls the newText property, which is part of the event object in the XFA DOM.
  • xfa.resolveNode(): This script calls the resolveNode method of the XFA DOM.

    This xfa root element will also be the prefix when you make a reference to one of its child DOMs.

  • xfa.layout.pageCount(): This script calls the pageCount property of the Layout DOM.

The Template DOM

The Template DOM contains information about the form design. You will rarely, if ever, script against this DOM. The Form DOM has all of the same objects as the Template DOM as well as a few others. The Form DOM also has access to the data, but the Template DOM does not.

The Data DOM

The Data DOM contains the data structure and content. You can use this DOM to access any data element. However, you typically will only use this DOM to access hidden data. The Template and the Data DOM merge to create the Form DOM, and many of the data elements are bound to elements in the form DOM. Once these data elements are bound to form elements, you can access them by referencing the objects in the Form DOM.

The Form DOM

The Form DOM contains the Template DOM and the Data DOM. You will use this DOM for most of your scripting.

The Layout DOM

The Layout DOM contains page-specific information. You will use this DOM to write scripts to access specific page numbers or to retrieve a total page count or other page-related requirements, just as you did in a previous example:

this.rawValue = xfa.layout.pageCount()

Scripting the Form Object Model

All DOMs are not created equal when it comes to scripting. As you can see in Figure 4.20, certain DOMs provide more value for your form scripting. Open the file formObjectModel.pdf from the Samples folder for the exercises in this section.

Figure 4.20

Figure 4.20 Scripting the Form Object Model.

The Form DOM—the scripting default

The Form DOM is the most useful DOM because you can access both presentation and data information. The Form DOM is also the default DOM for all Designer scripting. You do not need to explicitly include the word form in your SOM expression, but it will work if you do.

Your sample form has two buttons—FormDOM_Explicit and FormDOM_Implicit—that accomplish the same task. The first button, FormDOM_Explicit sets the rawValue property of username to "John Warnock" by referencing the Form DOM explicitly:

xfa.form.order.page1.username.rawValue = "John Warnock";

The second button refers to the Form DOM implicitly:

username.rawValue = "John Warnock";

There are actually two reasons that the abbreviated statement works. I discussed the first reason in the previous section on referencing objects. The abbreviated reference works because the button and text field are both part of the same container object. The second reason that this abbreviated statement works is because it references an object and property in the Form DOM, and the Form DOM is the default for scripting.

The formObjectModel.pdf has a more advanced example of accessing the Form DOM objects with scripting. Select Preview PDF and enter 3 in the numberOfPants text field. When you press the Enter key or when you tab out of the field, the form creates three line items containing a length and width text field for each pair of pants (Figure 4.21).

Figure 4.21

Figure 4.21 A new line item is added based on the number of pants that the form filler requests.

Go back to Design View and select the numberOfPants text field. You will see the following script in the exit event:

var numField = this.rawValue;
var count = xfa.form.order.page1.flowedSubform.positionedSubform.all.length
var t;
var r=0;
if(count > 1){
   for(t = 0; t < count-1; t++){
      xfa.form.order.page1.flowedSubform.positionedSubform.instanceManager.removeInstance(1);
   }
}
for(t = 0; t<=numField -2; t++){
   xfa.form.order.page1.flowedSubform.positionedSubform.instanceManager.addInstance(1);
}

This script explicitly calls the form object to create a new instance of the pantDetails subform. A new instance is added by calling the addInstance() method of the subform's instance manager.

Accessing data values with the Data DOM

You will typically use the Form DOM to access data values in your scripting. The Form DOM contains the data elements that are bound to your form elements. However, if you need to access hidden data values that are not bound to a form element, you will use the Data DOM.

Open the dataDOM.pdf file in Designer to see an example of scripting the Data DOM. In this example, a form filler can cycle through a series of shirt colors and the form will immediately update with new values from the data file (Figure 4.22).

Figure 4.22

Figure 4.22 Cycling through shirt colors in the sample dataDOM.pdf file.

This form uses the shirtColor.xml file from the Samples folder, which contains the RGB (Red, Green, Blue) equivalents of six colors. If you receive a warning message about this file when you launch the PDF form in Designer, you may need to reestablish the link with this file. Simply select Form > Form Properties > Defaults and reestablish the link in the Data File field:

<ShirtColor>
   <entry>
      <Color>0,0,255</Color>
   </entry>
   <entry>
      <Color>255,0,0</Color>
   </entry>
   <entry>
      <Color>0,0,0</Color>
   </entry>
   <entry>
      <Color>255,128,0</Color>
   </entry>
   <entry>
      <Color>0,255,0</Color>
   </entry>
   <entry>
      <Color>255,255,0</Color>
   </entry>
</ShirtColor>

This example uses various methods of the dataWindow object. The XFA dataWindow object represents all of the data records that are currently loaded into memory. You can see the following dataWindow methods in the click events of their respective buttons

  • First button: The click event of the First button contains the following script that takes you to the first record, which is blue (R = 0, Green =0, Blue=255):
    xfa.dataWindow.gotoRecord(0);
    
  • Previous button: The click event of the Previous button contains the following script, which performs two actions. The first action verifies that the current record is not the first record in the dataWindow. If it is, the script provides a message box that informs users that they are on the first record. If it is not, the script calls the moveCurrentRecord method of the dataWindow object:
    if (xfa.dataWindow.recordsBefore > 0) {
      xfa.dataWindow.moveCurrentRecord(-1);
    }
    else {
      app.alert("This is the first record in the data file.");
    }
    
  • Next button: The click event of the Next button contains a script that is similar to the Previous button but in this case it verifies that users are not on the last record of the dataWindow:
    if (xfa.dataWindow.recordsAfter > 0) {
      xfa.dataWindow.moveCurrentRecord(1);
    }
    else {
      app.alert("This is the last record in the data file.");
    }
    
  • Last button: The click event of the Last button contains the following script, which takes users to the last record. The last record is calculated by adding the index value of the current record to the number of records after the current record:
    xfa.dataWindow.gotoRecord(xfa.dataWindow.currentRecordNumber + xfa.dataWindow.recordsAfter);

For this example to function, you need to manually add a line of code to the XML source for the form. To view this line of code, switch to the XML Source tab and do a search for the following line of code using Designer's Find feature in the Edit menu:

<record>entry</record>

Event and host objects in the XFA DOM

The XFA DOM has two important objects that you have already used in previous scripts:

  • The event object: By scripting the event object, you can retrieve information about form changes that occur before, during, and after actions take place. These actions include events that are fired as the form is rendered as well as interactive events that are fired by the form filler's actions. You saw an example of this object in the "Getting and setting properties" section. There is another example in the "Sending Email Through Scripts" section in Chapter 6.
  • The host object: The host object refers to the container for your form, which will most likely be Adobe Acrobat or Adobe Reader, but it could be a Web browser. This object, which includes the message box, is only available at runtime.

The following script uses the host object to determine the container for your form:

TextField1.rawValue = xfa.host.name + " " + xfa.host.version;

On my computer, this script produces the string "Acrobat 8" because that is my container name and version number. Yours may be different. You can see more examples of how the host object is used in scripting in these sections of Chapter 6: "Message Box Scripts," "Working with Page Numbers," "Disabling All Form Fields."

Accessing page information with the Layout DOM

The Layout model is the final in-memory representation of the form. As mentioned previously, you will script against the Layout DOM to access page-related information. The Form DOM does not contain this page-related information. The following script shows how to access the Layout DOM to retrieve the current page number:

TextField1.rawValue = xfa.layout.page(this);

The previous script that counted the number of text fields in a form also referenced the Layout DOM:

var oFields = xfa.layout.pageContent(nPageCount, "field");

No scripting with the Template DOM

You typically do not script against the Template DOM for two reasons. First, the Form DOM has all of the same objects as well as some additional objects. Also, the Form DOM has access to the form's data so it is a much better DOM to script against. Second, the Template DOM is simply more difficult to work with than the Form DOM. According to Adobe, you will need, "a thorough understanding of the merge and layout processes. In some cases, you have to request a remerge and relayout to see the results of any changes." I have never used this DOM for any real-world programming work.

Navigating the reference documents

The current "XML Form Object Model Reference" from Adobe weighs in at a trim 412 pages (Figure 4.23). The previous version for Designer 7.1 was a full 695 pages, which made it a rather heavy PDF to carry around. Both documents have all the detailed information that you need about the objects, properties, and methods of the XML Form Object Model. However, these reference documents are long and very technical. I recommend navigating these documents using their internal PDF links.

Figure 4.23

Figure 4.23 "XML Form Object Model Reference" in Adobe Acrobat.

Follow these steps to navigate the reference documents to get information about the messageBox object:

  1. Open the reference document in Acrobat or Reader. This example uses the version 8 document.
  2. Select the "XML Form Object Model DOMs" section under the "Understanding the XML Form Object Model" section.
  3. Select the Host Model and under the Host Model header, select the link titled, "'hostPseudoModel' on page 78."
  4. Page 78 lists all the properties and methods of the host object. Select the messageBox link to see detailed information on the messageBox. The message box has the following syntax:
    messageBox(STRING param1, STRING param2, INTEGER param3, INTEGER param4)
    
    The parameters are also listed and described in Table 4.2.

    Table 4.2. Parameters for the MessageBox

    Parameter

    Description

    param1

    A valid string representing the message to display

    param2 (optional)

    A valid string representing the title to appear in the title bar

    param3 (optional)

    An integer representing the icon to display in the dialog box 0 (Error) default, 1 (Warning), 2 (Question), 3 (Status)

    param4 (optional)

    An integer representing the buttons to display 0 (OK) default, 1 (OK, Cancel), 2 (Yes, No), 3 (Yes, No, Cancel)

  5. FormCalc and JavaScript scripting examples are also located below the parameters table. These are usually useful, but in this case the syntax for the JavaScript example is wrong. The syntax description is correct, but the example is wrong. The following example creates the messageBox illustrated in Figure 4.24.
    Figure 4.24

    Figure 4.24 This messageBox is created by setting all of the optional parameters of the messageBox object.

    xfa.host.messageBox("This is the message", "This is the title", 2,3);
    

As you can see, these documents are chock full of valuable information. Along with a good book on JavaScript and this chapter, you will be able to use these documents to write any scripts that your forms require.

Peachpit Promotional Mailings & Special Offers

I would like to receive exclusive offers and hear about products from Peachpit and its family of brands. I can unsubscribe at any time.

Overview


Pearson Education, Inc., 221 River Street, Hoboken, New Jersey 07030, (Pearson) presents this site to provide information about Peachpit products and services that can be purchased through this site.

This privacy notice provides an overview of our commitment to privacy and describes how we collect, protect, use and share personal information collected through this site. Please note that other Pearson websites and online products and services have their own separate privacy policies.

Collection and Use of Information


To conduct business and deliver products and services, Pearson collects and uses personal information in several ways in connection with this site, including:

Questions and Inquiries

For inquiries and questions, we collect the inquiry or question, together with name, contact details (email address, phone number and mailing address) and any other additional information voluntarily submitted to us through a Contact Us form or an email. We use this information to address the inquiry and respond to the question.

Online Store

For orders and purchases placed through our online store on this site, we collect order details, name, institution name and address (if applicable), email address, phone number, shipping and billing addresses, credit/debit card information, shipping options and any instructions. We use this information to complete transactions, fulfill orders, communicate with individuals placing orders or visiting the online store, and for related purposes.

Surveys

Pearson may offer opportunities to provide feedback or participate in surveys, including surveys evaluating Pearson products, services or sites. Participation is voluntary. Pearson collects information requested in the survey questions and uses the information to evaluate, support, maintain and improve products, services or sites; develop new products and services; conduct educational research; and for other purposes specified in the survey.

Contests and Drawings

Occasionally, we may sponsor a contest or drawing. Participation is optional. Pearson collects name, contact information and other information specified on the entry form for the contest or drawing to conduct the contest or drawing. Pearson may collect additional personal information from the winners of a contest or drawing in order to award the prize and for tax reporting purposes, as required by law.

Newsletters

If you have elected to receive email newsletters or promotional mailings and special offers but want to unsubscribe, simply email ask@peachpit.com.

Service Announcements

On rare occasions it is necessary to send out a strictly service related announcement. For instance, if our service is temporarily suspended for maintenance we might send users an email. Generally, users may not opt-out of these communications, though they can deactivate their account information. However, these communications are not promotional in nature.

Customer Service

We communicate with users on a regular basis to provide requested services and in regard to issues relating to their account we reply via email or phone in accordance with the users' wishes when a user submits their information through our Contact Us form.

Other Collection and Use of Information


Application and System Logs

Pearson automatically collects log data to help ensure the delivery, availability and security of this site. Log data may include technical information about how a user or visitor connected to this site, such as browser type, type of computer/device, operating system, internet service provider and IP address. We use this information for support purposes and to monitor the health of the site, identify problems, improve service, detect unauthorized access and fraudulent activity, prevent and respond to security incidents and appropriately scale computing resources.

Web Analytics

Pearson may use third party web trend analytical services, including Google Analytics, to collect visitor information, such as IP addresses, browser types, referring pages, pages visited and time spent on a particular site. While these analytical services collect and report information on an anonymous basis, they may use cookies to gather web trend information. The information gathered may enable Pearson (but not the third party web trend services) to link information with application and system log data. Pearson uses this information for system administration and to identify problems, improve service, detect unauthorized access and fraudulent activity, prevent and respond to security incidents, appropriately scale computing resources and otherwise support and deliver this site and its services.

Cookies and Related Technologies

This site uses cookies and similar technologies to personalize content, measure traffic patterns, control security, track use and access of information on this site, and provide interest-based messages and advertising. Users can manage and block the use of cookies through their browser. Disabling or blocking certain cookies may limit the functionality of this site.

Do Not Track

This site currently does not respond to Do Not Track signals.

Security


Pearson uses appropriate physical, administrative and technical security measures to protect personal information from unauthorized access, use and disclosure.

Children


This site is not directed to children under the age of 13.

Marketing


Pearson may send or direct marketing communications to users, provided that

  • Pearson will not use personal information collected or processed as a K-12 school service provider for the purpose of directed or targeted advertising.
  • Such marketing is consistent with applicable law and Pearson's legal obligations.
  • Pearson will not knowingly direct or send marketing communications to an individual who has expressed a preference not to receive marketing.
  • Where required by applicable law, express or implied consent to marketing exists and has not been withdrawn.

Pearson may provide personal information to a third party service provider on a restricted basis to provide marketing solely on behalf of Pearson or an affiliate or customer for whom Pearson is a service provider. Marketing preferences may be changed at any time.

Correcting/Updating Personal Information


If a user's personally identifiable information changes (such as your postal address or email address), we provide a way to correct or update that user's personal data provided to us. This can be done on the Account page. If a user no longer desires our service and desires to delete his or her account, please contact us at customer-service@informit.com and we will process the deletion of a user's account.

Choice/Opt-out


Users can always make an informed choice as to whether they should proceed with certain services offered by Adobe Press. If you choose to remove yourself from our mailing list(s) simply visit the following page and uncheck any communication you no longer want to receive: www.peachpit.com/u.aspx.

Sale of Personal Information


Pearson does not rent or sell personal information in exchange for any payment of money.

While Pearson does not sell personal information, as defined in Nevada law, Nevada residents may email a request for no sale of their personal information to NevadaDesignatedRequest@pearson.com.

Supplemental Privacy Statement for California Residents


California residents should read our Supplemental privacy statement for California residents in conjunction with this Privacy Notice. The Supplemental privacy statement for California residents explains Pearson's commitment to comply with California law and applies to personal information of California residents collected in connection with this site and the Services.

Sharing and Disclosure


Pearson may disclose personal information, as follows:

  • As required by law.
  • With the consent of the individual (or their parent, if the individual is a minor)
  • In response to a subpoena, court order or legal process, to the extent permitted or required by law
  • To protect the security and safety of individuals, data, assets and systems, consistent with applicable law
  • In connection the sale, joint venture or other transfer of some or all of its company or assets, subject to the provisions of this Privacy Notice
  • To investigate or address actual or suspected fraud or other illegal activities
  • To exercise its legal rights, including enforcement of the Terms of Use for this site or another contract
  • To affiliated Pearson companies and other companies and organizations who perform work for Pearson and are obligated to protect the privacy of personal information consistent with this Privacy Notice
  • To a school, organization, company or government agency, where Pearson collects or processes the personal information in a school setting or on behalf of such organization, company or government agency.

Links


This web site contains links to other sites. Please be aware that we are not responsible for the privacy practices of such other sites. We encourage our users to be aware when they leave our site and to read the privacy statements of each and every web site that collects Personal Information. This privacy statement applies solely to information collected by this web site.

Requests and Contact


Please contact us about this Privacy Notice or if you have any requests or questions relating to the privacy of your personal information.

Changes to this Privacy Notice


We may revise this Privacy Notice through an updated posting. We will identify the effective date of the revision in the posting. Often, updates are made to provide greater clarity or to comply with changes in regulatory requirements. If the updates involve material changes to the collection, protection, use or disclosure of Personal Information, Pearson will provide notice of the change through a conspicuous notice on this site or other appropriate way. Continued use of the site after the effective date of a posted revision evidences acceptance. Please contact us if you have questions or concerns about the Privacy Notice or any objection to any revisions.

Last Update: November 17, 2020