|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.faceless.pdf2.Form
public final class Form
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.
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 |
---|
public PDF getPDF()
public Map getElements()
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.
Map
containing all the form elementspublic 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);
name
- the name of the form elementelement
- the element to add to the form
IllegalStateException
- if the element already exists in the formpublic FormElement getElement(String name)
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.
name
- the name of the form element
null
if it doesn't existpublic FormElement removeElement(String name)
FormElement element = form.getElements().remove(name);
name
- the name of the form element to remove
null
if it didn't existpublic void renameElement(String fromname, String toname)
IllegalArgumentException
is thrown. Since 2.0 the element keeps the same ordering in the form if possible.
fromname
- the original name of the form elementtoname
- the new name of the form element
IllegalArgumentException
- if the specified element does not existpublic void renameAllElements(String prefix, String suffix)
prefix
- the prefix to add to all element names - may be null
suffix
- the suffix to add to all element names - may be null
public void clear()
public String getName(FormElement element)
FormElement
, return the name by which
this element is stored in the form, or null
if
it doesn't exist in this form.
null
if it's not in the Formpublic void setBackgroundStyle(PDFStyle style)
WidgetAnnotation.setBackgroundStyle(org.faceless.pdf2.PDFStyle)
method in the WidgetAnnotation
class. The default is a white
background with a plain black border
style
- the default back style for new form elementsWidgetAnnotation.setBackgroundStyle(org.faceless.pdf2.PDFStyle)
public void setTextStyle(PDFStyle style)
style
- the default text style for new form elementsWidgetAnnotation.setTextStyle(org.faceless.pdf2.PDFStyle)
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.
FormElement.flatten()
,
PDFAnnotation.flatten()
public void removeXFA()
public InputStream getXFAElement(String packet)
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
.
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.
null
if no such section exists.setXFADatasets(java.lang.String)
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.
SAXException
- if dataset is not a valid XFA dataset object.getXFAElement(java.lang.String)
,
setXFAElement(java.lang.String, java.lang.String)
,
PDF.importFDF(org.faceless.pdf2.FDF)
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, newStreamResult
(out)); form.setXFAElement(element, out.toString());
packet
- the XFA section to update - "template", "datasets" or similar.data
- the data to set that packet to.
SAXException
- if section is "datasets" and data is not a valid XFA dataset object.getXFAElement(java.lang.String)
,
setXFADatasets(java.lang.String)
public String toString()
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |