Understanding the Submit function in Adobe LiveCycle Designer

Using Adobe® LiveCycle™ Designer software, you can create three types of buttons:

• Regular — Can be used to run a script or calculation, for navigation, or to play a sound or movie
• Submit — Used to submit data (including optional attachments) and/or client requests to a server
• Execute — Used to call Web services or execute a database query

This tip discusses the Submit control — how it works and what happens when you implement it on a button.

The tabs in the Object palette vary according to the object you have selected. When you drag a Button object on to the form design, its default Control Type is Regular. For buttons with a Control Type of Regular, the Object palette displays one tab, the Field tab. However, when you change the Control Type to Submit or Execute, the Object palette displays an additional tab. For a button object with a Control Type of Submit, the Object palette displays a Field tab and a Submit tab as shown in Figure 1.

Figure 1. Object palette for a button with a Control Type of Submit

The Submit tab (figure 2) allows you to control the information sent from the Intelligent Document to the server. Do you want to send just the XML field data? Do you need to send the XML data file as well as the associated schema?

Figure 2. Submit panel options

Note in figure 2, there are four possible options:

1. XML Data Package (XDP) — Allows you to send the document and its components as an XML package
2. PDF — Submits the PDF template along with any filled-in data. Note: Submitting PDF will work if you have Adobe Acrobat® software installed, or if your PDF file has had its functionality extended using Adobe LiveCycle Reader Extensions software
3. XML Data (XML) — Submits only the XML form data
4. URL-encoded Data (HTTP post) — Submits your form data in a format used by HTML forms

When you select XML Data Package (XDP), you can also specify the items to include in the package. These options include:

• Annotations
• Digital signature
• PDF
• Template

Note: A full description of all options is available in Adobe LiveCycle Designer online Help documentation.

The Other box enables you to specify other elements of the XDP to submit, such as XML schema or XMP metadata. The following chart lists some of the XML structures you might use. Any XML node can be specified in the Other field.

If you do not specify any of these Includeoptions, the submission will include XML form data, a reference to the location of the PDF file, and the action associated with the Submit button as seen in figure 3.

Figure 3. Example of submit XDP with no options selected

Additionally, you can select XML Source view and edit the <submit action directly. Attributes associated with <submit include:

• embedPDF — Either 0 or 1. If 1 is selected, the PDF file is embedded as a Base-64 encoded chunk.
• format — Values include xdp, xfd, formdata, xml, or pdf.
• id — This would be the XML ID of the submission.
• lock — Either 0 or 1. If 1, the content is restricted from edit.
• target — This is the URL for submission.
• textEncoding — This is the encoding. Default is UTF-8.
• use — Invokes a prototype. The value of this property is a "#" character followed by the prototype's identifier.
• xdpContent — This is where the XML structures for inclusion in an XDP submission are specified. Any tag specified is submitted to the server. If you specify "*", all elements are submitted.

So, an example <submit that included the form template, the PDF file, and annotations would be:

<event activity="click">
  <submit textEncoding="UTF-8"
  xdpContent="pdf datasets xfdf template"
  target="http://localhost:9080/MortgageApplication/EchoMe"
  embedPDF="1"/>
</event>

Included in the Using Adobe Designer 6.0 with IBM® WebSphere Studio tutorial is an example echo data servlet that allows you to experiment with the Submit function. This servlet echoes the XML packet information you submit to the server back to the local client for testing.
Example: Using the Mortgage application from this tutorial, we bind to the schema (mortgage.xsd). Then we select XDP for submission, and include Annotations, Template, PDF, and xmlschema (figure 4). In this example, we are running IBM WebSphere Studio Application Developer to host the sample servlet.

Figure 4. Example XDP submission

The output of this sample submission would be similar to figure 5. See the full XDP submission.

Figure 5. Example XDP submission elements

If you'd like to provide feedback on this tip or if you have questions, send e-mail to Lori.