If you work in an enterprise setting, chances are you may have already had to deal with corporate data schemas that define how that data is structured. The goal, when connecting a form to a schema, is to ensure that the data consumed and output by the form adheres to a specific structure. Any fields bound to data nodes that aren’t inside the schema space are basically ignored at time of submission.

To help put things in context, I decided to define a schema for movie rentals to stay on the movie theme for the data I used in my other data connection tutorials.

Before we get started, I wanted to point-out that there are so many features related to schema handling and the Data View palette that I won’t be able to cover them all in a single tutorial. It would be information overload. Instead, I’ll try to point-out the basics along with a few interesting things that I think would be useful.

Creating the Connection

Right-click in the Data View palette and choose “New Data Connection”. In the first step, set the name for the connection (I set it to “SchemaConnection” so it’s easy to identify amongst any other connections that might be defined) and choose “XML Schema” as the type.

Note that while you may have multiple ODBC and web service data connections, a form may be connected to only one schema. As of XFA 3.0 (Designer ES2, Acrobat/Reader 9.1), however, you can inject foreign data nodes into the Data DOM even if they aren’t in the schema, which may help if you need to get extra data into/out of your form (a topic for another post; for now, have a look at the new “File > Form Properties > Data Binding tab” in the Designer ES2 Beta). You can also merge schemas into a single, larger schema (<import/> nodes are supported which can make importing multiple schemas into a single one relatively easy).

The next and final steps are to choose the schema file and root element. Depending on how your schema is defined, you may have a choice of elements to use as the root. In the Movie Rental schema, there is only one root: “movieRental”.

There are other options that let you embed the schema definition into your form (good if you don’t want to have to keep the schema file along with your form; otherwise, whenever you edit your form, you will need to ensure that the schema file is available) as well as specify XSLT files for incoming and outgoing data transformations (also a topic for another post).

Data View Palette

The initial view of the connection in the palette shows the data structure specified by the schema as represented in XFA. Each node in the schema gets an associated XFA object type depending on its description.

For example:

• Complex types (such as {customer} and {movie}) are usually mapped to subforms since they are elements that contain child elements.
• Simple types (such as {customer.firstName} and {customer.prov}) are typically mapped to XFA fields. As you can see, the Schema Data Connection Wizard detected various types and assigned specific XFA fields to each data node: The {customer.prov} node is set to a drop down list because that element is defined as an enumeration of specific values in the schema while {movie.cost} is set to a decimal field because it’s type is “xs:decimal”.

Root Subform Name

When the connection was created, there was a change to your form’s root subform name. Note how it has changed to movieRental:

The name of the root subform is always the name of the root data element in the Data DOM. This ensures that data submitted from the form has the correct root element to match the schema and data merged into the form will be bound first by the root subform, then by child form objects.

Inserting New Fields

The Data View palette can be used to insert fields into your form. This makes it really easy to create new fields with the proper settings and bindings. You can customize how fields are created by choosing “Palette menu button > Options”:

• Generate Validation Scripts: If enabled, field Validate events will be generated for elements that have certain restraints defined in the schema.
• Generate Descriptive Information: If enabled, particular forms of metadata in the schema will be inserted into the field definitions in your form (more on this in another post).
• Allow Tables to be Generated: If enabled, tables, rather than plain subforms, will be generated where appropriate.
• Show Binding Properties Dialog Box: If enabled and you drag & drop an element onto an existing field, a customization dialog will be displayed (more on this later).

To insert a new field configured according to an element in the schema, just drag & drop the element from the connection tree (in the Data View palette) into your form. You can add an entire group in a single operation by dragging a container element (e.g. {customer}). When a field in your form is bound to an element in the schema, a binding icon is displayed next to the element in the connection tree.

Start by dragging and dropping the {customer} element into your form. The result should be a new subform named “customer” containing 8 fields named according to the schema’s {customer} element and the elements it contains.

New fields on the form.

New structure in the hierarchy.

Notice how each leaf element in the connection now has a binding icon next to it in the connection tree (indicating that fields on the form are bound to those schema elements). The inserted fields were also customized according to their schema element counterparts. For example:

