The service is quite simple: It displays what you submit to it. Since Designer’s “PDF Preview” tab is actually an instance of Internet Explorer hosting a PDF version of the form you’re previewing (a temporary PDF if your form is saved as an XDP or is new), the results are conveniently displayed within the tab itself after clicking on the submit button.

To use the service, simply use either an http submit button (or a regular button with its “Object palette > Field tab > Control Type property” set to “Submit”) and set its URL to:

http://forms.stefcameron.com/services/http-submit-test/

The idea is to use this service as a means to test/debug your forms before spending time writing the actual server code that will receive the data. You can also use it to ensure that you are submitting the correct data to a third-party service (for which you don’t control the server-side code).

Choosing a Submit Format

HTTP submissions can be made in various formats: XML, XDP, URL-encoded (HTTP post), and PDF. If you are using Reader instead of Acrobat, you will not be able to submit in PDF format unless you have enabled this ability using LC Reader Extensions.

The most important difference amongst the formats is that repeating data sets cannot be submitted using URL-encoding (HTTP post). This is due to the way the data is submitted: In HTTP post directives, data is submitted in “name=value” pairs. Since repeating data sets involve hierarchy and duplicate data node names, only the last instance of the repeating set will be submitted.

To submit repeating data sets, you must choose either XML, XDP or PDF as the data format.

Sample Form

The following sample form demonstrates the use of the HTTP Submit Test service.

Download Sample [pdf]

The form has a typical address block as well as a table to demonstrate both static and repeating data sets. Use the submit buttons to try submitting in different formats (XML, XDP, PDF, URL-encoded). Notice how only the last table row is submitted when using the URL-encoded (“post”) submit button.

Minimum Sample Requirements: I created this sample using Designer 9.0 and Acrobat 9.2 however it should work fine back to Acrobat 7.0.5.

Last February, I announced the release of a new Designer book titled, “PDF Forms Using Acrobat and LiveCycle Designer Bible”.

Over the past few months, I had the opportunity to review it and I thought I would share my comments, with respect to the second-half of the book, which deals with LiveCycle Designer ES and XFA forms, to help you decide if it would be a good book for you*. (The first-half deals with authoring PDF forms, a.k.a. AcroForms, in Acrobat and is beyond the scope of my blog.)

Creating Data Nodes

In a similar article, John Brinkman showed how to create form variable nodes at runtime however what’s not obvious about data nodes is that you don’t create them using

a class name of your choice.

For example, say you wanted to create the following data node structure:

<custom>
    <message>Hello World!</message>
</custom>

Given the following syntax for the createNode() function (see page 367 in the LC Designer 8.2 Scripting Reference):

{model}.createNode(className [, name, namespace]);

you might try the following, using “custom” as the class name for the first group/container node <custom>:

var n = createNode("custom");

Doing the above would generate an error stating that “custom” is an invalid node type.

The trick here is that only specific XFA class names are allowed, such as “text”, “decimal”, “integer”, etc., as well as two special types for data nodes: “dataGroup” and “dataValue”. When you need a data node that will contain other data nodes, you use the “dataGroup” class. When you need a data node to which you will assign a value, you use the “dataValue” node.

The JavaScript code to create the above XML structure then becomes:

// <custom> data group to contain <message>
var c = xfa.datasets.createNode("dataGroup", "custom");
// <message> data value for "Hello World!"
var m = xfa.datasets.createNode("dataValue", "message");
// set value of data value node
m.value = "Hello World!";
// add <message> into <custom> data group node
c.nodes.append(m);
// print result to JavaScript Console (Ctrl + J in Acrobat)
console.println(c.saveXML("pretty"));

// output from above:

<custom>
    <message>Hello World!</message>
</custom>

Note that the createNode() function must be called on an object of type “model” and since we’re creating nodes in the Data DOM, we use the xfa.datasets object since it is a model object.

At this point, the <custom> node (and the nodes/values it contains) is not part of the Data DOM. To add it to the Data DOM so that it gets submitted with the rest of the form’s data, you would have to append it to a node inside the root subform (the top-most subform in the Hierarchy palette). For example, if your root subform’s name was “form1″, you would do the following to add the <custom> node to the form’s data:

xfa.datasets.data.form1.nodes.append(c);

This can be very useful. In fact, this technique is used in Correspondence Management letter template scripts to flag a selection list’s default selection as having been processed. Since the data merged into the list to print the letter based on the template may not match the default selection in the list, the scripts generate a special node directly in the Data DOM to indicate whether the list’s data value should be processed instead of its default selection (i.e. no need for a hidden checkbox field for each list, keeping the form/PDF file size down).

The “Custom Node Example” section in my sample form demonstrates the above technique.

Loading Data Nodes

Another use for creating data nodes is they give you the ability to load existing XML in order to parse it without having to modify the Data DOM. If you create a new, orphaned (un-parented) data group node, you can use its loadXML() function to load an XML string into it, thereby giving you a handy XML node structure for parsing.

One example use of this would be in a form that retrieves various settings from a web service data connection where the structure of the returned data is determined by the input parameters (i.e. you have a single data connection which you can use to retrieve various data). You can return the XML data as a string and load it into a new data group node in order to parse-out the value you’re looking for without ever touching the Data DOM.

Another example would be an extension of my URL Request article. In this case, you could pass some XML data into your form via the URL request if your PDF form was available on a website. Warning: This is a not a secure method to pass data to your form.

Clicking the following link will load some movie data into the “Movies loadXML() Example” section of my sample form:

CreateLoadDataNodes.pdf?data=%3Cmovies%3E%3Cmovie%3E%3Ctitle%3ENacho%20Libre%3C%2Ftitle%3E%3Ccost%3E21.00%3C%2Fcost%3E%3CactorName%3EJack%20Black%3C%2FactorName%3E%3CcatName%3EComedy%3C%2FcatName%3E%3C%2Fmovie%3E%3Cmovie%3E%3Ctitle%3EMI%3AI%3C%2Ftitle%3E%3Ccost%3E20.00%3C%2Fcost%3E%3CactorName%3ETom%20Cruise%3C%2FactorName%3E%3CcatName%3EAction%3C%2FcatName%3E%3C%2Fmovie%3E%3C%2Fmovies%3E

Finally, my sample form also has a handy “URI Encoding Tool” section which you can use to encode various strings to include in a website address (as above).

Samples

Download Sample [pdf]

Minimum Sample Requirements: I created this sample using Designer 8.2 and Acrobat 9 however it should work fine back to Acrobat 7.0.5.

There is also a great example on creating data nodes on page 438 of the LiveCycle Designer ES Scripting Reference for Designer 8.2 — an excellent XFA form scripting reference.

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.

Angie Okamoto, Director of Enterprise Development at Easel Solutions, and Ted Padova, the "PDF Guru" and author of the "Adobe Acrobat PDF Bible" series, have published a new book titled, "PDF Forms Using Acrobat and LiveCycle Designer Bible". I’m sure it’ll be a great reference!

Their book is available now on Amazon.com and Wiley.com.

Form Guide Layout

The goal is to design a form guide which will provide two panels: one for user options and the other for results.

The first panel will expose the 4 fields inside the GuideObjects subform (which are only meant to be exposed in the form guide — hence why the GuideObjects subform has the Initialize script to hide it if the host isn’t “Flash”). The user will have the option to choose an actor and/or category for further filtering and will then click on the GetMovies button to execute the request on the Movie Service. When the requested XML is returned to the form guide, the GetMovies result handler will convert the XML into instances of MovieRow inside the Listing table.

The second panel will use a repeater layout to expose the Listing table’s contents within the form guide however this panel will only be accessible if the movie query returned 1 or more results.

Once the results are in, the user will then be able to switch (“flip”) to the PDF view which will show the Listing table in the form, from which the user could then print or archive the results.

Designing the Form Guide

Open your tutorial form in Designer and launch GuideBuilder (GB) by choosing the “Tools > Create or Edit Form Guide” command. Switch to the “Customize Appearance” tab and choose “Save Styles”, saving them to a SWC file of your choice (usually in the same folder). It’s not mandatory to do this but if you don’t specify a file name here, GB will auto-generate a style SWC (which contains information about any style customizations you might apply) named according to the wrapper you choose (e.g. “ga.wrappers.CobaltStandard.swc” for the “Cobalt Standard” wrapper — not the most meaningful name for our solution).

Back to the “Edit Guide” tab, set the guide’s title to “MAX 2008 Movie Catalog Service” (double-click on the “New Guide” label to set it), the section’s title to “Movie Catalog” and the panel’s title to “Options”. Set the panel’s layout to “Two Column”.

Options Panel

Click on the “Add or Bind Fields” button and drag the entire GuideObjects subform into the panel. You’ll see, in the “Panel Preview” pane on the lower-right, that objects in the panel are laid-out in two columns from left to right, top to bottom, according to the top-down order in which they appear in the panel. What we want is for the MatchCount field to show-up below the GetMovies button. To do this, insert a “Next Area” object (from the “Utility Objects” group at the top of the form tree) after all the objects in the panel and then drag the MatchCount field below it. The “Next Area” object causes a break in the layout algorithm, thereby forcing the following object onto the next row in the two-column layout.

To make the panel layout more pleasing, switch back to the “Set Properties” view and set the captions of the ActorList, CategoryList and MatchCount fields to be at the top and the width of both listboxes to be “100%”. Finally, override the MatchCount field’s caption (double-click on it) and set it to “Number of movies matching criteria:” (accept the warning about the caption binding being removed).

One important form guide feature is the ability to display fields in different ways. In other words, if your field is a listbox, for example, you aren’t limited to displaying it as a traditional listbox. You could choose to display it as a series of checkboxes or radio buttons, for example, or you could create your own custom control using FlexBuilder.

GB provides a checkbox control type which will suit our needs perfectly because while our listboxes are single-selection only, using checkboxes will allow the user to remove a previous selection which is important if they previously filtered by actor, for instance, and now they want to remove that filter.

For the ActorList and CategoryList fields, set their “Display field as a” property to “Check Boxes”.

At this point, the settings for the ActorList (and CategoryList) fields should look like this:

and your form guide hierarchy should look like this:

Movie Listings Panel

The second panel is a lot simpler since it just shows the Listing table’s contents and it doesn’t require as much settings.

Insert a second panel into the “Movie Catalog” section, give it a title of “Movie Listings” and set its layout to be “Repeater Grid”.

The objects named “Repeater First Column” and “Repeater Second Column” don’t apply to this type of repeater panel however they do matter in other repeater layouts and are there for consistency (should you decide to change the repeater panel type). The “Trailer” object signifies that all objects placed after it, on this panel, will go below the grid as opposed to being part of the grid (this would be good for footer objects, if we had any).

Drag the MovieRow subform (table row) into the panel between the “Repeater First Column” and “Repeater Second Column” objects (drop the subform directly in between the two objects — if you miss, just drag each object back to where it’s supposed to go).

For each field you dragged-in, set its caption as follows: “Title”, “Actor”, “Category” and “Cost”. (You should see these changes in real-time in the Panel Preview pane.) Select the Title item and set its width to 150 (which means pixels in the form guide) to ensure the titles are completely visible and then set its “Allow field to repeat” property to indicate that it, and all associated fields, should be repeated within the grid layout. The items in the panel will then get a yellow outline indicating that they are repeating items.

Now that we’ve set this up, I’ll follow-up on a comment I made in part 1 when we designed the Listing table and set the MovieRow to have 1 initial instance: There’s a bug in the Repeater Grid panel layout where the data entered into the fields in the grid will not be rendered (it’s there, you just can’t see it) unless there’s some data in the grid when the form guide is initialized. To work around the bug, we simply include an initial instance of the MovieRow and then the GetMovies result handler code simply removes the instance prior to populating the table with movie results (whether there are any or not).

The last step in setting-up this panel is to apply a Display Rule to indicate when the panel should be visible (accessible to the user) in the form guide. What we want to do is set the panel to be visible only if the MatchCount field’s value is greater than zero, meaning there’s at least one movie result from the query. To do this, you simply toggle the “Specify panel display rules” pane in the panel’s properties, choose “Use Display Rules”, add a rule, set MatchCount as the field, “greater than” as the condition and “0″ as the value.

FormBridge XFO Fix

Now that the form guide has been designed, the
re’s just one more thing we need to do: Apply a small fix to the FormBridge code that brokers the communication between the form guide and the PDF at runtime. The FormBridge code is normally automatically injected into the PDF when it’s generated by the GB Preview functionality or by LiveCycle when the form is rendered as a form guide with the PDF however we need to use our own “fixed” version of the FormBridge code. Otherwise, when we flip to the PDF, there will be no data in the table.

To do this, save your changes to the form guide and exit GB. Find the “Custom” pane in Designer’s Object Library and drag the “Form Bridge” object onto your form below the GuideObjects subform (where there are no objects on the page).

It shows-up as a hairline selection on the page and in the hierarchy looks like this:

Select the “ContainerFoundation_JS” script object and open the Script Editor to edit the script. Find the two instances of “saveXML()” (lines 316 and 631) using the Find dialog (Ctrl + F) and change them from

saveXML().replace(/\n/g, "");

to

saveXML();

Do not remove/change any of the code that comes before it on the same line. This fix ensures that the format of the data going across the line is correct.

With the FormBridge object in our form, GB Preview and LiveCycle will not inject their version into the PDF. The only draw-back from this approach is that if the FormBridge code changes, you’ll have to manually update it in your form as opposed to automatically getting the new version when you preview with GB or render your form with LiveCycle.

This bug should be fixed in a future release and so the workaround in the FormBridge code will eventually no longer be needed.

Flash Log and Debug Players (Optional)

You may have noticed some “trace()” statements in the code we set on the ActorList, CategoryList and GetMovies objects in part 2. This is a handy way to get a read on what’s going on (i.e. debugging) inside the form guide at runtime if you aren’t using FlexBuilder to debug it (which we’re trying to avoid in this tutorial). It’s a lot like using “console.println()” to output information to Acrobat’s JavaScript Console.

If you want to see trace statement outputs (it’s not necessary but it could be handy), you need to look at your flashlog.txt file which is auto-generated by the debug version of the Flash Player. These are normally called “debug players” or “content debuggers” and are downloadable here. To ensure that you have a debug player, you can hit this page which will tell you what version and type of Flash Player your browser is using.

Once you’ve installed a debug player, you’ll need to configure your system to enable the flashlog.txt file which will be located here, once enabled: C:\Documents and Settings\user_name\Application Data\Macromedia\Flash Player\Logs\flashlog.txt (XP) or C:\Users\user_name\AppData\Roaming\Macromedia\Flash Player\Logs\flashlog.txt (Vista).

The debugger configuration page details where to place the mm.cfg file and what to put in it in order to enable output to the flashlog.txt file. For example, if you’re running XP, you would create a new mm.cfg file in your “C:\Documents and Settings\user_name\” folder and you would put the following lines inside to enable error reporting and trace logging (i.e. output to the flashlog.txt file):

TraceOutputFileEnable=1
ErrorReportingEnable=1

Running the Solution

Now that the form guide is designed, we’re ready to run our solution: Launch GB again and this time, choose the Preview tab, select “Include PDF Preview” (to ensure that a PDF is included, otherwise you won’t be able to flip to it to see the results) and click on the Preview button.

The resulting form guide should look like this (with the pre-loaded actor and category lists):

When you click on the “Get Movies” button, the button will become temporarily disabled and then, assuming your query returned movies, the count should be updated and the “Movie Listing” panel should appear in the left toggle bar:

Now click on the “Movie Listing” panel to see the results in the form guide:

Finally, click on the “Show PDF” icon in the toolbar at the top-right to see the results (i.e. imported Movie Service data) in the PDF:

Cool? I think so! And the cherry on top is that this even works with the free Reader! Users don’t need Acrobat in order for the data to go back and forth between the form guide and the PDF.

Solution to Part 3

Try not to peek at this before you attempt to build the form guide on your own…

Download Part 3 [zip]

Minimum Requirements: Designer 8.2.1 SP1, GuideBuilder 8.2.1 SP1, Reader 9.0.

Note: If you decide to deploy this sample to LiveCycle (e.g. using FormsIVS), you’ll also need to deploy the styles SWC you created earlier. The form guide will not render without it.

Flex Code in XFA Forms

The key to today’s tutorial is understanding when and where the script you write in an XFA form (JavaScript or FormCalc) is compiled or interpreted.

For starters, form guides don’t support the FormCalc language so that just isn’t an option.

JavaScript, on the other hand, has the nice property of looking a lot like ActionScript. In fact, the two languages have enough similarities that with very little modification, any JavaScript you write in an XFA form can be converted into ActionScript which runs in a Flex form guide (in the Flash Player).

Normally, when you write JavaScript code in your forms and you run the form in Acrobat, the script isn’t compiled when the XFA form is converted into the PDF file format and it’s only interpreted when the interpreter attempts to execute it (i.e. if there’s a syntax error somewhere in your script and you never run that code, you’ll never know about the error). When you generate a form guide based on your form, however, your JavaScript is actually compiled by the Flex compiler that generates the SWC (Flash Library) which defines your form guide.

Warning: Script object code seems to be loaded and interpreted by Acrobat in one shot, instead of on a per-access basis as in form object event scripts, and any syntax errors anywhere in the script object will cause all of the script in the script object to basically be ignored. If you have functions defined in a script object and you know you’re calling a function properly but you keep getting a “function is not defined” error, use the Script Editor’s Syntax Checker tool — you’ll probably find a syntax error somewhere. After you fix it, you should be able to access your script object functions.

It also appears that Acrobat/Reader 9.0 may now be attempting to parse (but not execute) all scripts on form load which may produce syntax errors in the JavaScript Console due to the differences between JavaScript and ActionScript syntax however in my experience so far, I haven’t hit a situation where my JavaScript stops executing because of this. Nonetheless, if you’re seeing strange behaviour, it might be a good idea to check the console to make sure things are running smoothly.

What you might not have realized is that if you know that a particular portion of script will only be executed within the context of a form guide, you can actually write Flex code in your XFA form! When you generate the form guide (either by previewing using GuideBuilder or by rendering the form as a form guide via LiveCycle Forms), your Flex code will be compiled as any other Flex code would be and it’ll be executed in the same way.

That opens-up a world of possibilities and the one we’re going to explore in this tutorial is the use of the mx.rpc.http.HTTPService class to fetch data from the Movie Service and insert the results into the Listing table within the form guide, thereby causing the data to be inserted into the Listing table within the PDF form when the user switches from the form guide to the PDF.

XFA Host Name = Flash

You might recall, in yesterday’s tutorial, that I talked about the xfa.host.name property returning “Flash” when your XFA code is executing within the context of a form guide (it returns “Acrobat” when its executed within the PDF because the form’s “host” is “Acrobat”).

This is the indicator we’ll use to “protect” the Flex code we’re going to write to make sure that it’s not executed within the PDF:

if (xfa.host.name == "Flash")
{
    // do some cool stuff in Flex/ActionScript
}

Note that the XFA model in a form guide works just the same as it does within the PDF with the exception that the form guide environment only supports a subset of XFA functionality (less than in the PDF but more than in HTML).

Our Own HTTPService

Since there will 3 requests made to the Movie Service, one for the actor list, one for the category list and another for the movie listings resulting from the chosen actor and/or category (if any), the first step to take is to create some reusable code within our form that makes use of the HTTPService object.

Open the form you designed yesterday and add a new script object by right-clicking on the root subform (“movieList”) and choosing the “Insert Script Object” command.

Name your script object “FlexHttpService” and paste the code from this text file into the script object.

You’ll notice that there are some statements in this script that aren’t regular JavaScript (namely the “import” statements to get access to the HTTPService and its result and fault event classes as well as the typing of variables like “service:HTTPService”). That’s because it’s ActionScript!

I’m assuming you know enough about Flex to be able to understand what’s going on but the gist of it is that the script object’s send() function takes a URL (to the Movie Service) and two functions, the first called when the request is successful and the second called if the request fails. If the request is successful, the result handler function is called with an XML variable as its parameter. This XML variable contains the movie listing we want to insert into the Listing table.

The FlexHttpService.send() function will be the reusable piece of code that we’ll use in the two listboxes and the button, each providing its own URL and result handlers.

It’s important to note that the actual result and fault handlers given to the HTTPService object instance are inline functions. This is essential since the call to HTTPService.send() is asynchronous. When the result comes back (later), context will be lost and the service won’t be able to find a function you defined in the FlexHttpService script object. Therefore, the handlers must be inline.

ActorList Initialize Script

With the FlexHttpService defined, it’s easier to write the rest of the code to fetch the list of actors.

We want the list of actors to be retrieved when the form guide initializes so we’ll put this script in the Initialize event of the ActorList field. In the result handler, we’ll simply iterate through the items in the XML object returned and, for each actor, add his/her name and ID as an item into the ActorList field in the form guide.

Note that accessing the ActorList field in the form guide within the result handler, which is out-of-context at this point, is done by using the full SOM expression to the field, starting with xfa.form (accessing the Form DOM), followed by the root subform name (“movieList”), followed by the path to the ActorList field.

Edit the ActorList field’s Initialize event and paste the code from this text file into it.

Basically, we first clear any existing list items and call the Movie Service with the appropriate URL. In the result handler, we add items into the ActorList and then enable the list so that the user can make a selection (we don’t want the list accessible until the items have been loaded).

CategoryList Initialize Script

The CategoryList field is much the same as the ActorList field however it’ll fetch the list of categories.

Edit the CategoryList field’s Initialize event and paste the code from this text file into it.

GetMovies Click Script

Finally, we just need to set the Click event script on the GetMovies button that will fetch the movies requested by the user (optionally filtering on actor and/or category).

This script is essentially the same as the first two however it’s a little more complex since the Listing table must be retrieved and then new instances of the MovieRow must be added and their fields (Title, Actor, Category and Cost) populated with data from each movie returned from the service. Additionally, the button is disabled once its clicked and only re-enabled when the result or fault handler is called to prevent the user from clicking multiple times while a request is pending (since HTTPService.send() is asynchronous) and the MatchCount field is populated with the number of rows added to the Listing table (this will be important when we design the form guide in part 3).

Edit the GetMovies button’s Click event and paste the code from this text file into it.

Solution to Part 2

Try not to peek at this before you attempt to build the form on your own…

Download Part 2 [zip]

Minimum Requirements: The form should work back to Designer 8.0 however it was designed with Designer 8.2.1 SP1.

Updated: November 22, 2008

Throughout the tutorial, I will assume that you’ve used Designer already and you know about things like flowed vs positioned subforms. I will also assume that you’re familiar with Guide Builder’s interface for designing Form Guides.

Software Requirements

Before we get started, make sure you’re using Designer 8.2.1 SP1 and Guide Builder 8.2.1 SP1. You can download an evaluation version of Designer and Guide Builder when you download the Acrobat 9.0 Pro trial. If you haven’t installed SP1 yet, you can download it from here (note that you only need to install the Designer SP1 update — you don’t need Workbench or even LiveCycle ES to run through this tutorial).

If you already have Designer but you don’t have Acrobat, you can use Reader 9.0 to go through the tutorial.

Schema Data Connection

The first step is to connect the form to a schema which we can obtain from the Movie Service:

<movieList>
    <movie>
        <movieId/>
        <title/>
        <cost/>
        <actorName/>
        <catName/>
    </movie>
    <movie>
        <movieId/>
        <title/>
        <cost/>
        <actorName/>
        <catName/>
    </movie>
</movieList>

Save this structure to an XML file named “movieCatalog-schema.xml” somewhere where you can reference it later from your form in Designer. (It’s important that you save it as-is with the duplicated <movie> element since this will indicate to the Data Connection Wizard that the <movie> element is repeatable.)

Create a new blank form in Designer and then create a new data connection using the Data Connection Wizard available from the Data View palette’s menu button. On the first page, set the name to “MovieCatalogDC” and choose “Sample XML File”:

On the next page, choose the “movieCatalog-schema.xml” file you saved earlier and click “Finish”. You should now have a schema data connection in your form (note that Designer inferred the possible structure of the schema based on the sample XML file we provided for the data connection):

This data connection will help us set the correct bindings later.

Page Header

Next we’ll create a simple header for the form by adding a text object to the Master Page. Switch to the Master Pages tab and drag a text object onto it. Place it at the top-left and set the text to “MAX 2008 Movie Catalog”.

To make sure that what we’ll put on the body pages (in the Design View) doesn’t show-up over-top our header, make sure that the content area starts below the header text object:

Movie Listing Table

Back on the Design View, we now need to create a table which we’ll use to display the listings from the catalog. This is where that schema data connection will come-in handy as we’ll see a little later.

Our table will display 4 columns: title, actor name, category name and cost. Drag a table object onto the top-left corner of the page and give it 1 header row, 1 body row and 4 columns:

We want the table to take-up the entire width of the page but we also want the first column, title, to be wider than the other 3 since the title is usually longer than names or a dollar amount. Start by making the last 3 columns a little wider by dragging the column separator between the 2nd and 3rd and 3rd and 4th columns to the right, leaving some room to make the first column wider. Then drag the column separator between the 1st and 2nd column to the right until it won’t move anymore, which indicates that it’s the widest the first column can be made while keeping the table constrained to the page’s width.

Now double-click in each header cell and rename them to “Title”, “Actor”, “Category” and “Cost” from left to right.

(Here I’ve also set a linear-to-bottom background gradient color on the header row.)

Next, we need to set some fields into the table row where the movie data will go since they’re only text objects by default. The first 3 columns need to be text fields and the last one should be a numeric field since it’ll contain a dollar amount.

Using the Hierarchy palette, select the “Cell1″, “Cell2″ and “Cell3″ objects in the “Row1″ table row and change their object type (using the Object palette) to “Text Field”. While they’re still selected, set their Value Type to “Read Only”.

Now select the last cell in “Row1″, “Cell4″, and change its object type to “Numeric Field”. While it’s still selected, set its Value Type to “Read Only”, its Data Format to “Float” and click on the “Patterns…” button on the Object palette’s Field tab. In there, set the Display pattern to “numeric.currency{}” and set the Data pattern to “numeric.decimal{}”:

This will let the field accept a decimal number as its data and will cause it to be displayed with a currency symbol (e.g. “25.50″ is displayed as “$25.50″).

Finally, rename “Table1″ to “Listing” and “Row1″ to “MovieRow”. Inside “MovieRow”, rename “Cell1″ to “Title”, “Cell2″ to “Actor”, “Cell3″ to “Category” and “Cell4″ to “Cost”.

Schema Data Bindings

The next thing on the list is setting the data bindings into the schema data connection we created earlier. This will ensure that when data is merged into the form, after being retrieved from the Movie Service, that instances of the MovieRow table row are created accordingly and the Title, Actor, Category and Cost fields they contain populated with the right data for a particular movie.

Select the MovieRow table row object and set its binding by choosing “MovieCatalogDC > movie” from the binding popup button next to the Default Binding property. This will set the binding to “$.movie[*]“:

(The button next to the field that contains “$.movie[*]” is the binding popup button.)

This binding, with the “[*]” syntax, indicates that the MovieRow object will bind to all occurrences of the <movie> data group nodes in the data that gets merged into the form.

Finally, make the MovieRow repeatable with no min, no max but 1 initial instance:

The initial instance is essential in getting around a bug with the Form Guide Repeater Data Grid panel layout which we’ll be using in part 3 of this tutorial.

The last bindings we need to set are on the Title, Actor, Category and Cost fields that make-up the MovieRow. Set them as follows:

• Title: “$.title”
• Actor: “$.actorName”
• Category: “$.catName”
• Cost: “$.cost”

You can set these bindings manually or you can use the binding popup button to select the appropriate node from the MovieCatalogDC data connection. If you use the binding popup button, you’ll likely get the Binding Properties dialog, in which case you should choose to not to update any related properties as follows:

Under certain circumstances, the schema may contain more information about a particular element which could be automatically applied to the field such as name, caption and default value. Since we’ve already setup the fields ourselves (and since our sample XML schema didn’t have much information to start with), we don’t need this functionality.

Form Guide Only Objects

The final step in the form design is to include 4 objects which we’ll use only in the form guide that we’ll create in part 3 of this tutorial. We’ll need a listbox to hold the actor names, one to hold the category names, we’ll need a numeric field to hold the movie count and we’ll need a button that the user will click to fetch the movies that match the actor and/or category they will have selected in the lists (if any).

This is simpler to setup than it sounds. All we need to do is drag a new subform into the page (below the Listing table) and place two listboxes, one numeric field and one button inside. Rename the subform to “GuideObjects”.

Rename one listbox to “ActorList” and the other to “CategoryList”. Rename the numeric field to “MatchCount” and the button to “GetMovies”.

Set the ActorList field’s caption to “Choose an Actor (optional):” and the CategoryList field’s caption to “Choose a Category (optional):”. Set both field’s Value Type to “Read Only” since we don’t want the user to be able to interact with the listboxes until actor and category data are loaded into them (in the Form Guide, which we’ll see later in part 3).

Set the MatchCount field’s caption to “Number of matches:” and set its Value Type to “Read Only” as well since we’ll just be reporting the total number of movies that matched the criteria (actor and/or category or neither) and we won’t want the user to edit the result.

The bindings on both listboxes and the numeric field will be “None” by default which is fine. There’s no node in the schema to bind them to and we don’t need to bind them anyway.

Set the GetMovies button’s caption to “Get Movies”.

Finally, to make sure all the guide-only objects are hidden in the form, set the Initialize script of the GuideObjects subform to hide itself if the context isn’t the Form Guide. You can determine what the context is by checking the value of the xfa.host.name property. If it’s “Flash”, then you know the script is executing within the context of the Form Guide, not Acrobat. This will be very important in part 2 when we write the ActionScript code necessary to fetch the data from the Movie Service:

if (xfa.host.name != "Flash")
    this.presence = "hidden";

This is what the form should look like now:

(Note that the exact placement of the objects within the GuideObjects subform doesn’t matter since they’ll be positioned correctly in the Form Guide and won’t be displayed on the form itself.)

Getting Rid of the Page Subform

To ensure that our Listing table is free to expand and roll-out onto additional pages if there are a lot of movies returned in the listing, we need to move the Listing table and the GuideObjects subform out of the page subform and into the root subform (“movieList” at the top of the Hierarchy tree). We could just make the unnamed page subform flowed but that would introduce an extra level of subform hierarchy that just isn’t needed.

This can be done simply by right-clicking on the unnamed page subform “(untitled Subform) (page 1)” object in the Hierarchy palette and choosing the “Unwrap Subform” command. The hierarchy should now look like this:

Testing the Form

Before we go on to part 2 we should make sure that what we’ve done so far works correctly. To test our form, we simply need to merge-in some movie data from the Movie Service to make sure that it gets displayed properly in the Listing table.

You can get the full movie catalog listing simply by hitting this URL:

http://forms.stefcameron.com/services/movies/

Save what you get into an XML file named “movieCatalog-sample.xml” and set it as the Preview Data File for the form using the Form Properties dialog.

Now preview the form using the “Preview PDF” tab. You should get something that looks like this:

After you’ve determined that the table is functioning correctly (which means that the bindings are working as expected), you should remove the Preview Data File setting since it’ll interfere with the Form Guide’s function later on. (A Preview Data File can be used to initialize data in a form guide however, in this case, we don’t want all the movie data to be there already; we want to query the Movie Service for it in real-time based on any actor and/or category settings the user may have specified.)

Solution to Part 1

Try not to peek at this before you attempt to build the form on your own…

Download Part 1 [zip]

Minimum Requirements: The form should work back to Designer 8.0 however it was designed with Designer 8.2.1 SP1.

The book is the result of J.P.’s own expertise and a collaborative effort with the Designer Team in Ottawa. It tackles form design and techniques in building dynamic XML-based PDF forms with Designer.

As Alan Siegel (Founder & Chairman of Siegel+Gale, branding pioneer and champion of simplifying corporate communications) put it,

“J.P. Terry is a rare individual who understands both the design and technical issues involved with effective communications. This book will teach you about LiveCycle Designer but more importantly it will teach you about effective form design.”

How to get the book

The book is now available for immediate ordering at the following sites

• PeachPit Press
• Barnes & Noble

as well as at various local bookstores.

For some reason, it’s still on “pre-order” status at Amazon.com but should be “officially” available shortly.

The Designer book will also be available for purchase at MAX 2007 and I will be giving away a copy or two at my hands-on sessions on Designing PDF Forms and Flex-based Form Guides so be sure to attend if you’re at MAX 2007 North America!

Sample Files Posted

For those of you who already have the book, you can now download the sample files from SmartDocTech.com.