Stefan Cameron on Forms

LiveCycle ES2 Ships

Stefan Cameron — Fri, 06 Nov 2009 21:11:30 +0000

Adobe’s enterprise platform, LiveCycle Enterprise Suite 2, is now officially released.

This means, amongst other awesome things about this release, that LiveCycle Designer ES2 (version 9.0) is officially released as well! Designer ES2 supports XFA 3.0 which is already supported by Acrobat 9.1.

Designer Environment Initial Setup

Stefan Cameron — Fri, 30 Oct 2009 11:18:59 +0000

While I was attending MAX 2009 a couple of weeks ago, I mentioned setting-up a keyboard shortcut for showing/hiding the Script Editor palette to one of my colleagues who thought it was the greatest thing since sliced bread! (OK, maybe not that great but it was obvious this would be a great time-saver). Since this is part of what I do whenever I install a new version of Designer, I thought others may find it useful to know all of what I do to get my form development environment setup just right, maximizing design canvas real estate and making it as easy as possible to edit scripts. The following steps are based on Designer ES2 however most should apply to older versions as well:

Click “don’t show again” on welcome screen; click ‘exit’.
Maximize the Designer window on your largest monitor — mine is a 24in monitor with 1920×1200 resolution.
Drag the Script Editor (SE), initially displayed in single-line mode at the top of the window, out over the Designer window so it’s floating in multi-line mode. Hold the [Ctrl] key down while positioning the palette so that it doesn’t dock to any side. Make the palette almost as big as the Designer window but not so wide as to hide palettes on left hand side where the Hierarchy palette is located.
Hide/close the SE by clicking on the tiny “x” at the top right hand side of the palette.
“Tools menu > Keyboard Shortcuts“; choose “Window” from “Product Area” drop down; scroll almost to the end of the command list that appears/filters below and select “Script Editor”; click the “Remove” button to remove the current [Ctrl+Shift+F5] shortcut; put your cursor in the “New Shortcut” field and press “F5″; press the “Assign” button — you’ll get a warning that F5 is already assigned to “PDF Preview” — choose “Yes” to re-assign it to the SE palette.
Optional: Set the keyboard shortcut for “PDF Preview” (under the “View” product area) to “Ctrl + F5″. I tend to always click on the “PDF Preview” tab to preview so I usually don’t bother with setting-up this shortcut.
Set “Tools menu > Options > Doc Handling > Default File Type for New Forms” to “Dynamic XML Form” — part of ensuring your forms preview as Dynamic PDFs.
Set “Tools menu > Options > Workspace > Script Editor > Show Line Numbers” to checked.
Set “Tools menu > Options > Workspace > XML Source > Show Line Numbers” to checked.
Set “Tools menu > Options > Data Binding > Show Dynamic Properties” to checked.
Set “Tools menu > Options > Data Binding > Subform Binding > Default Binding for New Subforms” to “None” or “No Data Binding” — this prevents data binding errors when adding new subforms to control layout and forces you to think of the data binding when adding subforms for data structure.
Set “Tools menu > Options > Tab Order > Display Additional Visual Aids for Tab Order” to checked — ’cause it’s really cool!
If using Designer prior to version ES2/9.0 (where toolbar customization was removed), right-click on a toolbar, choose “Customize”, then un-check “Large Buttons” to reduce the screen real estate consumed by the large toolbar buttons. It’s not much but a few pixels here and there add-up to a lot of savings.
Choose “Window menu > Font” to show the Font and Paragraph palettes docked together in a floating window in the center of the app window; dock the palette to the left hand side with the Hierarchy, PDF Structure, Data View and Tab Order palette group above; click on the Paragraph tab to activate the palette and force it to resize to its “normal” height (it’s taller than the Font palette and doing this now means it won’t shift the next time you switch back and forth between the two palettes).
Hide the “How To” palette — this leaves the Object Library on the top half of the right side and the Object/Accessibility palettes on the bottom half.
Right-click on the Object palette’s tab: you’ll get a drop down menu containing the names of other palettes within that group that aren’t visible: Layout and Border. Select Layout, then Border to show those palettes within the group.
Click on the “New” button in the toolbar (not the drop down arrow next to it, the button part) — this gives you a new document using the default document template (letter size). Drag a text field onto the form; check that the Paragraph palette on the bottom left side and Object palette on the bottom right side don’t have “expansion handles” visible, indicating that the palette UI isn’t entirely visible

