org.faceless.pdf2
Class Form

java.lang.Object
  extended by 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
 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 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.
 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 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()

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.

 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)

toString

public String toString()


Copyright © 2001-2010 Big Faceless Organization