• All fields have appropriate data bindings (see “Object palette > Bindings tab > Data Binding property”).
• The {customer.prov} element became a drop down list which has a list of items, as well as a default value of “ON”, as specified in the schema.
• All new form objects have names that match their schema element names (though these could be altered, if better suited to any scripting requirements you may have, without affecting the data bindings).
• All new form objects have captions that are derived from their schema element names (e.g. the field bound to {customer.firstName} has a caption of “First Name”).

Next, drag and drop the {movie} element from the connection into your form. This element is special because the schema specifies it may have multiple occurrences:

<xs:element
    name="movie"
    type="movieDef"
    minOccurs="1"
    maxOccurs="unbounded"/>

The result is a repeatable subform, as you can see by the Binding properties that were automatically set on the new “movie” subform (bound to movie[*] with Min Count set to 1 and no specified Max Count (unbounded)):

(Note that if the properties on the “Object palette > Binding tab” are partially disabled, it’s most likely because the movie subform is not inside a flowed container. Though it isn’t an XFA requirement, Designer requires it in order to enable the repeatable properties. We’ll fix this shortly.)

Binding to Existing Fields

There are two ways to bind an existing field to an element in the schema connection:

1. Simply choose the element to which the field should bind by using the “Object palette > Binding tab > Data Binding property” pop-out menu (button to the right-hand side of the property) and selecting it from within the schema connection’s sub menu.
2. Drag an element from the connection tree, in the Data View palette, and drop it on top of a field in your form. Doing so will — if it’s enabled — cause the Binding Properties Dialog Box to be displayed, giving you some options to further customize the existing field with information from the schema.

Binding Properties Dialog Box

Add a new text field to your form. This will be for the {returnBy} schema element. Ensure that the “Show Binding Properties Dialog Box” option is checked in the “Data View palette > Palette menu button > Options” dialog. Now drag the {returnBy} element from the connection and drop it on top of the new text field.

The above dialog will be displayed, giving you the option to update the following properties of the field on which the schema element was dropped:

• Name: Updates the name of the field to match the name of the schema element (from “TextField1″ to “returnBy”).
• Caption: Updates the caption of the field to one derived from the schema (from “Text Field” to “Return By”).
• Type: Updates the field’s object type to match the kind of data represented by the schema element (from text field to date/time field).
• Type > Default Value: Updates the field’s default value to that specified in the schema, if any (in the case of {returnBy}, the schema does not specify a default value).
• Type > Data Pattern: Updates the field’s patterns (display, edit, validate, data) according to the schema (in the case of {returnBy}, no pattern restrictions are specified in the schema, though a “date{YYYY-MM-DD}” data pattern will be set by default).

Choose the “Update all related properties” option and click on the “OK” button. The text field you previously inserted will be updated to a date/time field with various properties matching the {returnBy} schema element’s specifications (as detailed above).

Finishing Touches

At this point, your form should look something like this (the positioning of the objects may differ depending on where you dropped them):

Here are a few steps you can take to make things look a little nicer (in my opinion) as well as enable instances of the movie subform to be added for new movies to rent:

1. Place the movie subform in a flowed subform so that multiple instances can be added, flowed one after the other.
2. Place an “add” button next to the movie subform to add instances as well as a “remove” button inside the movie subform to remove specific instances.
3. Add an unbound decimal field that shows the running total cost for the movie rental order.
4. Add script to the returnBy field to automatically set the date 30 days in the future.
5. Add a submit button to submit the order.

Following the steps above should yield a more functional movie rental form. The only thing missing is the ability to pull-in movies to choose from. For one thing, this would avoid having to specify the movie ID, title and cost when choosing a movie to rent. To accomplish this, you could connect the form to a movie database (note that the database in the linked tutorial doesn’t have a “cost” column associated to a movie so you’ll have to add one) or, the more secure and recommended way, to a movie web service.

Download Sample Form [pdf]

Download Schema [xsd]

Download Sample Data [xml]

