Have you ever wanted to shade (color) a field’s caption instead of its content area? For example, you may want

instead of (entire field shaded)

 

or (field’s content area shaded)

Shading the entire field is easy: just set the background fill color using the Border palette. Shading the field’s content area is easy too: just choose “Object palette > Field tab > Appearance > Custom…” and set the background color in the Custom Appearance dialog that appears. Shading the caption, that’s not so trivial, unfortunately.

There are actually six (six!) steps involved in shading a field’s caption if you want the end-result to be a field that has a shaded caption but retains all of the original spacing (i.e. margins) of the caption’s text and the field’s value (don’t worry, it only seems long because I explain the logic of the steps along the way):

1. Set the field’s background color to blue (or whatever color you want the caption to be): “Border palette > Background Fill > Style > Solid” and use the color well to choose the color you want.
2. Set the field’s content area background color to white (the “paper”/document color): “Object palette > Field tab > Appearance > Custom… > Background Fill > Style > Solid” and use the color well to set the color to white.
3. Remove all field margins but remember what they were — we’ll need them in the following steps (this gets rid of the color you see above, below and to the right of the field’s content area): “Layout palette > Margins” and set all of them to zero.
4. Set the field caption’s indentation and spacing paragraph formatting properties to the original margins: “Paragraph palette > Edit Caption Properties” using the edit menu as follows:

   

   This will ensure that you’re only modifying the caption’s paragraph formatting properties (the default is set to modifying both the caption and value, or “content area”, at the same time). The set the “Indents > Left”, “Indents > Right”, “Spacing > Above” and “Spacing Below” to the original left, right, top and bottom margins, respectively. This will give the illusion of margins around the caption without actually setting the margins so that the field’s background color we set in step 1 won’t be visible around the field’s content area.

5. Set the field’s content area (value) indentation and spacing paragraph formatting properties to the original margins except for the left spacing otherwise the spacing between the caption and content area (value) will be doubled because we’ve already set the caption’s right spacing to the original right margin: “Paragraph palette > Edit Value Properties” using the edit menu as above. The set the “Indents > Right”, “Spacing > Above” and “Spacing > Below” to the original right, top and bottom margins, respectively. Ensure that “Indents > Left” is set to zero. This will give the content area the illusion of having margins without actually setting margins on the field. (Note that this may conflict with paragraph formatting you may want on a multi-lined text field, for example. If that’s the case, you simply may not be able to give the effect of the original margins on the content area.)
6. Add the original left margin value to the field caption’s reserve (the space reserved within the field’s “box” for displaying the caption): “Layout palette > Caption > Reserve” and add the left margin value to the value currently set in the Reserve property. This will move the content area back to its original horizontal position prior to removing the margins.

So there you have it: a shaded caption! Now that you’ve done these steps, all you need to do to change the shade is change the field’s background color (like in step 1).

Remember that you can always store a field you’ve formatted this way as a custom object in the Object Library so that you can easily re-use it again in other forms without having to go through these steps again.

To illustrate this a little better, I’ve included a sample form that shows the various ways to shade a field:

Download Sample [pdf]

Minimum Requirements: I created this form using Designer 8.1.1 SP2 and Acrobat 8.1.2 however this technique should work at least back to Designer 7.1 and Acrobat 7.0.5.

---

Posted by Stefan Cameron on June 13th, 2008
Filed under Designer,Tutorials

---

Here’s a quick observation you might find useful: The order in which form objects are initialized is “field and depth-first” according to the document order (the top-down order in which they appear in the Hierarchy palette in LiveCycle Designer). This means that fields inside a subform are initialized before the subform itself is initialized. When you think about it, it makes sense since this means that in a subform’s Initialize event, you always have access to properly-initialized child form objects. You can read more about event execution order in the LiveCycle Designer Scripting Basics document (page 24) as well as in the

XFA Spec (page 353 in version 2.7).

Say your form object hierarchy looked like this (in the Hierarchy palette in Designer):

The fields and subforms would get initialized in the following order:

To clarify, this is the order (note that text objects don’t get initialized just like squares, circles and images wouldn’t — image fields would, however):

0. DateTimeField1
1. TextField1
2. PasswordField1
3. Subform2
4. NumericField1
5. Subform1
6. CheckBox1

To demonstrate this, I’ve provided the form that contains the objects above. When you preview the form (or view it in your web browser) using Acrobat, use the JavaScript Console to see the output from the Initialize events of the various form objects to see the order of initialization.

Download Sample [pdf]

Minimum Requirements: I created this form in Designer 8.1.1 SP2 and tested it in Acrobat Pro 8.1.2.

---

Posted by Stefan Cameron on May 9th, 2008
Filed under Events,Scripting,Tutorials

---

LC Designer ES (8.1) introduced a new feature called Target Version to help you design forms for use in specific versions of Acrobat/Reader. Although new releases of Designer usually support most new features introduced in new releases of Acrobat, there are still some differences and the Target Version feature will help you ensure that your form isn’t using a feature that isn’t compatible with the version of Acrobat/Reader that you’re targeting (the version you expect the users of your form to use).

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.

