Stefan Cameron on Forms
Building intelligent forms using Adobe LiveCycle Designer

Archive for January, 2007

Barcoded Forms (PDF417) Primer

Lee Sutton has posted a what looks like a really good introduction to LiveCycle Barcoded Forms along with some tips and best practices for using 2D barcodes (PDF417 in particular) on your forms and in your workflows.


Posted by Stefan Cameron on January 24th, 2007
Filed under Tutorials

Bug: Images aren't always embedded into PDFs

Description

Image objects (images and image fields) have a property which you can set to specify whether the image should be embedded or linked (the "Embed Image Data" check box on the Object palette’s Field tab).

When the property is checked, the result is that the image file loaded into the image object is embedded into the XFA Data that’s stored in the form. When the property is unchecked, only the URI (file path or URL) is stored in the XFA Data.

I put emphasis on XFA Data above because it’s important to understand the difference between the XFA layer and the PDF layer of a PDF form in order to understand what this bug is all about: Essentially, an XFA form saved as a PDF file results in a PDF container with the XFA inside (as opposed to saving the form as an XDP where the XFA form is at the top layer). When the PDF form is subsequently filled and saved within Acrobat (Standard or Pro), the image loaded into an image field object is supposed to be saved on one layer or the other depending on the setting of the "Embed Image Data" property on the image field.

When you save a PDF form in Acrobat, what gets saved in the XFA Data (in the XFA layer) depends on the value of the "Embed Image Data" property (which maps to the //field/ui/imageEdit@data attribute). If it’s set to "link" (unchecked), then only the original path to the image file is saved. If it’s set to "embed", then the image file is text-encoded and saved in the data instead of the original file path. In either case, however, the image should always be embedded into the PDF layer (don’t worry, it doesn’t actually get embedded twice, once on each layer, I’m just simplifying things a little here) such that the PDF is self-contained and can be re-distributed without having to ensure that the linked image file remains accessible from any location.

Unfortunately, there are cases when the image file doesn’t get embedded into the PDF layer when it should be. For example, if you have an image field object which is set to link to its image file and you load the image by importing data that contains the file path then save the PDF, the image won’t be embedded into the PDF as expected.

Workaround

At this time, I’m not aware of any workarounds to the specific issue I stated above (when importing the image’s file path).

The only way to consistently get image files to be embedded into the PDF as they should be — regardless of the image field object’s setting to link or embed its data — is to manually click on the image field object in Acrobat and pick the image file.

Fix

Please refer to the Bug List for updated information on the version(s) affected by this bug as well as if and when it was/will be fixed.

Update (May 22, 2008)

This bug was addressed in Acrobat/Reader 8.1 (XFA 2.6, PDF 1.7) in a way that addresses both security and PDF self-containment issues.

For XFA 2.6+ forms (forms authored in Designer 8.1+), images that are linked (referenced) rather than being embedded are now stored (the bits are embedded) in an array in the PDF layer when the PDF form is saved. At runtime, if an image is linked (referenced) rather than embedded, Acrobat/Reader will look for the associated image bits in the PDF layer and, if a match is found, will load the image. This means that Acrobat/Reader no longer goes outside of the PDF to fetch images unless explicitly directed by the user (e.g. the user clicks on an image field and chooses an image on their own) which addresses security issues. The fact that linked images are now stored in the PDF layer also addresses self-containment issues where the nature of a PDF document is that it is a self-contained entity (e.g. when you email a PDF, the recipient can always open it and see its content even if they don’t have access to referenced content — the exception being if the form makes an external data connection to a database or web service or needs an XML data file to be imported).

Image fields with content embedded at design time are still stored in the XFA data as they were before. You may still load an image dynamically from data provided that the data is the actual image bits or, if the data is a link, that there are associated image bits already in the PDF layer (which implies that the image was linked from the form at design-time — for example, you could have 5 hidden image objects each linking to different images and then use a link in the data to control which of those images show up in an image field on your form). In either case (whether the image is loaded via embedded bits or a link), the image bits always end-up in the data submitted from the form. The original link is not included in the submitted data nor is it available at runtime via scripting (unless imported in data via a data connection or XML data file) because it could contain sensitive information (e.g. your username).


Posted by Stefan Cameron on January 23rd, 2007
Filed under Acrobat,Bugs

Setting JavaScript as the Default for New Forms

If you’ve ever written scripts in Designer, you will have noticed that the default scripting language is FormCalc which is a problem if you need to (or prefer) to write your scripts in JavaScript.

The easiest way to make sure that all your new scripts default to the JavaScript language is to use the Form Properties dialog and set JavaScript as the default scripting language (in the Defaults tab). The problem with this setting is that it affects only the current form. If you’re like me, you create lots of forms every day, you constantly forget that the default scripting language is FormCalc and you only remember once you’re running your form and you get a FormCalc error message box in Acrobat telling you that your syntax is incorrect. How annoying!

Fortunately, there’s a way to set JavaScript as the default scripting language for all new forms — based on a specific template. The default setting for the scripting language is actually specified as a processing instruction in the XML Source. If you create a new document and go to the XML Source tab, you’ll find the following processing instruction set as a child of the <template> element (also shown in the image below):

<?templateDesigner DefaultLanguage FormCalc?>

Since all new documents created in Designer are based on templates and that each template comes with its own set of processing instructions, modifying the processing instruction in the template would effectively modify the default scripting language on all new forms based on that template. Going one step further and making that modified template your default template would ensure makes things even easier when you’re creating new forms.

Fortunately, you don’t have go to the XML Source view to modify this processing instruction. Instead, you can set its value using the Form Properties dialog (accessible via the File menu): In the Defaults tab, set the Default Language property to “JavaScript”.

Modifying Designer Templates

In Designer, you use the Template Manager to organize your templates. You can access the Template Manager from the Tools menu.

To modify a template, you can follow these easy steps:

  1. Create a new document based on the template you wish to modify.
  2. Make the necessary modifications (like setting the processing instruction for the default scripting language setting to "JavaScript").
  3. Save the new document as an "Adobe LiveCycle Designer Template (*.tds)" file. If you want to replace an existing template (say "Letter"), use that same name as the file name for the new (modified) template file you’re saving.
  4. Using the Template Manager, select the tab pertaining to the group in which you want to add your new template. If you’re wanting to replace the "Letter" template, for example, select the "Standard" tab.
  5. Right-click in the list panel and select "Add Template…". Select the template you just saved and it’ll be added to Designer’s "template store". Note that if the name of your new template file is the same as an existing template in the group you selected (e.g. the "Letter" template in the "Standard" group), you’ll be prompted to overwrite the existing template.

One important thing to note in the way Designer handles templates is that any template file you add to the Template Manager gets copied into the "template store" which means that new documents based on that template aren’t actually based on the template file in the location where you saved it but rather on the copy that was placed in the "template store".

If you’re wondering what the "template store" is, it’s actually a folder inside Designer’s Application Data folder on your system. While I don’t encourage you to look in there (because you might see things that look interesting but you shouldn’t be playing with ;) , if you find them, then you should also be able to open them directly in Designer and modify them without having to create a separate copy.

Updated: January 17, 2006


Posted by Stefan Cameron on January 10th, 2007
Filed under Events,Script Editor,Scripting

New Scripting Basics Guide

I was looking around in the LiveCycle Developer Center today and came across a great beginner’s guide to scripting in Designer that Alex Mitchell, a colleague of mine here at Adobe, recently posted to the site.

Even though it’s labelled as "beginner", there’s some great stuff in there regardless of your level of expertise. For example, there are some really nice flow charts illustrating the order of execution of form and field events and the section on Creating and Resuing JavaScript Functions should come-in handy for those complex forms. There are also some examples of common scripting tasks which could be useful in all types of forms.


Posted by Stefan Cameron on January 4th, 2007
Filed under Scripting

Return to the Blog

Thank you all for your patience while I was away. I have finally weeded through hundreds of comments and have identified the real ones from the spam ones.

In order to be fair to everyone, I will be responding to comments in the order in which I received them. While it may take me a while to get to comments which were posted in the last few days, rest-assured that I will get to them eventually.


Posted by Stefan Cameron on January 4th, 2007
Filed under General