Minimum Requirements: I designed this form using Designer ES2 Beta and Acrobat 9.1 however the principals should work all the way back to Designer 7.1 and Acrobat 7.0.5. There may be a few features lacking from the Data View palette if you go back that far but the concept of connecting the form to a schema remains the same.

Aug 28, 2009 — Added link to Schema Metadata tutorial.

Nov 4, 2009 — Fixed a couple of syntax errors in the sample PDF form that were preventing the addition and removal of movie subform instances.

Before we get started, you’ll need Designer 7.1 and Acrobat/Reader 7.0.5 at minimum to run through this tutorial. I will be using Designer 8.2 and Acrobat/Reader 9.0 to do the tutorial so it’s possible some of the UI may have changed slightly since the 7.1/7.05 versions.

Creating the Table

The first step is to drag a Table object from the Object Library palette’s Standard tab into your form. When you drop it, the Insert Table wizard appears. Set it to include 5 columns, 1 body row and header and footer rows:

Headers and Footers

Double-click on the first “Header” cell and set the text/caption to “#”. This will be the dynamic index column. Set the remaining headers as follows: “Item”, “Quantity”, “Cost”, “Total”.

In the footer, we only need two cells: One with a caption that reads, “Grant Total:”, and the other for the calculated grand total. To start, select the first 4 footer cells by Ctrl-Clicking each one:

Then, with the cells selected, click on the “Merge Table Cells” button in the Object palette (highlighted in yellow in the image below):

The 4 cells will merge into one and you can then double-click the text to change it to “Grand Total:”. While you’re editing the text, use the Paragraph palette to align it to the right.

We’re pretty much done with the header and footer row except for the grand total cell but we’ll come back to that after the body row has been defined.

Body Row

What we want for the body row is a text/read-only cell for the row number, a drop down list for selecting items, a numeric cell for the quantity, a numeric/read-only cell for the cost (which will be set depending on the selection in the item list) and a numeric/read-only cell for the calculated total (quantity * cost) for the row.

The first thing to do is to rename the “Row1″ body row to “Item” and set it to repeat for each data item by selecting Row1 from the Hierarchy palette and setting its “Object palette > Binding tab > Name property” to “Item”, its “Default Binding” property to “Normal” and checking its “Repeat Row for Each Data Item” property to enable it to repeat so that the table can expand.

Row Number Cell

While this may sound complex, it’s actually quite easy to achieve. Since the Item body row will repeat, it will have an index and the index will be zero-based. This means our row number is simply the index of the cell’s parent (Item body row) + 1.

Drop a text field from the Object palette onto the first cell in the Item row. This will change the cell’s type to a text field. Set its name to “ItemIndex” (not just “index” because it’ll cause conflicts with the Item row’s index property), its “Object palette > Binding tab > Default Binding property” to “None” (since we don’t need the index in the submitted data — it’s just for show, after all) and its “Object palette > Value tab > Type property” to “Calculated – Read-Only”.

Finally, using the Script Editor, set its Calculate event to the following JavaScript code:

(this.parent.index + 1) + ".";

If we preview the form at this point, we’ll see that the first and only Item row has a row number of “1.”:

Item Name and Cost Cells

The next cell is the item name. This will be a drop down list with a few items to choose from which have associated values that we’ll use to set the cost field depending on the selected item.

Drop a down down list from the Object Library onto the second cell in the Item row. Set its name to “ItemName” (not just “name” because it’ll cause conflicts with the Item row’s name property) and add some items to it using the Object palette’s Field tab. The following image shows that I’ve populated my list with 3 items:

An important thing to note here is that we did not associate values as costs to each item. It would’ve been convenient to store them like that however if we had, the item’s name would’ve shown-up as the cost in the submitted data which is not the intention. When data is submitted, we want the item’s name (e.g. “Helmet”) to show-up as the ItemName data.

With the ItemName cell defined, we need to setup the Cost cell so that we can set its value to the value associated with the selected item.

Drop a numeric field from the Object Library onto the 4th cell (the 3rd cell is for quantity) in the Item row. Set its name to “Cost”, its “Object Palette > Binding tab > Data Format property” to “Float”, its Value Type to “Read-Only” and its Display Pattern to “num{($zzzz9.99)}” (without the double-quotes).

