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

This is a design pattern that the Form Guide Team adopted when they conceived the default Form Guide user experience. Since the appearance of a field in a form guide doesn’t have to be the same as that of the field in the form (PDF), they were able to automatically add an asterisk next to mandatory fields without affecting their PDF counterparts.

For example, in the following images, the Name and Address fields are mandatory (“Object palette > Value tab > Type property” is set to “User Entered – Required”) while the rest are optional. Notice how the captions of the Name and Address fields in the Form Guide have asterisks while the ones in the PDF don’t (and I didn’t have to do anything other than include those fields in a panel in a Form Guide in order to get this functionality):

— Form Guide

— PDF

Unfortunately, while XFA gives us the ability to mark a field as mandatory, Acrobat/Reader doesn’t automatically set them apart like the Form Guide does. Perhaps that’s a good thing because it gives you full control over how to identify fields as being mandatory.

Mandatory fields could be highlighted in different ways: An asterisk, a different background color or various other types of styles. If you use an asterisk, however, the tendency is to put it in the caption but doing this manually can be tedious if there are a lot of fields. What if some fields only become mandatory after certain conditions are met as the user is filling the form? If you don’t put the asterisk in the field’s caption (so that you can easily show/hide it when necessary using script), then you risk getting into various layout issues trying to get the asterisk to show-up at the right position next to each field. It also means lots more form objects which could really bloat your form.

That’s why I decided to implement a script that automatically adds the asterisk to a field’s caption. That way, you don’t have to worry about the asterisk — just mark the field as mandatory, run the script on initialization and it will search the entire form, placing a red asterisk in the captions of mandatory fields regardless of nesting levels. Furthermore, if you decide to use a text object as a caption next to a caption-less field or radio button list, the script will mark it with an asterisk as well (provided the text object’s name is the same as the field/radio button list’s but with a “_Caption” postfix).

Applying my script to the sample above would yield the following results in the PDF without affecting field appearances in the Form Guide:

— PDF

mandatoryLib

The following sample form references the auto-asterisk script in the mandatoryLib script object fragment. I suggest you download the fragment (see link below) and reference it in all the forms in which you want to use the script. Feel free to enhance it as well if it doesn’t work quite right for your particular needs: The script is heavily commented so it should be easy to follow and extend.

There are two functions you can call:

• IdentifyMandatoryFields(formObj): Given a form object (field or container such as radio button list or subform), find all mandatory fields inside (all nesting levels) and add an asterisk to their captions (actual captions or text object captions).
• ToggleMandatoryField(formObject, isMandatory): Given a field or radio button list, toggle its mandatory state by adding (isMandatory == true) or removing (isMandatory == false) the asterisk.

Furthermore, since the scripts handles both plain and rich text captions, you don’t have to worry about making sure all captions use rich text formatting.

Note about rich text: If you look at the script, you’ll notice that the rich text value of a field’s caption or text object’s content is retrieved from the Template DOM rather than the Form DOM. The Template DOM is where the design-time form object definitions are stored (it’s what you define when you edit the form in Designer) and cannot be modified at runtime (i.e. Acrobat/Reader) while the Form DOM, generated at runtime, is very sparse and contains only what is needed to render the form object in its current state. That means as long as there are no modifications to the rich text value, it will not appear in the Form DOM and must be retrieved from the Template DOM instead. One draw-back of this issue is that if you make any modifications to the caption/text object and then run the script, those modifications will be lost because the script will use the un-modified rich text from the Template DOM rather than your modifications stored in the Form DOM.

Download Sample [pdf] (if you plan on editing this Designer, you’ll also need the fragment below in the same folder)

Download mandatoryLib Fragment [xdp] (to download, right-click on the link and choose “Save Link As…”)

Special Thank You to my friends at Avoka for pointing-out that my original solution didn’t handle mandatory fields in repeating subform instances.

Sample Minimum Requirements: Since the script object uses dynamic object variables for optimization, I had to set it to use XFA 2.8 which means you’ll need Acrobat/Reader 9.0 to run it.

mandatoryLib Minimum Requirements: You could probably get away with running this script in an XFA 2.5 form (Acrobat/Reader 8.0), maybe even less, but the optimizations with the $formObjMap object may not function properly due to an aggressive JavaScript Garbage Collector in earlier versions (in other words, the script may run slower but it should still run).

Aug 28, 2009 — Separated mandatoryLib script object out into a script object fragment.

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

This tutorial will show you how to (1) design a form with a table that has a repeating row, (2) add some Flex code to it that will enable the use of the mx.rpc.http.HTTPService class for retrieving data from my Movie Service and (3) design a form guide that will capture the data from the service and transfer it into the PDF which could then be used to print or archive the movie listings.

In an effort to wet your appetite, I thought I would get the ball rolling by showing a little preview of the final solution.

Be sure to come back every day, Monday to Wednesday next week (November 17-19, 2008), to get the full tutorial.

You have a compliant form that has sections for users to fill-in information. Because the form is compliant (i.e. its layout has received the “stamp of approval” and cannot change without another lengthy approval process), the sections cannot grow (they cannot expand-to-fit all of the text users may fill-in). To provide more space for users to add more text, you’ve provided an expandable “overflow” section at the end of form since expanding that section will not affect the portion of the form which has been approved.

The problem

You need to capture the text entered into the form using an interactive Form Guide which is not limited to the restrictions of the form’s approved layout. As such, the Form Guide will capture the text in a single field and you need that text to be entered into the PDF version of the form. If you put all the text into the appropriate section on the form, it won’t fit and the text will be cut-off (e.g. it will not print entirely and you will miss some of the important information).

You need some way to automatically split that text between the small section in the form and the overflow section at the end of the form. In other words, you need to ensure that only the text that can fit within the small form section is placed there and the rest is placed in the overflow section at the end.

In Designer 8.2, the content of fields can now be split between pages however in this case, you can’t use this feature because the small form section can’t be expanded (it’s fixed in size).

The solution

This is the problem Stephanie, Glenn and I were faced with on a recent customer visit. Stephanie took the time to put this into a sample form which provides the script we wrote to handle this task. It’s basically a mini text parser written in JavaScript that splits text between two fields with a fixed-width font (e.g. Courier New, Lucida Console, etc.).

This tutorial goes beyond the customizations you can do with the Guide Builder tool and uses Flex Builder to create customized guide and panel layouts as well as customized components for displaying data and more. If you’re in to form guides or you’re curious about what you can do with this technology, this should be well worth your time!