Package org.faceless.pdf2

Class 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 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

      • 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");
   DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
   DocumentBuilder db = factory.newDocumentBuilder();
   Document doc = db.parse(new InputSource(in));
        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)

      • 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 benefits of changing it minimal. Forgive our 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(in, 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()

      • putLiteral

        public void putLiteral​(String key,
                       String tokens)
        Put a literal token sequnce. For debugging
        Parameters:
        key - the key
        tokens - the token sequence, eg "true" or "/foo" or "[/Foo/Bar]". No refs, just direct objects.