Now set the following JavaScript code as the Change event for the ItemName drop down list:

switch (xfa.event.newText)
{
    case "Helmet":
        Cost.rawValue = 45.00;
        break;

    case "Pedals":
        Cost.rawValue = 150.00;
        break;

    case "Wheel":
        Cost.rawValue = 225.00;
        break;

    default:
        // unknown item
        Cost.rawValue = 0;
        break;
}

This simple script looks at the new selection in the ItemName list and sets the Cost field’s value accordingly.

At this point, we preview the form and choose “Pedals” as the item, the Cost cell will get a value of “150″ which will be displayed as “$150.00″ because of the display pattern we set on the Cost field earlier:

Quantity Cell

With the ItemName and Cost cells defined, we can now define the Quantity cell. This one is quite simple: Drop a numeric field onto the 3rd cell in the Item row. Set its name to “Quantity” and its default value to 1.

Total Cell

The last cell in the Item row is the one what will show the total for that Item which is “Quantity * Cost”. This is another easy one: Drop a numeric field onto the 5th cell in the Item row. Set its name to “Total”, its Default Binding to “None” (no need to store calculated values in the data), its Value Type to “Calculated – Read-Only”, its Display Pattern to “num{($zzzz9.99)}” (without the double-quotes) and its Calculate event to the following FormCalc code:

Quantity * Cost

That’s it! FormCalc is great for spreadsheet-like calculations and in FormCalc, the “rawValue” property is implied so you don’t need to specify it like in JavaScript.

At this point, previewing our form and choosing “Pedals” as the item shows a calculated total of “$150.00″ for that item:

Footer Grand Total Cell

Now that the Item body row is complete, we just have a couple of things left to do. First, we need to setup the Grand Total field in the footer row which will display the grand total of the order. This field will be a numeric/read-only field which will calculate the sum of all Total fields in all Item rows that exist. This may sound complicated but once again, FormCalc makes this easy-as-pie.

Drop a numeric field onto the 5th (or 2nd or last) cell in the footer row. Set its name to “GrandTotal”, its Default Binding to “None” (no need to store calculated values in the data), its Value Type to “Calculated – Read-Only”, its Display Pattern to “num{($zzzz9.99)}” (without the double-quotes) and its Calculate event to the following FormCalc code:

Sum(Item[*].Total)

You’re probably wondering what the “[*]” notation means. Put simply, it’s like a wildcard for the index of the Item row and it tells the Sum function to get the value of the Total field in all instances of the Item row and calculate their sum.

At this point, if we preview our form and choose “Pedals” as the item, the total and grand total values are automatically calculated:

Adding/Removing Items

Last but not least, we need a mechanism to add and remove items in the table. Since we had the Item row repeatable, this will be done using the Instance Manager associated with the Item row.

To start, place two buttons on the form and name them “Add” and “Remove”. Set their captions to “Add” and “Remove” as well.

Using the Script Editor palette, set the Add button’s Click event to the following JavaScript code:

Table1._Item.addInstance(0);

This script will add a new instance of the Item row to the table. Now set the Remove button’s Click event to the following JavaScript code:

if (Table1._Item.count > 1)
    Table1._Item.removeInstance(Table1._Item.count - 1);

This script will first make sure that there are at least 2 rows (since the minimum row count is 1) and if so, will remove the last row that was added to the table. Note the use of the underscore prefix to access the Item row’s Instance Manager.

Previewing the form at this point will now allow you to add/remove rows and you’ll see that the totals are all being calculated automatically as you choose items and set quantities:

Sample Form

Here is the sample form for the tutorial. It’s the solution so try not to look at it until you’ve run through the tutorial on your own…

Download Sample [pdf]

Sample Minimum Requirements: Designer 7.1/Acrobat 7.0.5

Sample Form with Page Totals

Reader Sandeep Goli asked an interesting question: How would one show a page total?

