Tutorials, tools, scripts and samples for scripting Acrobat and PDFpdfscripting.com
HomeVideo TutorialsCopy-n-Paste ScriptsDownload LibraryFree ContentSearchMEMBERS LOG-IN
Home | LiveCycle Form Scripting

LiveCycle Form Scripting

* What is LiveCycle? Discussion
* Resources, Video Tutorials and Sample Files
* Articles and Scripts

What is a LiveCycle Form

LiveCycle forms are the "Other" forms technology in Acrobat and PDF. They are famous for their ability to grow and change to fit any amount of data, to connect to data sources and to easily handle repeatable data (such as the line on an order form). This is a highly dynamic, data oriented forms model that has many advanced features that traditional Acrobat forms will never achieve. However, by using a LiveCycle form you lose many standard Acrobat and PDF features. So, before getting into the details of form design and scripting, it's good to get a birds-eye view of how LiveCycle forms work and fit into the Acrobat and PDF environment.

Putting LiveCycle Forms into Perspective

Interactive form features were added to PDF in version 3 of Acrobat. This is the traditional Acrobat Forms Model (AcroForms). This forms technology is seamlessly integrated into PDF, so that all PDF and Acrobat features are available to an AcroForm. AcroForms are, for an interactive form, somewhat static because PDF is a mostly static document technology.

LiveCyle forms are a very different technology. They are dynamic because they are not really PDFs. They operate on a completely different rendering and scripting engine inside of Acrobat than do standard PDF files. This LiveCycle engine was first added to Acrobat in version 6. But at that time it wasn't documented or made public. It was first officially announced in Acrobat 7, which was also the first Acrobat version to include LiveCycle Designer in the Acrobat installer.

LiveCycle, or XFA forms require a different rendering and scripting engine because under the covers it is a completely different animal than AcroForms. A LiveCycle form is defined by an XML template. The XML grammar for this template is called XFA, so LiveCycle forms are often referred to as XFA forms. To create a complete interactive form the template is combined, or merged, with data. So, there is also an XML data model and some other supporting information such as localization (language) data. All these blocks of XML are combined into the XML Data Package (XDP). This XDP represents a complete form.

How LiveCycle Forms are Made

Creating the XDP requires a special design tool. It cannot be done with Acrobat since Acrobat is not a document design tool. This is why LiveCycle Designer, which is a completely separate application, is included in the Acrobat Professional installation- to give users the ability to create XDP files. Unfortunately, Adobe has not been keen to make this distinction clear to users. Clicking on the "Forms > Create New Form..." menu item in Acrobat 8, or the "Forms > Start Form Wizard..." menu item in Acrobat 9, dumps the user into LiveCycle Designer. To the uninitiated, it appears as if LiveCycle Designer is part of Acrobat and that it is the only option for creating a form, neither of which are true.

Once created, the XDP can be rendered into any displayable document technology for which someone was willing to write a converter. But, of course LiveCycle Designer only generates PDF files or writes out raw XDP. There is no such thing as an XDP viewer. So unless you have the LiveCycle ES forms server, your only choice for rendering an XFA form is PDF. The LiveCycle Servers can render to HTML, but for all practical purposes this is not a real option.

The PDF created by LiveCycle Designer is a wrapper for the raw XDP. If you were to look inside the PDF at the low level (COS) object structure, you'd see the XDP components that are generated by LiveCycle Designer, verbatim.

LiveCycle Forms Operation

When the LiveCycle form is opened, Acrobat switches the way is does things. It first reads all the XML data stored in the PDF and then merges the XFA template, the data model, and any other supporting information to create the complete runtime form. Acrobat turns off its normal page rendering engine and turns on the special XFA rendering engine. The runtime model is then used to generate the actual page views that can be displayed and interact with the user.

Acrobat also selectively turns off parts of the traditional JavaScript engine and several standard PDF features. In general, it turns off anything that has to do with pages, since the pages are rendered with the LiveCycle Engine. These features include anything involving form fields, annotations, OCG layers, and multimedia. However, many document level features are still available, such as bookmarks and file attachments. These document level features are not part of the XFA model, but they are part of the PDF file wrapper. So, a useful and practical way to think about XFA PDF forms is that the document is a PDF file, a kind of frame for the pages, which are purely XFA and have nothing to do with PDF.

LiveCycle Form Scripting Environment

Along these same lines, XFA forms have their own scripting model that is completely unrelated to the traditional Acrobat scripting model. However, this model is an addition to the traditional Acrobat JavaScript model. It is not a replacement. The XFA scripting model only deals with things that are completely within the XFA template. So all the parts of the Acrobat Scripting model that have to do with the Acrobat application (the app object), the document level (the doc object), and all of the supporting objects such as security, remain valid. In fact, the XFA scripting model is actually a member of the document object. The relationship between objects in the traditional AcroForm Scripting Model and the XFA Scripting Model is shown in the figure below.

The entire XFA Scripting Model for a form can be accessed from the Document Object in the traditional Acrobat Scripting Model. And the reverse is also true. The entire Acrobat Scripting Model can be accessed from inside the XFA Scripting Model. These two scripting environments, while being very different, exist side by side and can be used together.



Articles and Scripts

LiveCycle Scripting: Connecting a Form to a Database
Database, Data Handling, XFA, Automation
LiveCycle PDF forms have a built-in ability to connect to a database through OLE DB drivers. While it can be extremely useful to have a direct connection between a form and an . . . keep reading
Radio Buttons in LiveCycle PDF Forms
LiveCycle, Form Controls
Radio Buttons are a common user interface element found on almost every type of platform. They are a selection device for choosing one option from a set mutually exclusive options (Figure 1). Cont . . . keep reading
LiveCycle Scripting: Overriding Calculations
LiveCycle, Calculation
There are times when it's useful to have a field value that is calculated, but can also allow the user to enter data, i.e., to override the calculated value. This is a tricky proposition since th . . . keep reading
Connecting a LiveCycle PDF form to an Excel File
LiveCycle, Data Handling, Database
LiveCycle PDF forms have the ability to be connected directly into a datasource, and even an Excel file. But to do this the Excel file has to be setup in a particular way. This article covers the details. . . . keep reading
Counting Text items: Characters, Words and Lines
Thom Parker
There are many commercial applications (press releases, product descriptions, ad text, etc.) as well as others where counting text elements like characters and words is important. The scripts on this page provide several different techniques for finding this information, including filtering text for specific characters and words. . . . keep reading