As he puts it, there are limitations, the biggest ones of them being, in my opinion, the inability to debug script objects and the inability to retain breakpoints between debugging sessions. Nonetheless, this tool can give you way more insight than the good old “JavaScript Console + saveXML(‘pretty’)” combination can in certain cases, and it does it in a nice tree to boot!

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.

For example, say you have a simple form with a text field and a numeric field. The following statement will output the form’s data to the JavaScript Console in Acrobat:

console.println(xfa.datasets.data.saveXML());

The result, however, isn’t very readable:

<?xml version="1.0" encoding="UTF-8"?>
<xfa:data xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/"
><form1
><TextField1
>asdf</TextField1
><NumericField1
>1234</NumericField1
></form1
></xfa:data
>

Though I had been using saveXML() for quite some time, I hadn’t realized that it actually takes an optional parameter, a string with a value of “pretty”, that results in much nicer output.

console.println(xfa.datasets.data.saveXML('pretty'));

results in the following pretty/readable output:

<?xml version="1.0" encoding="UTF-8"?>
<xfa:data xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/">
   <form1>
      <TextField1>asdf</TextField1>
      <NumericField1>1234</NumericField1>
   </form1>
</xfa:data>

One other nice thing about console.println() for outputting debug information to the JavaScript Console in Acrobat is that these strings are also output to the Flash Log when you run form guides generated with LiveCycle ES Update 1 (8.2.1) using the Flash Debug Player. (The 3rd part of my MAX 2008 Tutorial series has details on how to set this up under the “Flash Log and Debug Players” section.)

What?

It started with a form I had created using Designer 8.1 which was set to target Acrobat 8.1/XFA 2.6. Later-on, I installed Designer 8.2 and wanted to update my form to target Acrobat 9/XFA 2.8.

In my form, I had a script object with various functions that used the following syntax to test the existence of a field inside a subform object which was passed-in to these functions as a parameter:

if (subformObj.someField)

The result of this was what I expected: If ‘someField’ existed inside ‘subformObj’, the IF statement would evaluate to ‘true’; if it didn’t, it would evaluate to ‘false’. According to the rules of dynamic properties in JavaScript, this was all fine and dandy.

All my scripts were set to run on client only. Then I found myself having to execute them on the server. So I set all my scripts, including my script object, to Run At ‘Client and Server’ using the Script Editor. That’s when the problems first started showing-up. The server log showed the following error messages whenever the JavaScript engine would come across the above IF statements in cases where, after a little investigating, I determined ‘someField’ was not inside ‘subformObj’:

GeneralError: Operation failed.
XFAObject.someField:2935:XFA:form1[0]:bodyPage[0]:subformObj[0]:otherField[0]:initialize
Invalid property get operation; subform doesn't have property 'someField'

But why was I getting these error messages? My form was executing just fine in those circumstances on the client (in Acrobat and Reader 9) and I even had "Form Properties > Defaults > Enforce Strict Scoping Rules in JavaScript" enabled in my form.

Why?

Well it turns-out that while my form was now targetting Acrobat 9/XFA 2.8 (since my <template> node’s namespace, in the XML Source view, was properly set to "http://www.xfa.org/schema/xfa-template/2.8/"), it was still behaving like an XFA 2.6 form! That meant that my scripts were subject to the same rules as scripts running in Acrobat 8.1, not Acrobat 9.

Back in Acrobat 8.1/XFA 2.6, the client-side XFAObject form objects in JavaScript supported the addition of custom/dynamic properties yet the server-side (LiveCycle; xfa.host.name == "XFAPresentationAgent") ones did not. Hence the error messages like the one above.

How did this happen? Well, when I opened my old Designer 8.1 form in Designer 8.2 and updated its target to Acrobat/Reader 9 and XFA 2.8, Designer did what it does by default which is insert the following processing instruction in the form in order to give the form access to the new XFA 2.8 APIs yet make it still behave like an XFA 2.6 form in order to maintain compatibility:

<?originalXFAVersion http://www.xfa.org/schema/xfa-template/2.6/?>

Unfortunately, that’s not what I wanted. My intention, when updating the form’s target version, was to make that form Acrobat 9 + XFA 2.8 compliant — even if it meant I had to potentially deal with some behavioral differences — in order to take full advantage of all the new features and bug fixes.

Once I removed the offending processing instruction (by going to the XML Source view in Designer and removing it manually since there’s no UI to do this), Acrobat and Reader 9 began to throw the same exceptions as the server which was good because it meant I was finally in the situation I had wanted all along: XFA 2.8 compatibility and behavior!

Thankfully, fixing my script wasn’t too difficult. The new version,

if (subformObj.resolveNode("someField"))

works very predictably for both client- and server-side rendering and what’s more, the custom/dynamic properties I do create on regular JavaScript Object variables are safe from garbage collection.

Recommendations

If you want to understand more about form target and compatibility settings along with the do’s and don’ts of custom properties in JavaScript within XFA forms, I highly recommend you read John Brinkman’s posts on the scope of JavaScript objects and form compatibility settings.

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.

You can set a form’s target version by using the “File menu > Form Properties > Defaults > Target Version” property.

For example, the “Lock Fields After Signing” feature of digital signature fields is not supported in versions of Acrobat/Reader less than 8.0. By setting your form’s target version to “Acrobat/Reader 7.0.5 or later”, Designer would issue a warning (in the Warnings palette) about this fact if you placed a digital signature field on your form and checked the “Object palette > Document Signature > Lock Fields after Signing” box.

The Target Version Reference document (under the “Develop” tab) details the versions of Acrobat/Reader that are compatible with Designer features from version 6.0 to 8.1, incl. This should help you ensure that your forms are always compatible with the versions of Acrobat/Reader you expect your target audience to use.

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).

Even if you haven’t, it may happen someday so here’s the remedy for the case of the “Common (Static PDF) Flue”…

In Designer, there are two different locations containing settings which affect the type of temporary PDF file created when you click on the Preview tab:

1. Under the “File Options” section within the “Document Handling” panel of the “Tools | Options” dialog, you can set the Default File Type for New Forms. This type is used on new forms which you preview prior to saving (because Designer doesn’t know which format you’ll use at the time of preview). This is set to a static PDF format by default.
2. Even if you’ve specified a dynamic PDF format for the Default File Type for New Forms, this setting may be overridden by the Preview Type and XDP Preview Format properties in the “File | Form Properties” dialog in the “Defaults” panel once you’ve saved your form. The Preview Type property, set to “Interactive” by default, determines whether the form will be previewed as an interactive (dynamic) form or as a print (static) form. This property supersedes the PDF format. The XDP Preview Format property usually picks-up the Default File Type for New Forms setting and determines what PDF format will be used to preview your form should it be saved as an XDP. (Note that if you’ve saved your form as a PDF file, then the XDP Preview Format setting is ignored).

Now that we’ve covered the different properties which affect the PDF preview format, here’s how to kick that flue I was talking about earlier (so that you actually do preview in a dynamic PDF format and stop pulling your hair out):

1. If you haven’t saved your form, make sure the Preview Type is set to “Interactive” and that the Default File Type for New Forms is set to a dynamic PDF format. You may also want to set the XDP Preview Format to a dynamic PDF format while you’re at it.
2. If you’ve saved your form as a dynamic PDF, make sure the Preview Type is set to “Interactive”.
3. If you’ve saved your form as a static PDF, none of these settings will help you. You must first save your form as a dynamic PDF.
4. If you’ve saved your form as an XDP, make sure the Preview Type is set to “Interactive” and the XDP Preview Format is set to a dynamic PDF format.
5. If you’re tired of running into these problems and want to avoid them in the future, just set your Default File Type for New Forms to a dynamic PDF format.

I hope this tip improves your form design health. It did wonders for me!

_{Updated: January 27, 2007}