org.faceless.pdf2

## Class Form

- java.lang.Object
- - org.faceless.pdf2.Form

- All Implemented Interfaces:
    Cloneable

      public final class Form
      extends Object

  The Form class represents the interactive Form that may be included as part of a PDF document. This form can be filled out by users and then eventually submitted for processing in the same way as an HTML form. Unlike HTML, a PDF document may only have one form.

  A form contains zero or more `FormElement` objects which you can access via the `getElements()` method. Each form element usually has one or more visual representation on the page - a `WidgetAnnotation`. These annotation can be accessed by the `FormElement.getAnnotations()` method. Each element in the form is stored under a name, which is used to reference the element and must be unique.

  The name may be a simple string, like `"Element1"`, or it may be a compound name, with fields separated with dots, for example `"Employee.Address.City"`. Simple and Compound names must not collide - for example, it would be illegal to have elements called "Country.Capital" and "Country" in the same document.

  > Note: In Acrobat 6.0 Adobe introduced an XML-based forms architecture called XFA, which is stored alongside the regular PDF form in the document. We believe this is the future of forms as far as Adobe is concerned, but as it effectively means you're storing all your form data twice, problems must occur. In our case, it means that in versions prior to 2.4.3 any attempts to update a field in an XFA-enabled form will not appear when that document is loaded into Acrobat. This was fixed in 2.4.3, but even that version still has the limitation that any attempts to modify the appearance of the form (by changing the style, adding or deleting fields) will not show up in Acrobat. Generally XFA forms are created in a product like Adobe InDesign which do a much better job of layout than the PDF library, so this is not too important.

  Note that using interactive forms requires the "Extended Edition" of the library - although the classes are supplied with the package an "Extended Edition" license must be purchased to activate this functionality.

  Since:
    1.1.13
  See Also:
    `PDF.getForm()`, `FormElement`

- - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addElement(String name, FormElement element)` Add an element to the form.
    `void` | `clear()` Remove all the elements from the form
    `void` | `flatten()` Flatten the entire form.
    `FormElement` | `getElement(String name)` Return the specified element from the form.
    `Map<String,FormElement>` | `getElements()` Return a map of all the elements in the form.
    `String` | `getName(FormElement element)` Given a `FormElement`, return the name by which this element is stored in the form, or `null` if it doesn't exist in this form.
    `PDF` | `getPDF()` Return the PDF associated with this form
    `InputStream` | `getXFAElement(String packet)` Returns the entire XFA stream, or the specified packet from the XFA form as an `InputStream`.
    `boolean` | `isXFA()` Return true if this Form is XFA enabled
    `void` | `rebuild()` Call the `FormElement.rebuild()` method on each element that requires it.
    `FormElement` | `removeElement(String name)` Remove the specified element from the form, if it exists.
    `void` | `removeXFA()` Removes the XFA elements from the form.
    `void` | `renameAllElements(String prefix, String suffix)` Rename all the elements in the form by adding a prefix and/or suffix to their names.
    `void` | `renameElement(String fromname, String toname)` Rename an element in the form.
    `void` | `setBackgroundStyle(PDFStyle style)` Set the default background style for all new elements added to the form.
    `void` | `setTextStyle(PDFStyle style)` Set the default text style for all new elements added to the form.
    `void` | `setXFADatasets(String datasets)` Sets the values in this form according to the supplied XFA "datasets" object.
    `void` | `setXFAElement(String packet, String data)` Override a section (or "packet") of the XFA data.
    `String` | `toString()`

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Method Detail

    - #### getPDF

          public PDF getPDF()

      Return the PDF associated with this form
      Since:
        2.8

    - #### getElements

          public Map<String,FormElement> getElements()

      Return a map of all the elements in the form. Each key in the Map is a `String` representing the name of the element, and the corresponding value is the `FormElement`. The returned map can be modified to add or remove elements from the form. The fields are stored in the order they are added to the Map.
      Returns:
        a `Map` containing all the form elements
      Since:
        2.0

    - #### addElement

          public void addElement(String name,
                                 FormElement element)

      Add an element to the form. Although a form can contain as many elements as you like, currently only a single signature with a state of `FormSignature.STATE_PENDING` can be added to each document. This method is identical to calling:

             form.getElements().put(name, element);

      Parameters:
        `name` - the name of the form element
        `element` - the element to add to the form
      Throws:
        `IllegalStateException` - if the element already exists in the form
      Since:
        1.1.13

    - #### getElement

          public FormElement getElement(String name)

      Return the specified element from the form. This method is almost identical to calling:

             FormElement element = form.getElements().get(name);

      The difference is that since 2.4.3, if an element with that name does not exist, each elements description (as returned by `FormElement.getDescription()`) is checked for a match. If exactly one element is found that matches, that element is returned. This is primarily an ease-of-use change to cope with the long field names required by the XFA architecture.
      Parameters:
        `name` - the name of the form element
      Returns:
        the specified element, or `null` if it doesn't exist
      Since:
        1.1.13

    - #### removeElement

          public FormElement removeElement(String name)

      Remove the specified element from the form, if it exists. This method is identical to calling

             FormElement element = form.getElements().remove(name);

      Parameters:
        `name` - the name of the form element to remove
      Returns:
        the removed element, or `null` if it didn't exist

    - #### renameElement

          public void renameElement(String fromname,
                                    String toname)

      Rename an element in the form. If the specified element name does not exist, an `IllegalArgumentException` is thrown. Since 2.0 the element keeps the same ordering in the form if possible.
      Parameters:
        `fromname` - the original name of the form element
        `toname` - the new name of the form element
      Throws:
        `IllegalArgumentException` - if the specified element does not exist
      Since:
        1.1.23

    - #### renameAllElements

          public void renameAllElements(String prefix,
                                        String suffix)

      Rename all the elements in the form by adding a prefix and/or suffix to their names. This method is useful when merging two copies of the same document together - as each field must have a unique name, this method can be used to rename the fields in the first copy to "Name1", "Phone1", in the second copy to "Name2", "Phone2" and so on. The elements keep the same ordering in the form.
      Parameters:
        `prefix` - the prefix to add to all element names - may be `null`
        `suffix` - the suffix to add to all element names - may be `null`
      Since:
        2.0

    - #### clear

          public void clear()

      Remove all the elements from the form
      Since:
        1.2.1

    - #### getName

          public String getName(FormElement element)

      Given a `FormElement`, return the name by which this element is stored in the form, or `null` if it doesn't exist in this form.
      Returns:
        the name of this element or `null` if it's not in the Form

    - #### setBackgroundStyle

          public void setBackgroundStyle(PDFStyle style)

      Set the default background style for all new elements added to the form. This can be overridden by the `WidgetAnnotation.setBackgroundStyle(org.faceless.pdf2.PDFStyle)` method in the `WidgetAnnotation` class. The default is a white background with a plain black border
      Parameters:
        `style` - the default back style for new form elements
      Since:
        1.1.23
      See Also:
        `WidgetAnnotation.setBackgroundStyle(org.faceless.pdf2.PDFStyle)`

    - #### setTextStyle

          public void setTextStyle(PDFStyle style)

      Set the default text style for all new elements added to the form. The style must include a font and a fill color to draw the text in. If a font size of 0 is specified, an appropriate size is chosen for each widget (the equivalent of "Auto" font size in Acrobat). Like background styles, this can be overridden for each widget. The default is black auto-sized Helvetica.
      Parameters:
        `style` - the default text style for new form elements
      Since:
        1.1.23
      See Also:
        `WidgetAnnotation.setTextStyle(org.faceless.pdf2.PDFStyle)`

    - #### flatten

          public void flatten()

      Flatten the entire form. Calls `FormElement.flatten()` on every element in the form and then delete it, so only the visible appearance of the form remains. Provided the user is not going to edit the values in the form, flattening a form before rendering is an extremely effective way to reduce the size of the document.

      Since 2.10.6 this also removes the XFA content of a PDF, by calling `removeXFA()`.

      Note that if you use JavaScript to format the field before display, this will not be taken into used when the field is flattened. Only the exact value returned by `FormElement.getValue()` will be used.

      Since:
        2.0
      See Also:
        `FormElement.flatten()`, `PDFAnnotation.flatten()`

    - #### isXFA

          public boolean isXFA()

      Return true if this Form is XFA enabled
      Since:
        2.17.1

    - #### removeXFA

          public void removeXFA()

      Removes the XFA elements from the form. This strips out the entire XFA structure from the PDF. The resulting document will probably work in Acrobat 6.0, but will no longer be maintainable by Adobe LiveCycle.
      Since:
        2.6.6

    - #### getXFAElement

          public InputStream getXFAElement(String packet)

      Returns the entire XFA stream, or the specified packet from the XFA form as an `InputStream`. For instance, to extract the `datasets` from the XFA form and convert it to a DOM tree you could do the following:

             InputStream in = pdf.getForm().getXFAElement("datasets");
             DOMParser parser = new DOMParser();
             parser.parse(new InputSource(in));
             Document doc = parser.getDocument();

      Note that prior to 2.6.9, the initial "xml" processing instruction wasn't included in the response for any packets other than `null`.
      Parameters:
        `packet` - the XFA section that should be returned, or `null` to return the entire XFA object as a single stream. Typical values would be `datasets`, `template` etc.
      Returns:
        the specified XFA section, or `null` if no such section exists.
      Since:
        2.6.6
      See Also:
        `setXFADatasets(java.lang.String)`

    - #### setXFADatasets

          public void setXFADatasets(String datasets)
                              throws SAXException

      Sets the values in this form according to the supplied XFA "datasets" object. The "datasets" parameter must consist of a value XFA datasets object, similar to the content returned by `form.getXFAElement("datasets")`.

      Note that the dynamic creation of repeating subforms which is a feature of XFA is not supported by this library. The fields you want to populate have to already exist in the PDF.

      Throws:
        `SAXException` - if dataset is not a valid XFA dataset object.
      Since:
        2.6.6
      See Also:
        `getXFAElement(java.lang.String)`, `setXFAElement(java.lang.String, java.lang.String)`, `PDF.importFDF(org.faceless.pdf2.FDF)`

    - #### setXFAElement

          public void setXFAElement(String packet,
                                    String data)
                             throws SAXException

      Override a section (or "packet") of the XFA data. This method should be used with extreme caution - it is intended for those with a good knowledge of XFA, and it's very easy to generate a document with this method that is invalid. For general updating of the XFA the `setXFADatasets() method` is more useful. Specifying "datasets" as the packet simply calls that method, otherwise no validation is performed on the supplied data and the PDF is simply updated with that string.

      We're aware `getXFAElement()` returns an `InputStream` and this takes a String. Ideally `getXFAElement` would have returned a `Reader`, but the API is set now and the beneifts of changing it minimal. Forgive out inconsistancy. Here's an example showing how to read and write an XFA packet, correctly allowing for encoding.

           import javax.xml.transform.*;
           import javax.xml.transform.stream.*;

           StreamSource in = new StreamSource(form.getXFAElement(element));
           StringWriter out = new StringWriter();
           TransformerFactory factory = TransformerFactory.newInstance();
           Transformer transformer = factory.newTransformer();
           transformer.transform(source, new StreamResult(out));
           form.setXFAElement(element, out.toString());

      Parameters:
        `packet` - the XFA section to update - "template", "datasets" or similar.
        `data` - the data to set that packet to.
      Throws:
        `SAXException` - if section is "datasets" and data is not a valid XFA dataset object.
      Since:
        2.7.9
      See Also:
        `getXFAElement(java.lang.String)`, `setXFADatasets(java.lang.String)`

    - #### rebuild

          public void rebuild()

      Call the `FormElement.rebuild()` method on each element that requires it. Generally not necessary to call directly, but can be called from the `EventDispatchThread` in the viewer to control when and on which thread these operations are run on
      Since:
        2.16

    - #### toString

          public String toString()

Copyright © 2001-2015 Big Faceless Organization