This can be done by adding first allowing the table’s content to break across pages by checking the “Object palette > Table tab > ‘Allow Page Breaks within Content’ property”. The next step is to add another footer row to the table, located prior to the existing “FooterRow” row object (select the FooterRow row, duplicate it, rename it to “PageFooter”, rename the field inside to “PageTotal” and drag it up above the FooterRow object in the Hierarchy palette), and set it up to be included on subsequent pages as well as a the final page (rather than just the final page) using the “Object palette > Pagination tab > ‘Include Footer Row in Subsequent Pages’ and ‘Include Footer Row in Final Page’ properties”. This will cause the footer row to appear at the bottom of all pages, including the last page, as the table breaks across pages.

The final step in making this work is to set script in the new footer row’s Layout:Ready event. (If you duplicated the FooterRow, make sure you remove its Calculate script.) In this event, you can use APIs from the Layout Model which will let you determine the set of table “Item” rows that are on a given page — that being the page on which the PageTotal field was rendered:

xfa.layout.page(object)

will return the 1-based page number on which that object (field, subform, etc.) was rendered and

xfa.layout.pageContent(zeroBasedPageIndex, type, 0)

will return a list of all form objects of the specified type (a string, such as ‘subform’, ‘field’, ‘draw’, etc.) on the specified 0-based page index.

The following script finds all Item rows on the same page as the rendered PageTotal field, sums their Total child field values and sets that number as the PageTotal’s value:

// get a list of all subforms rendered on the same page as this field
var pageSFList = xfa.layout.pageContent(xfa.layout.page(this) - 1, "subform", false);
var pageTotal = 0;
// for each subform named "Item", sum its "Total" field value
for (var i = 0; i < pageSFList.length; i++)
{
    var sf = pageSFList.item(i);
    if (sf.name == "Item")
        pageTotal += sf.Total.rawValue;
}
// set this field's value to the sum of all Item rows on this page
this.rawValue = pageTotal;

Download Sample [pdf]
Download Sample Data [xml]

Sample Minimum Requirements: Designer 8.0/Acrobat 8.0. This is due to bug fixes with table footer placement which are available only as of Acrobat 8.0.

Sample Form with Row Remove Button

Reader Susila asked an interesting question: How do you remove a specific row using a “remove” button in the row to be removed?

This is done simply by inserting a column to the left of the ItemIndex column in the table and setting the cell’s type to a button. The button’s Click event is then set to remove the row to which it belongs.

The trick lies in writing the script in such a way that it automatically relates to (i.e. removes) the row instance to which it belongs. This is achieved by retrieving the instance index of the row to which it belongs and using that as the parameter supplied to the Item row Instance Manager‘s removeInstance([index]) method. The method expects a zero-based index and that’s what the index property gives you:

// JavaScript:
this.parent.parent._Item.removeInstance(this.parent.index);

The script above first accesses the button’s grand-parent (Table1). Then it gets the Instance Manager for the Item row and executes its removeInstance() method providing it with the index property value of its (the button’s) parent (Item row instance). By accessing parent objects, you ensure that you’re doing things with relation to the button that was clicked and, therefore, the row that contains the button.

Note that simply removing the row won’t necessarily update the ItemIndex field in other row instances that remain. If your form’s Target Version is set to Acrobat/Reader 7.0.5, you will have to explicitly tell the form to re-execute calculations. This issue was addressed in Acrobat 8.0+ so there’s no need to do this if your form targets a later version of Acrobat/Reader.

Download Sample [pdf]

Sample Minimum Requirements: Designer 7.1/Acrobat 7.0.5

Further Improvements

As I mentioned earlier, this is a simple dynamic table with a repeatable row. It demonstrates only the basics. You could enhance it further by including row shading options, validations, better formatting (font and paragraph), smarter add/remove buttons (e.g. put the remove button on the Item row in order to delete that specific row instead of always deleting from the end), put an insert button on the Item row in order to insert new items instead of always appending to the end of the list, etc.

For an advance sample, you should check-out the “Dynamic Interactive Purchase Order” sample that ships with Designer. Depending on how Designer was installed (either with Acrobat, with LiveCycle or standalone) and whether it was on Win 2k, XP or Vista, you should be able to find it in one of the following folders:

C:\Program Files\Adobe\LiveCycle ES\Workbench ES\Designer ES\{version}\EN\Samples\Forms\Purchase Order\Dynamic Interactive\Forms

C:\Program Files\Adobe\LiveCycle Designer ES\{version}\EN\Samples\Forms\Purchase Order\Dynamic Interactive\Forms

C:\Program Files\Adobe\Acrobat\Designer\{version}\EN\Samples\Forms\Purchase Order\Dynamic Interactive\Forms

(Note that in Vista, “Program Files” changes to “Program Files (x86)”.)

Updated Oct 2, 2009 — Added page totals sample.

Updated Oct 2, 2009 — Added row remove button sample.

• Scripting Reference (technical document about scripting your forms)
• Target Version Reference (if you want to know what features are compatible with specific PDF versions or if you’re using Designer ES 8.2 to build a form for users on Acrobat/Reader 7.x and you want to make sure they can use your form)
• Scripting Errors Reference (solutions to common scripting errors)
• FormCalc Reference (for those of you who like to use FormCalc instead of JavaScript, this reference includes previously-omitted information about various language constructs such as “while”, “for” and “for each” loops)

Under the Develop Tab, you’ll find documentation on the following topics as they pertain to Designer:

• Designer Help (LiveDocs)
• Form Guides (“getting started” guide)
• Scripting Basics
• Scripting Reference
• Target Version Reference (to know what features of XFA and Designer are supported in specific versions of Acrobat — this is what the new Target Validation feature in Designer is intended to help you manage)
• Transformation Reference (to know what’s supported if you’re targeting HTML)
• FormCalc Reference

What’s more is that the new Enterprise Suite launch means that there’s also new version of Designer: LiveCycle Designer ES (version 8.1). I believe this will be an upgrade to Designer 8.0 which currently ships with Acrobat Pro 8.0. Most notable in this new version are

• the new Guide Builder tool which will help you quickly re-purpose your PDF form as a Flash-based Form Guide;
• a new feature called Form Fragments which will enable you to re-use sections of your forms and scripts in other forms while only needing to make changes in one place;
• a Syntax Checker in the Script Editor to check for errors in your scripts (this will definitely help with debugging!); and
• the Target Validation feature which will help you determine which XFA features you may use when targeting a specific version of Reader/Acrobat (e.g. if you specify Reader/Acrobat 7.0 as your target version and you insert a table into your form, you’ll get a warning telling you that tables aren’t supported in Reader/Acrobat 7.0 — they’re only supported as of Reader/Acrobat 7.0.5).

Foreach Expression

The Foreach expression is quite similar to the For expression but is meant to be used to achieve a slightly different kind of iteration that may be better suited to your needs rather than just increasing/decreasing the value of a counter (as for a regular For expression). The difference is that the Foreach expression assigns a different value taken from an argument list (list of objects/values) to a variable for each iteration of the loop (and there’s one iteration for each argument in the list).

FormCalc Syntax

foreach Variable in (ArgumentList) do
  ExpressionList
endfor

In this syntax, there’s an ArgumentList. This is simply a comma-separated list of objects/values to assign to the Variable on each iteration.

Based on the syntax, you can do things like set a total field’s value to the sum of subTotal, shipping and taxes fields:

foreach val (subTotal, shipping, taxes) do
  total = total + val
endfor

In this example, each time the expression loops, the variable val assumes the “identity” of a different object in the argument list: First, the subTotal field, then the shipping field and, finally, the taxes field.

JavaScript Syntax

For comparison, here is the equivalent JavaScript examples (note the semicolons and curly braces):

var arr = {0: subTotal, 1: shipping, 2: taxes};

for (key in arr)
{
  total.rawValue += arr[key].rawValue;
}

(In this case, the curly braces are optional but I think this is better style.) It’s certainly more cumbersome in JavaScript using the For…In expression (which is the closest equivalent to FormCalc’s Foreach expression I could find) because it’s only meant for iterating through an object’s properties or an array’s keys (which is what my example is doing).

