XSL-FO Designer for Apache FOP

bcl_716964462.htm

13. PDF interactive forms

Introduction

Starting with version 1.5 you can create PDF forms using J4L FO Designer (Suite edition), however this requires that you use our FOP server since the generation of PDF forms is not part of the XSL-FO standard.

You will find an introduction to the usage of and motivations for PDF forms at this page in our site.

Note the generation of forms requires the suite or enterprise license and the use of J4L FOP Server.

Form objects

The highlighted objects in the toolbar can be used for data entry:

  • Text fields.This object is also used in non-form PDF files to display data.
  • Combo boxes. This object is also used in non-form PDF files to display data.
  • Checkbox. This object can be used in forms only.
  • Button (to submit or reset a form). This object can be used in forms only.

Text fields and combo boxes are normally used to display data.  In order to activate them for data entry the "Input field" property must be set to yes.

Input fields have a green border in the designer.

Text field

Text fields can be used to allow free entry of data. The following properties are available for these kind of input fields:

  • Read only: It is possible to set the field to read only, this is useful to prefill fields which you later can read when the user has submitted the PDF form. The read only field can contain a user id which you would use to identity the form.
  • Is hidden field. If true the field will not be displayed in the PDF reader but the field is still contained in the PDF file.
  • Mandatory: the field must contain a value
  • Multiline: several lines of text can be entered in the field.
  • Max length: maximum number of characters that can be entered

The default value of the text field will be the constant one (see value property) or the one returned by the Xpath.

Combo box

This kind of fields offer a list of values the user can select. They behave in a similar way as text fields.

Checkbox

Checkboxes are input fields which can only contain the value true or false (selected or not selected).

Button

Button objects are used to execute actions. The actions available at this time are:

  • reset form to the default values.
  • submit form. In this case you have to enter the url in the "Submit to URL" field. This can be:

    Email address URL, for example:
    • mailto:receiver@company.com?Subject=My%20Order&body=bla
    • A web server HTTP URL, for example http://myserver/submit.

      The submit URL value can also be filled dynamically from the XML data using the Xpath.
  • The submission format, HTML, XML or PDF

Filling in the form

There are several ways to submit the forms:

  1. submitting to a web server (as PDF, HTML or XML)
  2. email (as PDF or XML)
  3. printing and sending paper
  4. sending the filled PDF file by any other means

The option (4 or partly 2) that requires you to save the filled form to a PDF file has a potential issue. If you use Adobe Reader you will get an error like this one "You cannot saved data typed into this form".

The reason for this is, Adobe Reader allows saving filled forms only if the forms has been created and digitally signed by Adobe tools. At this point you have some options:

  1. Buy Adobe LiveCycle reader extensions server which will add the signature to the form.
  2. Use Adobe standard to fill in the form (instead of the free adobe reader)
  3. or use another reader.
    there are several free PDF readers that will allow you to fill and save forms. One of them is Nitro PDF Reader

Form submission

The PDF form can be submitted in several ways:

  • to a web server using HTTP
  • by email
  • or saving the filled form to a PDF file and submitting by any other means.

There are several formats which can be used to receive the form data:


  • ·HTML, the data will be submitted to your web server (the URL you have specified) using the HTTP POST method. The body on the HTTP request will be something like this:

    FieldName1=value1&FieldName2=value2&...
  • XML. The format of the data when submitted using XML is:

<?xml version="1.0" encoding="UTF-8" standalone="no"?> <formData>

<fields>

<field name="fieldname1"><value>value1</value></field> <field name="fieldname2"><value>value2</value></field>

...

<fields>

</formData>

  • PDF. Submitting in PDF format requires you to have a reader that allows you to do that (see previous section), it has the advantage that the user can keep a copy of the same file she has submitted. The receiver of the submitted PDF can also display the received data in a user friendly way.

    In order for your application to extract the content of the submitted PDF you have 2 options:
    • Use our servlet which converts PDF to XML. The file J4LFOPServer.war file contains a servlet, once this file has been deployed to a web server you can reach our servlet in this URL:

      http://servername/J4LFOPServer/FieldExtractorServer

      This servlet accepts HTTP POST requests which contain the PDF as body of the request, and returns the XML file with the field values.

      It also accepts files to be uploaded using an HTML form using the parameter FORMMODE=ON, see example FormRead.html inside J4LFOPServer.war.
    • Or use our Java API to extract tha values of the fields. This example shows how to do it:

      import com.java4less.xreport.fop.FormValuesExtractor;
      ....

      FormValuesExtractor extractor=new FormValuesExtractor(); FileInputStream is=new FileInputStream("myform.pdf"); Hashtable fieldsTable=extractToTable(is);

      Enumeration enum=fieldsTable.keys(); while (enum.hasMoreElements()) {

      String key=(String) enum.nextElement(); System.out.println("Field "+key+"="+fieldsTable.get(key));

      }



Input form example

The order_form.xre example shows how the input fields can be used. The example contains one input field of each type, furthermore it shows how fields can be repeated in the detail area.

The example contains no submit button since it assumes the user will fill the form with a PDF reader that can save forms (see the Filling forms section) and submit the saved PDF by email. This example is an order form which:

  • Contains a read only field (customer number) which can be used as key for identifying the customer.
  • The address and city fields are prefilled with the customer data but the customer can change the delivery address by modifying the fields.
  • ·Contains a list of items the customer can order by just entering the quantity at selecting the color.
  • There is a multiline comments field at the bottom.

the screenshot shows how the PDF form has been filled and can be saved using Nitro PDF Reader:

As last step the filled forms has been received by the selling company and the values of the PDF can be extracted (see section Form submission). We include a simple HTML page inside J4LFOPServer.war which calls our form extractor server:

once submitted the server returns the form content as XML, note field names have a suffix ( _1 ,_2 ..) because fields in a detail section (like the items in a purchase order) can be repeated:




Form's internal structure


By default all input fields in a form will be stored as an list in the PDF form (Flat form). If you would use a PDF analizer tool, you would see the internal list of fields:


It is however possible to create a hierarchical structure for the field in the form. This can be achieved  by removing the Flat form flag in the report‘s properties.



After removing the flag the created form fields in the PDF will have the same internal strtucture as the report in the designer:




that is it will have a tree structure:
    • the form header fields will be in the first level
    • the areas will be a node in the tree
    • for each repetition of the area there will be a record node
    • finally for each record there will be list of form fields

The naming of the form input fields (also called terminal nodes) and areas/record (non-terminal nodes, because the have children) is as follows:
    • for form fields: <fieldname>_<GeneratedUniqueId>. For example: CustomerID_N10001
    • for areas: <level>_<areacounter>_<GeneratedUniqueId>_AREA. For example the first detail area after the report header will be named 1_1_N10001_AREA.
    • for records (area repetitions) : <level>_<areacounter>_<GeneratedUniqueRecordId>_RECORD. For example the first detail area repetition after the report header will be called 1_1_N10001_RECORD , the second repetition of the same area could be  1_1_N102B5_RECORD