Rendering Forms at the Client

Summary of steps
Render a form at the client using the Java API
Render a form at the client using the web service API

You can optimize the delivery of PDF content and improve the Forms service’s ability to handle network load by using the client-side rendering capability of Acrobat or Adobe Reader. This process is known as rendering a form at the client. To render a form at the client, the client device (typically a web browser) must use Acrobat 7.0 or Adobe Reader 7.0 or later.

Changes to a form resulting from server-side script execution is not reflected in a form that is rendered at the client unless the root subform contains the restoreState attribute that is set to auto. For more information about this attribute, see LiveCycle Designer 11 Help.

Note: For more information about the Forms service, see Services Reference for LiveCycle.

Summary of steps

To render a form at the client, perform the following tasks:

Include project files.
Create a Forms Client API object.
Set client rendering run-time options.
Render a form at the client.
Write the form to the client web browser.

Include project files

Include 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 object

Before 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.

Set client rendering run-time options

You must set the client rendering run-time option to render a form at the client by setting the RenderAtClient run-time option to true. This results in the form being delivered to the client device where it is rendered. If RenderAtClient is auto (the default value), the form design determines whether the form is rendered at the client. The form design must be a form design with a flowable layouyt.

An optional run-time option that you may set is the SeedPDF option. The SeedPDF option combines the PDF container (seed PDF document) with the form design and the XML data. Both the form design and the XML data are delivered to Acrobat or Adobe Reader, where the form is rendered. The SeedPDF option can be used when the client computer does not have fonts that are used in the form, such as when an end user is not licensed to use a font that the form owner is licensed to use.

You can use Designer to create a simple dynamic PDF file for use as a seed PDF file. The following steps are required to perform this task:

Determine whether you need to embed any fonts within the seed PDF file. The seed PDF file will need to contain additional fonts required by the form being rendered. When embedding fonts into the seed PDF file, ensure that you are not violating any font licensing agreements. In Designer, you can determine whether you can legally embed fonts. Upon saving, if there are fonts you cannot embed into the form, Designer displays a message listing the fonts you cannot embed. This message is not displayed in Designer for static PDF documents.
If you are creating the seed PDF file in Designer, it is recommended that, at a minimum, you add a text field that contains a message. The message should be directed at users of earlier versions of Adobe Reader stating that they need Acrobat 7.0 or later or Adobe Reader 7.0 or later to view the document.
Save the seed PDF file as a dynamic PDF file with the PDF file name extension.

Note: You do not need to define the seed PDF run-time option to render a form on the client. If you do not specify a seed PDF, the Forms service creates a shell pdf which will not contain COS objects but will contain a PDF wrapper with the actual XDP content embedded inside. The steps in this section do not set the seed PDF run-time option. For information about COS objects, see the Adobe PDF Reference guide.

Render a form at the client

To render a form at the client, you must ensure that the client rendering run-time options are included in your application logic to render a form.

Write the form data stream to the client web browser

The Forms service creates a form data stream that you must write to the client web browser. When written to the client web browser, the form is rendered by Acrobat 7.0 or Adobe Reader 7.0 or later, and is visible to the user.

Render a form at the client using the Java API

Render a form at the client 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
- Create a ServiceClientFactory object that contains connection properties.
- Create an FormsServiceClient object by using its constructor and passing the ServiceClientFactory object.
Set client rendering run-time options
- Create a PDFFormRenderSpec object by using its constructor.
- Set the RenderAtClient run-time option by invoking the PDFFormRenderSpec object’s setRenderAtClient method and passing the enum value RenderAtClient.Yes.
Render a form at the client