Partially-visible Paragraph palette

Partially-visible Object palette

If they are visible, click on them to make the palettes wide enough to display all of the UI, then reduce the width of the left/right dock area by clicking and dragging on the edge between the palettes and the form area until the “expansion handles” appear, then drag back out just until they disappear — this ensures the left and right dock areas are just wide enough to display all palette UI but no wider than necessary so that your form design canvas real estate is maximized. You can also play with the width so that it’s just a little larger, making the Object Library Standard objects display in two columns rather than a single, long column which you may have to scroll in order to get to objects you want to use.

Fully-visible Object palette after performing steps above
Right-click on the “Design View” tab to see a context menu of hidden form canvas area views: Master Pages and XML Source. Choose “Master Pages” then “XML Source” to show the tabs. Go back to “Design View”.
Close the new form you created (most likely, there’s no need to save changes).
Choose “File menu > Open”, set the file type to “Adobe LiveCycle Designer Templates (*.tds)” and open
```
c:\Users\\AppData\Roaming\Adobe\Designer\\\Templates\Blank\Letter.tds
```
(the location will vary depending on the version of Windows you are using). This is the default template used to create new documents, as set in the Template Manager by default.
With the Letter.tds template open, choose “File menu > Form Properties > Defaults”; set “Target Version > Choose version…” to the latest available version, “Acrobat/Reader 9.1″; set “Scripting > Default Language” to “JavaScript” (thought in v9 this can now be set in “Tools menu > Options > Workspace > Script Editor > Default Language for New Forms”); (optional) set “Scripting > Default Run At” to “Client and Server” (to make sure your code runs when rendering on the server to PDF/A, for example, if this is a frequent requirement); set “Scripting > Preserve scripting changes to form when saved” to “Manually” (it’s a good habit to take care of it yourself so you don’t get into a snag with certified forms); set “Scripting > Enforce Strict Scoping Rules in JavaScript” to checked (only possible if target version is 8.1 or later and helps you write more robust scripts); set “Server > PDF Render Format” to “Dynamic XML Form” (again, to ensure your PDFs are dynamic, this time for server renderings). Ensure that “Preview > Preview Type” is set to “Interactive Form” and “Preview > Preview Adobe XML Form As” is set to “Dynamic XML Form” — makes sure that your forms are previewed as Dynamic PDFs rather than Static PDFs, even when previewing an XDP, although this still won’t help you if you if you save your form as a Static PDF.
Switch to the XML Source view and search (Ctrl+F) for “originalXFAVersion”. If found, remove the processing instruction to ensure that you are truly creating the latest and greatest type of XFA document (as you specified in “File menu > Form Properties Defaults > Target Version”) when you create a new form from the default template. Remove the following (or similar) processing instruction (PI), if found:
Click on “Design View” and apply your changes to the source.
Save your changes to the Letter.tds template. Repeat steps 20 to 22 for any other templates you use regularly.
Click on the “New” button in the toolbar (not the drop down, the actual button to the left hand side of it). Verify that your “Form Properties” settings are applied to the new form and that the originalXFAVersion PI is not in the source (the one you may have removed from the template’s source in step 22).

New Versions of Reader and Acrobat

Stefan Cameron — Mon, 19 Oct 2009 17:46:40 +0000

On Oct 13, 2009, Adobe released a security bulletin providing information about new versions of Reader and Acrobat that address various critical vulnerabilities.

The new versions are:

Acrobat/Reader 9.2
Acrobat/Reader 8.1.7
Acrobat/Reader 7.1.4

The Adobe Updater application should automatically download and install the latest version the next time you run Acrobat/Reader. Otherwise, you should definitely consider installing the updates to protect your computer. Download links are available in the security bulletin.

@SConForms at Adobe MAX 2009

Stefan Cameron — Fri, 02 Oct 2009 19:00:50 +0000

It’s hard to believe but only 48 hours remain until I find myself in Los Angeles heading to the LA Convention Center to check-in at the MAX 2009 conference. Before I head down there, I though I would share a few final details that might interest you.

Whether or not you are heading to MAX, Twitter is a huge part of MAX this year:

Though I have yet to follow the masses, I will attempt to tweet at @SConForms;
You can check-out what people are saying about MAX by searching for the #adobemax tag (and if you tweet about MAX, you should use the tag as well!); and
Each of my labs will have designated Twitter tags, #adobemax49 (Oct 6, 3:30-5pm, PST) and #adobemax357 (Oct 7, 11am-12:30pm, PST), so that attendees can collaborate, ask questions and give feedback.

The MAX Resources page has even more Twitter details, including other ways to follow MAX like FaceBook, the MAX Blog, flickr, etc.

For those of you who can’t join us this year, Adobe has just launched the MAX Online site where you’ll be able to watch live keynotes and the top 3 daily sessions.

Here’s to an awesome MAX conference this year and Happy Canadian Thanksgiving! I’ll be back to my blog as of Oct 19, after taking a little bit of time off following the conference.

Multi-Selection List Schema Definition

Stefan Cameron — Wed, 30 Sep 2009 14:07:02 +0000

After spending some time, recently, showing you how to connect your form to a schema and highlighting Designer’s support for schema metadata, I thought I would round-off my current train of thought on schemas by tackling multi-selection listboxes. Since they store their selected data in nodes, once you think about it, their schema definition may not be obvious. When you’re working with XML data that isn’t governed by a schema and namespaces, it is perhaps easier to work with (i.e. accept) these nodes however things change when you have a schema telling you how your data must be structured and scoped (with namespaces).

How Lists Store Selected Items

To better understand the challenges, let’s look at how list form objects store a multi-selection of values.

In the Form DOM, the list’s value actually contains XML rather than plain text. For example, say we have a multi-selection list named “ListBox1″ (bound to a data element named “list1″) with items (”item1″, “item2″, “item3″). If the first two items were selected, the list’s value would look like this:

In script, this would translate to a newline (\n)-delimited string when the list’s value is accessed from its rawValue property:

item1\nitem2

In the Data DOM, the list’s value is stored in a series of repeating nodes, much like the way it is stored in the Form DOM:


    item1
    item2

Adding the Schema

A schema describes how XML should be structured. Given how lists store their selected items in data, a schema that includes a multi-selection list will need to allow for the element that defines the list to contain zero or more repeating nodes. Unfortunately, this means modifying your schema, if you already have one. (I can think of at least one workaround to this which would involve script and a sibling, hidden text field bound to the element in your schema, as opposed to the list itself, in which you would store the selection, but I won’t get into that in this article.)

For example, this is a schema that defines a “form1″ root element that contains an element named “list1″ that has a multi-selection list type (the way XFA expects it).

Data Connection

The problem with this structure is that once you connect your form to this schema, the Data View connection tree will interpret the list1 element as being a subform that contains a repeating node, “value”:

Because of this interpretation, you cannot simply drag & drop the “list1″ schema element into your form in order to get a multi-selection list. Instead, you’ll get a subform with a text field inside of it instead (only an element with a simple type restricted to an enumeration of values would be interpreted as a list). Furthermore, you cannot use the picker widget next to the “Object palette > Binding tab > Data Binding property” to assign “list1″ to a listbox you have already dragged into your form from the Object Library palette because “list1″ is viewed as a container (subform) and the form object you are attempting to bind is a field.

Data Binding

In order to bind the listbox to the “list1″ schema element, you must manually type its binding expression into the “Object palette > Binding tab > Data Binding property”. For our simple use case, the binding is “list1″. Note that you don’t actually bind the repeating “value” element to anything and that the schema data connection tree will not actually indicate that the “list1″ element is bound to a form object even though it now is (I’m guessing this is because it is expecting “list1″ to be bound to a subform, not a field).

The result of binding the listbox to the “list1″ schema element is that the Form DOM output changes slightly to include the proper namespace on the bound element within the field’s value:

Submitting Data

As you might expect, given the structure of the listbox’s selection in the Form DOM above, the list’s selection data will be similar in the Data DOM (which is what would be submitted from the form as well):

The only problem with the data above is that it isn’t valid against the schema which specifies that the repeating nodes inside the list1 element are part of the “scof” (target) namespace and should therefore look like .

Submitting Namespaced Data

In order to get the namespace into the repeating nodes for the selected values, we have to use a workaround that involves a little script in the listbox’s Exit event (though the script could be triggered elsewhere, if you like):

// JavaScript:

// schema namespace info
var nspace = "scof";
var nsUri = "http://forms.stefcameron.com/ns/2009/";

// get selection from list
var selection = this.rawValue.split("\n");

// build XML string for new selection in *Form DOM*
//  that includes the namespace in the 
//  nodes the outer  node is
//  essentially irrelevant and will be discarded later
//  however it is required so that we can load its
//  content into the listbox's exData value node where
//  its value is set in the Form DOM
// this.dataNode.name gets the listbox's bound data
//  element name from the Data DOM which is required
//  in the XML
var newSelection = "\n<" + nspace +
    ":" + this.dataNode.name + " xmlns:" + nspace +
    "='" + nsUri + "'>";

// add selected items into the new selection -- take
//  note of the newline character at the beginning of
//  the string as it is critical to the XML loading
//  properly later on (it shouldn't be but it is...)
for (var i = 0; i < selection.length; i++)
{
    newSelection += "\n<" + nspace + ":value>" +
        selection[i] + "";
}

// close the XML elements in the string
newSelection += "\n\n";

// load the new namespaced selection into the listbox's
//  exData value node, ignoring the root 
//  node in the XML string
this.value.exData.loadXML(newSelection, true, true);

The script above essentially builds an XML string equivalent in structure to that which is normally used to store the list’s selection in the Form DOM however it adds the necessary namespaces to the repeating nodes. This change is then replicated in the list1 data node in the Data DOM and the form’s exported data changes to this (which can be successfully validated against the schema we’re using):

Import Data Warning

Unfortunately, I have to point-out a bug as it relates to exporting multi-selection values with namespaces (which you only get when you use the above workaround script): Importing data with namespaced nodes for multi-selection lists — though valid XML and valid against the schema — will fail in Acrobat 9.1.3 (I have not done any testing on previous versions). My testing has revealed that the form doesn’t render properly after the data merge. Importing namespaced data that does not have namespaced nodes for multi-selection lists, however, does work fine (this is the default way data is exported, unless you use the script I outlined above).

Sample Form

I have built a sample form that demonstrates how multi-selection lists store their data in the Form DOM and Data DOM. The form also includes a checkbox which, when checked, will generate namespaced nodes instead of the default nodes, using the workaround script in the list’s Exit event.

Download:

Minimum Requirements: I designed this form using Designer ES2 Beta and Acrobat 9.1.3 however the form should work all the way back to Designer 7.1 and Acrobat 7.0.5.

Featur-O-meter Fixed!

Stefan Cameron — Fri, 25 Sep 2009 03:07:03 +0000

Last week, I asked you to start voting for your favorite next feature on the new Featur-O-meter poll.

I’m not sure how many of you might have tried to vote since then and weren’t able to but I just noticed the poll was broken and it’s now fixed.

