Web-based applications that enable a user to fill in interactive
forms require the data to be submitted back to the server. Using
the Forms service, you can retrieve the data that the user entered
into an interactive form. After you retrieve the data, you can process
the data to meet your business requirements. For example, you can
store the data in a database, send the data to another application,
send the data to another service, merge the data in a form design,
display the data in a web browser, and so on.
Form data is submitted to the Forms service as either XML or
PDF data, which is an option that is set in Designer. A form that
is submitted as XML enables you to extract individual field data
values. That is, you can extract the value of each form field that
the user entered into the form. A form that is submitted as PDF
data is binary data, not XML data. You can save the form as a PDF
file, or send the form to another service. If you want to extract
data from a form submitted as XML and then use the form data to
create a PDF document, invoke another LiveCycle operation.
(See Creating PDF Documents with Submitted XML Data)
The following diagram shows data being submitted to a Java Servlet
named HandleData from an interactive form displayed
in a web browser.
The following table explains the steps in the diagram.
Step
|
Description
|
1
|
A user fills in an interactive form and
clicks the form’s Submit button.
|
2
|
Data is submitted to the HandleData Java
Servlet as XML data.
|
3
|
The HandleData Java Servlet
contains application logic to retrieve the data.
|
Handling submitted XML dataWhen form data is submitted as XML,
you can retrieve XML data that represents the submitted data. All
form fields appear as nodes in an XML schema. The node values correspond
to the values that the user filled in. Consider a loan form where
each field in the form appears as a node within the XML data. The
value of each node corresponds to the value that a user fills in.
Assume a user fills the loan form with data shown in the following
form.
The following illustration shows corresponding XML data that
is retrieved by using the Forms service Client API.
Remarque : The form design must be configured correctly
in Designer for data to be submitted as XML data. To properly configure
the form design to submit XML data, ensure that the Submit button
that is located on the form design is set to submit XML data. For
information about setting the Submit button to submit XML data, see LiveCycle Designer 11 Help.
Handling submitted PDF dataConsider a web application that
invokes the Forms service. After the Forms service renders an interactive
PDF form to a client web browser, the user fills in the form and submits
it back as PDF data. When the Forms service receives the PDF data,
it can send the PDF data to another service or save it as a PDF
file. The following diagram shows the application’s logic flow.
The following table describes the steps in this diagram.
Step
|
Description
|
1
|
A web page contains a link that accesses
a Java Servlet that invokes the Forms service.
|
2
|
The Forms service renders an interactive
PDF form to the client web browser.
|
3
|
The user fills in an interactive form and
clicks a submit button. The form is submitted back to the Forms
service as PDF data. This option is set in Designer.
|
4
|
The Forms service saves the PDF data as
a PDF file.
|
Handling submitted Guide (deprecated) dataThe Flash Player security specifies that a Flash application
can only submit data to the URL location (domain) from which it
was served. When using the Forms service to render a guide, this
is not the case. The URL location from where a Guide (deprecated) is served and
the URL location to where the form data is posted is different (that
is typical Forms service functionality). For Flash Player to permit data
to be posted to a different URL, a crossdomain.xml file must be
available. Otherwise, form data cannot be posted to a different
URL.
Handling submitted URL UTF-16 dataIf form data is submitted as URL UTF-16 data, the client
computer requires Adobe Reader or Acrobat 8.1 or later. Also if
the form design contains a submit button that has URL-encoded Data
(HTTP Post) and the data encoding option is UTF-16, the form design
must be modified in a text editor such as Notepad. You can set the
encoding option to either UTF-16LE or UTF-16BE for
the submit button. Designer does not provide this functionality.
Summary of stepsTo
handle submitted forms, perform the following tasks:
Include project files.
Create a Forms Client API object.
Retrieve form data.
Determine if the form submission contains file attachments.
Process the submitted data.
Include project filesInclude necessary files into your development
project. If you are creating a client application using Java, include
the necessary JAR files. If you are using web services, ensure that
you include the proxy files.
Create a Forms Client API objectBefore you can programmatically
perform a Forms service Client API operation, you must create a
Forms service client. If you are using the Java API, create a FormsServiceClient object.
If you are using the Forms web service API, create a FormsService object.
Retrieve form dataTo
retrieve submitted form data, you invoke the FormsServiceClient object’s processFormSubmission method.
When invoking this method, you have to specify the submitted form’s
content type. When data is submitted from a client web browser to
the Forms service, it can be submitted as either XML or PDF data.
To retrieve the data that is entered into form fields, the data
can be submitted as XML data.
You can also retrieve form fields
from a form submitted as PDF data by setting the following run-time
options:
Pass the following value to the processFormSubmission method
as the content type parameter: CONTENT_TYPE=application/pdf.
Set the RenderOptionsSpec object’s PDFToXDP value
to true
Set the RenderOptionsSpec object’s ExportDataFormat value
to XMLData
You specify the content
type of the submitted form when you invoke the processFormSubmission method.
The following list specifies applicable content type values:
text/xml: Represents the content type to use when
a PDF form submits form data as XML.
application/x-www-form-urlencoded: Represents the content
type to use when an HTML form submits data as XML.
application/pdf: Represents the content type to use
when a PDF form submits data as PDF.
Remarque : You
will notice that there are three corresponding quick starts associated
with the Handling Submitted Forms section. The Handling PDF forms submitted
as PDF using the Java API quick start demonstrates how to handle submitted
PDF data. The content type specified in this quick start is application/pdf.
The Handling PDF forms submitted as XML using the Java API quick
start demonstrates how to handle submitted XML data that is submitted
from a PDF form. The content type specified in this quick start
is text/xml. Likewise, the Handling HTML forms
submitted as XML using the Java API quick start demonstrates how
to handle submitted XML data that is submitted from an HTML form.
The content type specified in this quick start is application/x-www-form-urlencoded.
You
retrieve form data that was posted to the Forms service and determine its
processing state. That is, when data is submitted to the Forms service,
it does not necessarily mean that the Forms service is finished
processing the data and the data is ready to be processed. For example,
data can be submitted to the Forms service so that a calculation
can be performed. When the calculation is complete, the form is
rendered back to the user with the calculation results displayed.
Before you process submitted data, it is recommended that you determine
whether the Forms service has finished processing the data.
The
Forms service returns the following values to indicate whether it
has finished processing the data:
0 (Submit): Submitted
data is ready to be processed.
1 (Calculate): The Forms service performed a calculation operation
on the data and the results must be rendered back to the user.
2 (Validate): The Forms service validated form data
and the results must be rendered back to the user.
3 (Next): The current page has changed with results
that must be written to the client application.
4 (Previous): The current page has changed with results that
must be written to the client application.
Determine if the form submission contains file attachmentsForms
submitted to the Forms service can contain file attachments. For example,
using Acrobat’s built-in attachment pane, a user can select file
attachments to submit along with the form. As well, a user can also
select file attachments using an HTML toolbar that is rendered with
an HTML file.
After you determine if a form contains file
attachments, you can process the data. For example, you can save
the file attachment to the local file system.
Remarque : The
form must be submitted as PDF data in order to retrieve file attachments.
If the form is submitted as XML data, file attachments are not submitted.
Process the submitted dataDepending on the content type of the
submitted data, you can extract individual form field values from
the submitted XML data or save the submitted PDF data as a PDF file
(or send it to another service). To extract individual form fields,
convert submitted XML data to an XML data source and then retrieve
XML data source values by using org.w3c.dom classes.
Handle submitted forms using the Java APIHandle a submitted form by using the Forms API (Java):
Include project files
Include client JAR files,
such as adobe-forms-client.jar, in your Java project’s class path.
Create a Forms Client API object
Retrieve form data
To retrieve form data that
was posted to a Java Servlet, create a com.adobe.idp.Document object
by using its constructor and invoking the javax.servlet.http.HttpServletResponse object’s getInputStream method
from within the constructor.
Create a RenderOptionsSpec object by using
its constructor. Set the locale value by invoking the RenderOptionsSpec object’s setLocale method
and passing a string value that specifies the locale value.
Remarque : You can instruct the Forms service to create XDP
or XML data from submitted PDF content by invoking the RenderOptionsSpec object’s setPDF2XDP method
and passing true and also calling setXMLData and
passing true. You can then invoke the FormsResult object’s getOutputXML method
to retrieve the XML data that corresponds to the XDP/XML data. (The FormsResult object
is returned by the processFormSubmission method, which is explained in the next sub-step.)
Invoke the FormsServiceClient object’s processFormSubmission method
and pass the following values:
The com.adobe.idp.Document object
that contains the form data.
A string value that specifies environment variables including
all relevant HTTP headers. Specify the content type to handle. To
handle XML data, specify the following string value for this parameter: CONTENT_TYPE=text/xml.
To handle PDF data, specify the following string value for this
parameter: CONTENT_TYPE=application/pdf.
A string value that specifies the HTTP_USER_AGENT header
value, for example, .Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; .NET CLR 1.1.4322).
This parameter value is optional.
A RenderOptionsSpec object that stores run-time
options.
The processFormSubmission method returns
a FormsResult object containing the results of
the form submission.
Determine whether the Forms service is finished processing
the form data by invoking the FormsResult object’s getAction method.
If this method returns the value 0, the data is
ready to be processed.
Determine if the form submission contains file attachments
Invoke the FormsResult object’s getAttachments method.
This method returns a java.util.List object that
contains files that were submitted with the form.
Iterate through the java.util.List object
to determine if there are file attachments. If there are file attachments,
each element is a com.adobe.idp.Document instance.
You can save the file attachments by invoking the com.adobe.idp.Document object’s copyToFile method
and passing a java.io.File object.
Remarque : This step is only applicable if the form is submitted
as PDF.
Process the submitted data
If the data content
type is application/vnd.adobe.xdp+xml or text/xml,
create application logic to retrieve XML data values.
Create a com.adobe.idp.Document object by
invoking the FormsResult object’s getOutputContent method.
Create a java.io.InputStream object by invoking
the java.io.DataInputStream constructor and passing
the com.adobe.idp.Document object.
Create an org.w3c.dom.DocumentBuilderFactory object
by calling the static org.w3c.dom.DocumentBuilderFactory object’s newInstance method.
Create an org.w3c.dom.DocumentBuilder object
by invoking the org.w3c.dom.DocumentBuilderFactory object’s newDocumentBuilder method.
Create an org.w3c.dom.Document object by
invoking the org.w3c.dom.DocumentBuilder object’s parse method
and passing the java.io.InputStream object.
Retrieve the value of each node within the XML document.
One way to accomplish this task is to create a custom method that
accepts two parameters: the org.w3c.dom.Document object
and the name of the node whose value you want to retrieve. This method
returns a string value representing the value of the node. In the code
example that follows this process, this custom method is called getNodeText.
The body of this method is shown.
If the data content type is application/pdf,
create application logic to save the submitted PDF data as a PDF
file.
Create a com.adobe.idp.Document object
by invoking the FormsResult object’s getOutputContent method.
Create a java.io.File object by using its
public constructor. Be sure to specify PDF as the file name extension.
Populate the PDF file by invoking the com.adobe.idp.Document object’s copyToFile method
and passing the java.io.File object.
Handle submitted PDF data using the web service APIHandle a submitted form by using the Forms API (web service):
Include project files
Create a Forms Client API object
Create a FormsService object
and set authentication values.
Retrieve form data
To retrieve form data that
was posted to a Java Servlet, create a BLOB object
by using its constructor.
Create a java.io.InputStream object by invoking
the javax.servlet.http.HttpServletResponse object’s getInputStream method.
Create a java.io.ByteArrayOutputStream object
by using its constructor and passing the length of the java.io.InputStream object.
Copy the contents of the java.io.InputStream object
into the java.io.ByteArrayOutputStream object.
Create a byte array by invoking the java.io.ByteArrayOutputStream object’s toByteArray method.
Populate the BLOB object by invoking its setBinaryData method
and passing the byte array as an argument.
Create a RenderOptionsSpec object by using
its constructor. Set the locale value by invoking the RenderOptionsSpec object’s setLocale method
and passing a string value that specifies the locale value.
Invoke the FormsService object’s processFormSubmission method
and pass the following values:
The BLOB object
that contains the form data.
A string value that specifies environment variables including
all relevant HTTP headers. Specify the content type to handle. To
handle XML data, specify the following string value for this parameter: CONTENT_TYPE=text/xml.
To handle PDF data, specify the following string value for this
parameter: CONTENT_TYPE=application/pdf.
A string value that specifies the HTTP_USER_AGENT header
value; for example, Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; .NET CLR 1.1.4322).
A RenderOptionsSpec object that stores run-time
options.
An empty BLOBHolder object that is populated
by the method.
An empty javax.xml.rpc.holders.StringHolder object
that is populated by the method.
An empty BLOBHolder object that is populated
by the method.
An empty BLOBHolder object that is populated
by the method.
An empty javax.xml.rpc.holders.ShortHolder object
that is populated by the method.
An empty MyArrayOf_xsd_anyTypeHolder object
that is populated by the method. This parameter is used to store
file attachments that are submitted along with the form.
An empty FormsResultHolder object that is
populated by the method with the form that is submitted.
The processFormSubmission method populates
the FormsResultHolder parameter with the results
of the form submission.
Determine whether the Forms service is finished processing
the form data by invoking the FormsResult object’s getAction method.
If this method returns the value 0, the form data
is ready to be processed. You can get a FormsResult object
by getting the value of the FormsResultHolder object’s value data
member.
Determine if the form submission contains file attachments
Get
the value of the MyArrayOf_xsd_anyTypeHolder object’s value data
member (the MyArrayOf_xsd_anyTypeHolder object
was passed to the processFormSubmission method). This
data member returns an array of Objects. Each element
within the Object array is an Object that
corresponds to the files that were submitted along with the form.
You can get each element within the array and cast it to a BLOB object.
Process the submitted data
If the data content
type is application/vnd.adobe.xdp+xml or text/xml,
create application logic to retrieve XML data values.
Create a BLOB object by invoking the FormsResult object’s getOutputContent method.
Create a byte array by invoking the BLOB object’s getBinaryData method.
Create a java.io.InputStream object by invoking
the java.io.ByteArrayInputStream constructor and
passing the byte array.
Create an org.w3c.dom.DocumentBuilderFactory object
by calling the static org.w3c.dom.DocumentBuilderFactory object’s newInstance method.
Create an org.w3c.dom.DocumentBuilder object
by invoking the org.w3c.dom.DocumentBuilderFactory object’s newDocumentBuilder method.
Create an org.w3c.dom.Document object by
invoking the org.w3c.dom.DocumentBuilder object’s parse method
and passing the java.io.InputStream object.
Retrieve the value of each node within the XML document.
One way to accomplish this task is to create a custom method that
accepts two parameters: the org.w3c.dom.Document object
and the name of the node whose value you want to retrieve. This method
returns a string value representing the value of the node. In the code
example that follows this process, this custom method is called getNodeText.
The body of this method is shown.
If the data content type is application/pdf,
create application logic to save the submitted PDF data as a PDF
file.
Create a BLOB object by invoking the FormsResult object’s getOutputContent method.
Create a byte array by invoking the BLOB object’s getBinaryData method.
Create a java.io.File object by using its
public constructor. Be sure to specify PDF as the file name extension.
Create a java.io.FileOutputStream object
by using its constructor and passing the java.io.File object.
Populate the PDF file by invoking the java.io.FileOutputStream object’s write method
and passing the byte array.
|
|
|