Invoke the FormsServiceClient object’s renderPDFForm method and pass the following values:
- A string value that specifies the form design name, including the file name extension. If you reference a form design that is part of a LiveCycle application, ensure that you specify the complete path, such as Applications/FormsApplication/1.0/FormsFolder/Loan.xdp.
- A com.adobe.idp.Document object that contains data to merge with the form. If you do not want to merge data, pass an empty com.adobe.idp.Document object.
- A PDFFormRenderSpec object that stores run-time options required to render a form at the client.
- A URLSpec object that contains URI values that are required by the Forms service to render a form.
- A java.util.HashMap object that stores file attachments. This is an optional parameter and you can specify null if you do not want to attach files to the form.
The renderPDFForm method returns a FormsResult object that contains a form data stream that must be written to the client web browser.
Write the form data stream to the client web browser
- Create a com.adobe.idp.Document object by invoking the FormsResult object ‘s getOutputContent method.
- Get the content type of the com.adobe.idp.Document object by invoking its getContentType method.
- Set the javax.servlet.http.HttpServletResponse object’s content type by invoking its setContentType method and passing the content type of the com.adobe.idp.Document object.
- Create a javax.servlet.ServletOutputStream object used to write the form data stream to the client web browser by invoking the javax.servlet.http.HttpServletResponse object’s getOutputStream method.
- Create a java.io.InputStream object by invoking the com.adobe.idp.Document object’s getInputStream method.
- Create a byte array and populate it with the form data stream by invoking the InputStream object’s read method and passing the byte array as an argument.
- Invoke the javax.servlet.ServletOutputStream object’s write method to send the form data stream to the client web browser. Pass the byte array to the write method.

Render a form at the client using the web service API

Render a form at the client by using the Forms API (web service):

Include project files
- Create Java proxy classes that consume the Forms service WSDL.
- Include the Java proxy classes into your class path.
Create a Forms Client API object

Create a FormsService object and set authentication values.
Set client rendering run-time options
- Create a PDFFormRenderSpec object by using its constructor.
- Set the RenderAtClient run-time option by invoking the PDFFormRenderSpec object’s setRenderAtClient method and passing the string value RenderAtClient.Yes.
Render a form at the client

Invoke the FormsService object’s renderPDFForm method and pass the following values:
- A string value that specifies the form design name, including the file name extension. If you reference a form design that is part of a LiveCycle application, ensure that you specify the complete path, such as Applications/FormsApplication/1.0/FormsFolder/Loan.xdp.
- A BLOB object that contains data to merge with the form. If you do not want to merge data, pass null. (See Prepopulating Forms with Flowable Layouts.)
- A PDFFormRenderSpec object that stores run-time options required to render a form at the client.
- A URLSpec object that contains URI values that are required by the Forms service. (See Specify URI values.)
- A java.util.HashMap object that stores file attachments. This is an optional parameter and you can specify null if you do not want to attach files to the form. (See Attach files to the form.)
- An empty com.adobe.idp.services.holders.BLOBHolder object that is populated by the method. This parameter is used to store the rendered PDF form.
- An empty javax.xml.rpc.holders.LongHolder object that is populated by the method. (This argument will store the number of pages in the form).
- An empty javax.xml.rpc.holders.StringHolder object that is populated by the method. (This argument will store the locale value).
- An empty com.adobe.idp.services.holders.FormsResultHolder object that will contain the results of this operation.
The renderPDFForm method populates the com.adobe.idp.services.holders.FormsResultHolder object that is passed as the last argument value with a form data stream that must be written to the client web browser.
Write the form data stream to the client web browser
- Create a FormResult object by getting the value of the com.adobe.idp.services.holders.FormsResultHolder object’s value data member.
- Create a BLOB object that contains form data by invoking the FormsResult object’s getOutputContent method.
- Get the content type of the BLOB object by invoking its getContentType method.
- Set the javax.servlet.http.HttpServletResponse object’s content type by invoking its setContentType method and passing the content type of the BLOB object.
- Create a javax.servlet.ServletOutputStream object used to write the form data stream to the client web browser by invoking the javax.servlet.http.HttpServletResponse object’s getOutputStream method.
- Create a byte array and populate it by invoking the BLOB object’s getBinaryData method. This task assigns the content of the FormsResult object to the byte array.
- Invoke the javax.servlet.http.HttpServletResponse object’s write method to send the form data stream to the client web browser. Pass the byte array to the write method.