In this post, I’ll explain the syntax of the If and For expressions in FormCalc. Those of you familiar with Visual Basic or VBScript will likely find this more familiar than the equivalent JavaScript syntax (while I’ll include for comparison however this isn’t a post on JavaScript syntax). In future posts, I’ll add to this collection by discussing the syntax for While and ForEach loops.

Conventions

Before we get started, I should explain a few things about the various syntax blocks you’ll find further down in this post (note that this is simplified for the purposes of this article):

• SimpleExpression: A simple expression like a comparison “i >= 0” that evaluates to true or false or a single entity like “MyVar” (a defined variable) or “5” (a number), for example.
• ExpressionList: A set of 1 or more expressions, each on a separate line.
• Square Brackets: A series of keywords (like “if”, “then”, “for”, “while”, etc.), SimpleExpressions and ExpressionLists grouped within square brackets denote an optional part of the syntax.
• Asterisk Character: Sometimes a closing square bracket is followed by an asterisk (*). This indicates that the optional syntax may be used 0 or more times.
• Question Mark Character: Sometimes a closing square bracket is followed by a question mark (?). This indicates that the optional syntax must be used 1 or more times.

Variables

I assume you’re probably familiar with declaring variables in scripts but just in case, in FormCalc, you declare variables like this:

var MyVar

and you can even declare it and assign it a value in the same step:

var MyVar = 5

If Expression

Let’s look at one of the most essential of all expressions:

FormCalc Syntax

if ( SimpleExpression ) then
    ExpressionList
[ elseif ( SimpleExpression ) then
    ExpressionList]*
[ else
    ExpressionList]?
endif

Based on the syntax, you can do things like (assuming you’ve declared a variable named “i”):

if (i >= 10) then
  i = i + 10
endif

or

if (i >= 10) then
  i = i + 10
elseif (i >= 5) then
  i = i + 5
  i = i * 2
else
  i = i + 1
endif

Hopefully this illustrates the differences in the syntax indicated by the asterisk and question mark characters.

JavaScript Syntax

For comparison, let’s look at the equivalent JavaScript syntax for the two examples above (note the semicolons and curly braces):

if (i >= 10)
  i = i + 10;

or

if (i >= 10)
  i = i + 10;
else if (i >= 5)
{
  i = i + 5;
  i = i * 2;
}
else
  i = i + 1;

For Expression

Often times, in your scripts, you need to execute some statements a certain number of times or iterate through a collection. In those cases (and many others), a For loop may be useful.

FormCalc Syntax

for Variable = StartExpression
        (upto | downto) EndExpression
            [step StepExpression]?
        do
    ExpressionList
endfor

In this syntax, there’s a StartExpression, and EndEExpression and a StepExpression. These are all similar to SimpleExpressions as described earlier. One thing to note about For loops in FormCalc is that “upto” loop will iterate as long as Variable is less-than-or-equal-to (<=) EndExpression whereas a “downto” loop will keep iterating as long as Variable is greater-than-or-equal-to (>=) EndExpression. Also, the variable Variable is implicitely declared in the For expression.

Based on the syntax, you can do things like add the numbers 1 to 10, inclusively, to a list:

for i = 1 upto 10 do
  MyList.addItem(i)
endfor

and then

var nCount = MyList.#items[0].nodes.length

if (nCount >= 2) then
  for nItem = nCount downto 1 step 2 do
    xfa.host.messageBox( MyList.#items[0].nodes.item(nItem - 1) )
  endfor
endif

which would display the value of each even-numbered list item in reverse sequence using a message box as long as there’s at least one even-numbered list item to display.

JavaScript Syntax

For comparison, here are the equivalent JavaScript examples (note the semicolons and curly braces again):

for (var i = 1; i <= 10; i++)
{
  MyList.addItem(i);
}

(in this case, the curly braces are optional but I think this is better style) and then

var nCount = MyList.resolveNode("#items[0]").nodes.length;

if (nCount >= 2)
{
  for (var nItem = nCount; nItem >= 1; nItem - 2)
  {
    xfa.host.messageBox(
      MyList.resolveNode("#items[0]").nodes.item(nItem - 1) );
  }
}