Please vote! We want to hear what you think.

Army Run 2009 Race Results

Stefan Cameron — Sun, 20 Sep 2009 19:26:21 +0000

What a perfect morning for a half marathon race! My goal was 1:30:00 but the weather was perfect, I felt really good and God answered my prayers with an official time, and personal best, of 1:28:59 (that’s a 4:14 kilometer pace for 21.1km) and a chip time of 1:28:54 (obviously I was very well positioned being only 5 seconds behind the start line). The rest of my stats are available online at Sportstats. (For comparison, my fastest time on record, so far, had been 1:36:54 at the Ottawa Race Weekend 2009 Half Marathon last May.)

This being only the second annual Army Run, the race was still small in comparison with the Ottawa Race Weekend. There were just under half the number of participants at a total of 4270 runners which made it much more enjoyable for me. Don’t get me wrong: it’s awesome to see and be with all those runners but bigger crowds pose more logistical challenges than smaller ones.

This race was special, being a way for Canadian civilians to support their troops and for the troops to say “thanks” for the support. A cannon was fired instead of the usual blow horn for the start of the race, a group of injured soldiers (one single-leg amputee hoping to break a 1:20:00 record, one double-leg amputee and others in race wheelchairs) participated, military bands were playing at various locations throughout the course and a group of soldiers were just beyond the finish line handing-out the dog tag-style finisher medals. Pretty cool!

A military band at the start line.

My sprint to the finish line — you can see I’m just about to cross over and the official time clock reads 1:28:58.

Few! Those 16 weeks of hard training really paid off!!! :)

Vote for your Favorite Next Feature

Stefan Cameron — Tue, 15 Sep 2009 16:08:50 +0000

Now that LC Designer ES2 (9.0) is in beta, the team is setting their sites on the next release. I invite you to start voting on what you would most like to see in the new version by checking-out the new Featur-O-meter poll.

The LC Designer ES2 (9.0) poll results are now archived here.

Schema Metadata

Stefan Cameron — Sat, 29 Aug 2009 03:48:35 +0000

My first tutorial on XML schemas explained how to connect your form to a schema however it did not show some of the Data View palette’s special features with respect to metadata in XML schemas.

Using metadata based on a combination of the XML Schema appInfo and Dublin Core title and description elements, you can influence how the Data Connection Wizard creates fields you drag and drop from the data connection tree into your form. You can also direct the Data View palette to show some of this information in the Schema Data Connection Tree that it displays.

To demonstrate these features, I have extended the original movie rental schema by adding metadata to its schema elements.

Element Descriptions

Sometimes a schema element’s purpose or use isn’t immediately clear based on its name and/or other properties. For example, just by seeing that the schema has a “customer.account” element wouldn’t necessarily tell you that this element should be empty for a new customer (since the system would generate a new account number upon submission of the customer’s first movie rental order). To clarify the use of this element, a description can be provided:


    
        
            
                Customer's account number (empty if it's a new customer).

Using the “Data View palette > Palette menu button > ‘Show Both’ command”, you can see the metadata associated with elements in your schema right within the Data Connection Tree:

Note that the description element must be part of the Dublin Core namespace (xmlns:dc=http://purl.org/dc/elements/1.1/) and must be contained within the XML Schema //annotation/appInfo elements in order for the Data Connection Wizard to detect it.

Form Object Captions

Often times schemas are defined at a corporate level because they can represent business rules and describe how data must be structured for its systems to be able to interpret it correctly. In those cases, it may be useful to also influence/dictate the labels that should be used to identify fields associated to certain schema elements. This can also be achieved with metadata by specifying title information:


    
        
            Account #:

Unlike descriptive metadata, this information is not displayed in the Data Connection Tree. Instead, it is used by the Data Connection Wizard when you drag and drop a schema element from the Data Connection Tree into your form.

Remember that, in the original schema (that didn’t have any metadata), generated fields would get captions similar to their schema element names. For example, dragging the “customer.account” field into a form would produce a field with “Account” as its caption. With the title metadata as defined above, the generated caption would instead be “Account #:”, as in the image below:

Note that the title element must be part of the Dublin Core namespace (xmlns:dc=http://purl.org/dc/elements/1.1/) and must be contained within the XML Schema //annotation/appInfo elements in order for the Data Connection Wizard to detect it.

Extra Descriptive Information

There’s one more way to provide information related to an element in a schema: Any text that is directly specified within an XML Schema //annotation/appInfo element (and is not further contained within a Dublin Core title or description element) is interpreted as extra “descriptive information”. When the element is dragged and dropped into a form, this text will be imported and associated with the generated field within a node, provided the “Generate Descriptive Information” option is checked in the “Data View palette > Palette menu button > Options dialog”:

For example, the “returnBy” schema element is defined as follows:


    
        ...
        
            Movies must be returned by 11:59pm on this date.
        
        
            The late fee is is $0.50/hour.

Dragging and dropping that element into your form would produce the following field mark-up in the XML Source view:


    ...
    
        
            Movies must be returned by 11:59pm on this date.
        
        
            The late fee is is $0.50/hour.

The Info palette could then be used to view the contents of all nodes inside the selected field’s node:

You can associate any number of extra “descriptive information” metadata elements to a single schema element definition. Each one would be imported as a separate node within the associated form object’s node

This information can also be viewed within the Data View palette by choosing the “Palette menu button > ‘Show Info’ command”. This will display the Info Panel in the bottom half of the palette. Selecting the “returnBy” schema element would then display the following information:

XFA object name (returnBy);
associated XFA object type (date/time field, since the schema defines its type as “date”);
occurrence (single since it isn’t repeatable like the “movie” element, for example); and
all other metadata identified as “descriptive info” associated to the element.

Script Access

Finally, the descriptive information found in a form object’s //desc/text nodes can be retrieved via script by accessing its “desc” node property and iterating through all child nodes that are of type “text” and have “Schema Annotation” in their name.

For example, to output the two descriptions in the “returnBy” field (as defined above) to the JavaScript Console in Acrobat, you could use the following script:

// JavaScript:
var descList = returnBy.desc.nodes;
for (var i = 0; i < descList.length; i++)
{
    var item = descList.item(i);
    if (item.className == "text" && item.name &&
            item.name.indexOf("Schema Annotation") == 0)
    {
        console.println(item.value);
    }
}

With a little more effort, you could parse-out all sorts of useful information provided by this type of metadata in your schemas though, most of the time, that information can usually be expressed in real schema mark-up (e.g. list items and values).

Combinations

Of course, you aren’t limited to using a single type of metadata on a given schema element: You can combine them to provide the degree of information you require for any element. For example, the “customer.account” element specifies both title and description metadata while the “returnBy” element specifies title and descriptive information metadata.

Adobe MAX 2009 Lab Update

Stefan Cameron — Mon, 24 Aug 2009 17:00:33 +0000

We have been hard at work on our Solution Accelerator lab (filter by Speaker and choose my name, “Cameron, Stefan”). Now that the content is coming together, there have been a few changes which I thought I should mention in light of my previous post.

In order to ensure the lab is successful in the short amount of time we have (90 minutes) to build a small end-to-end solution, the Content Creation (CCR) and Correspondence Generation (CGR) building blocks will no longer be featured. Instead, we will feature the following building blocks, which should give you a taste for their power to accelerate your own solutions:

Selection and Capture (SNC) — capture data and guide users through filling specific forms within a given set;
Review, Commenting and Approval (RCA) — review the submitted forms and approve or reject as needed;
On-Demand Assembly (ODA) — automate the creation of a PDF package, a single PDF document containing a copy of submitted forms and other appropriate documentation.

In the mean time, here’s some fun MAX trivia. You never know when it might come in handy…