---

Posted by Stefan Cameron on April 18th, 2008
Filed under Acrobat,Debugging,Designer

---

A colleague of mine on the Form Guide Team, Gilles Maurice, has assembled an extensive video-based tutorial on customizing Form Guides (a new Flash/Flex-based form technology available as of LiveCycle Designer 8.1) using Flex Builder, sample code included.

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!

---

Posted by Stefan Cameron on April 14th, 2008
Filed under Form Guides,Tutorials

---

This is something many of you have asked me about in the past and I never had a definite answer. The only method I knew of was to use a print button from the Object Library palette and add some checks for invalid data (or unfilled fields) inside its click event which is set to call xfa.host.print() by default. The problem with this method is that the user could still print using Acrobat’s print command (either via “File > Print”, the print button in the toolbar or by using “Ctrl + P”).

I didn’t know any better because, well, prior to Acrobat 8, there wasn’t really anything better and the reason was that form validations simply weren’t triggered prior to Acrobat receiving the command to print. So while you could easily prevent a form from being submitted electronically if validations failed, there was no definitive way to prevent it from being printed… until Acrobat 8 and XFA 2.5 came along, that is.

Advanced Tutorial: Before you read further, I should warn you that this is an advanced tutorial as it (unfortunately) requires editing the “XML Source” using Designer since Designer doesn’t have settings for this yet.

New Validate element in the Config DOM

In version 2.5, the Present element in XFA’s Configuration Document Object Model (“Config DOM” for short), which houses configuration options for XFA applications (such as Acrobat and Reader), was extended to have a Validate element.

This element can have any of four optional values, each separated by a space: “prePrint“, “preSubmit”, “preSave” and “preExecute”. By default, the element is not specified and the default behaviour (which is the same when the element is specified but contains no values) is to validate prior to submitting the form only. Once values are specified, then validations are run only prior to the specified events.

For example, if you wanted to have a form that prevents the user from printing but not submitting when a mandatory field is empty, you would specify the following validate element in the Config DOM (the ellipsis mean there’s other stuff in there; what’s important is the validate element inside the present element):

<config>
   ...
   <present>
      ...
      <validate>prePrint</validate>
      ...
   </present>
   ...
</config>

Unfortunately, this isn’t something that you can reliably set via script since these options are typically read-in on load and aren’t read again. Furthermore, Designer does not yet support setting the values in the validate element. In order to set this option, you’ll need to edit the XML Source in Designer and find the following markup about 2/3 way down:

<config xmlns="http://www.xfa.org/schema/xci/1.0/">
   <agent name="designer">
      ...
   </agent>
   <present>
      <!--  [0..n]  -->
      ...

Once you’ve located the <present> element inside the <config> element (the Config DOM), you’ll need to insert the <validate> element:

<config xmlns="http://www.xfa.org/schema/xci/1.0/">
   <agent name="designer">
      ...
   </agent>
   <present>
      <!--  [0..n]  -->
      <validate>prePrint</validate>
      ...

(Notice the <validate>prePrint</validate> element above.)

When you’re done making the change, click on the Design View tab and make sure you say “yes” to have your changes applied.

XFA 2.8/Acrobat 9 Update: With the release of XFA 2.8 and Acrobat/Reader 9.0, the <validate> element is now located under the <acrobat> element in the Config DOM:

<config>
   ...
   <acrobat>
      ...
      <validate>prePrint</validate>
      ...
   </acrobat>
   ...
</config>

To ensure backward compatibility, if the <validate> element is not found under <acrobat>, Acrobat/Reader will fall back to looking inside the old <present> to see if it’s defined there.

Now you’re probably wondering what the different values mean so here’s a quick explanation:

• prePrint: Failed validations prevent the form from printing.
• preSubmit: Failed validations prevent the form from being submitted electronically.
• preSave: Failed validations will not prevent the form from being saved however Acrobat/Reader will issue a special warning message, after issuing the validation error message, to inform the user that the validations failed. I’m guessing this is because the user may be saving the form to continue filling it at a later time so the save can’t be completely prevented.
• preExecute: Failed validations will prevent the form from executing a data connection (usually to a web service).

In all cases, any validation error messages will be displayed and this should work in Reader 8 as well. If you have set validation warnings (as opposed to errors), then the warnings will be displayed but the user’s action will not be stopped.

Sample Form

I took the time to put together a little sample form which demonstrates a Dynamic PDF form that cannot be printed nor submitted in Acrobat/Reader 8 and above unless the text field is filled.

Download Sample [pdf]

Minimum Requirements: Acrobat/Reader 8 or above.

Updated: December 20, 2008

---

Posted by Stefan Cameron on April 13th, 2008
Filed under Acrobat,Designer,Tutorials

---