XMLMill and existing documents

Description

XMLMill can change existing documents in two ways:

An existing document contains acrofields that can be filled by XMLMill
An existing document can be stamped using regular ml: elements.

Complete Acrofields of an existing PDF document

As of this version you can complete Acrofields of an existing PDF document, using this PDF document as a template. This has two big advantages:

You can design documents in a PDF editor (for example Acrobat Professional), eliminating cumbersome 'design' of the PDF document using ml:/xsl elements.
The speed of generating documents can be increased considerably by using an existing PDF document as a 'template', thanks to the caching technique used by XMLMill.

A template pdf document is in fact a PDF file with an AcroForm.

It is not possible to encrypt or digitally sign a generated PDF document based on a template. This will be solved in the next version.

The following steps are needed in order to use this functionality:

Make a new or modify an existing PDF document so it includes the so-called Acrofields (check your PDF-editor for more information).
Define an .xml document (as you have done before - nothing new).
Define a .xsl document containing the Acroform and acrofield elements (see below for more information).
Generate the document.

For a complete example please check the Element_acrofield_FormFieldsEnumerator-form-only.mill example in the samples/mill/ directory contained in the download.

Make a new or modify an existing PDF document

In case you already have an existing document with Acofields there is a good chance you can use it without any mofification.

In case you still have to make the PDF document you can do so by using one of the existing PDF-editors (check the internet for such applications).

The PDF document should preferably be of version 1.3 or 1.4 (higher version might have an internal PDF structure which XMLMill cannot read (yet).

The Acrofields should not be defined as fully qualified names. Although XMLMill can perfectly handle these names, the fields are shown empty in Acrobat Reader (although some other readers do show the fields correctly).

Mark all Acrofields immediately as read-only.

Please read the Appendix: Adding Acrofields to a PDF document with Acrobat Professional 8 chapter for more information on how to do this in Acrobat Professional 8.

Define an xml structure

Define an xml-structure that will contain the content of the fields, for example:

[001] <data>
[002]     <customerID>KL-123458</customerID>
[003]     <invoicenumber>#2007-21-01-589</invoicenumber>
[004]     ...
[005] <data>

Preferably use the same names for the elements and for the acrofields in the PDF document, for example:

Define an xsl document

In order to use a pdf document as a template following needs to be done:

Define the location of the PDF document acting as 'template'.
Define the content of the acrofields.

Define the location of the 'template'.

The ml:document element has been extended with 2 new attributes:

Attribute: `template`

`Value:`	<name>
`Initial:`	an empty name
`Applies to:`	ml:document
`Inherited:`	No, a value is required

Description:

The template attribute defines the location of the PDF document that will act as 'template'.

Values have the following meaning:


				<name>

This value indicates the name (and location) of the PDF document (acting as 'template') to use.

Example:

[001] <ml:document 
      template="file:pdftemplates/FormFieldsEnumerator-final-1.3.pdf" 
      template-in-memory="on" 
      ...>

Attribute: `template-in-memory`

`Value:`	on \|off \| true \| false
`Initial:`	off
`Applies to:`	ml:document
`Inherited:`	No, a value is required

Description:

The template-in-memory attribute defines whether the template, after it has been parsed, must be kept in memory so a second reading of the document can be avoided at the moment of generating the new document based on this template.

[001] <ml:document 
      template="file:pdftemplates/FormFieldsEnumerator-final-1.3.pdf" 
      template-in-memory="on" 
      ...>

This will not prevent that generating multiple documents with the same .xsl document the 'template' PDF document will each time be parsed again!

To increase speed dramatically you'll need to have the template read upfront when configuring XMLMill. Check the XMLMill Configuration chapter for more information.

Define the content of the acrofields.

In order to define the content of the template's acrofields two new elements have been defined:

Element: `ml:acroform`

The ml:acroform element just acts as a container element for the ml:acrofield elements.

[001] 
[002] <ml:acroform>
[003]   <ml:acrofield ...</ml:acrofield>
[004]   ...
[005] </ml:acroform>

Element: `ml:acrofield`

The ml:acofield element defines the content of a field contained in the PDF 'template' document.

[001] <ml:acroform>
[002]   <ml:acrofield name='InvoiceNumber'><xsl:value-of 
        select='data/invoicenumber' readonly='on'/> </ml:acrofield>
[004]   <ml:acrofield name='InvoiceDate'><xsl:value-of select='data/invoicedate' 
        readonly='on'/></ml:acrofield>
[006]   ...
[007] </ml:acroform>

The name attribute defines the field to be filled (this is the field's name as defined in the PDF 'template' document).

The readonly defines if the field must be marked as readonly in the document to be generated.

Generate the document

When the document is generated following is done:

The 'template' document is parsed and so XMLMill knows which Acrofields exists in the template.
A line is written in the log file showing the names of the Acrofields detected.
The original template document is written in a new document and the fields are updated with the values as defined in the .xsl document using the 'incremental update' technology.

Below you'll find an example of the line in the log file:

[001] DEBUG [main] Start reading template file:  
      c:/templates/FormFieldsEnumerator.pdf
[003] DEBUG [main] Acrofields: Button, CheckBox1, CheckBox2, TextBox1, TextBox2, 
      
[005] DEBUG [main] End reading template file:  (491 elapsed 
      (milliseconds))

Be sure that the loglevel is set to DEBUG.

During the parsing of the template some errors can occur:

Stamp the page(s) of an existing PDF document

As of this version the regular ml: elements can be used to 'stamp' an existing PDF document. This way new information can be added on a document existing pages.

It is not possible with this version to add new pages to an existing document.

The .xsl/.mill document should refer to an existing PDF document.

For a complete example please check the Element_acrofield_FormFieldsEnumerator-stamp-only.mill example in the samples/mill/ directory contained in the download.

Refer to an existing PDF document

In order to use the pdf document as a template following needs to be done:

Define the location of the PDF document acting as 'template'.
Use the regular ml: elements to 'stamp' the page(s).

Define the location of the 'template'.

The ml:document element has been extended with 2 new attributes:

Attribute: `template`

`Value:`	<name>
`Initial:`	an empty name
`Applies to:`	ml:document
`Inherited:`	No, a value is required

Description:

The template attribute defines the location of the PDF document that will act as 'template'.

Values have the following meaning:


				<name>

This value indicates the name (and location) of the PDF document (acting as 'template') to use.

Example:

[001] 
[002] <ml:document 
      template="file:pdftemplates/FormFieldsEnumerator-final-1.3.pdf" 
      template-in-memory="on" ...>

Attribute: `template-in-memory`

`Value:`	on \|off \| true \| false
`Initial:`	off
`Applies to:`	ml:document
`Inherited:`	No, a value is required

Description:

[001] 
[002] <ml:document 
      template="file:pdftemplates/FormFieldsEnumerator-final-1.3.pdf" 
      template-in-memory="on" ...>

This will not prevent that generating multiple documents with the same .xsl document the 'template' PDF document will each time be parsed again!

To increase speed dramatically you'll need to have the template read upfront when configuring XMLMill. Check the XMLMill Configuration chapter for more information.

Complete Acrofields and Stamp the page(s) of an existing PDF document

XMLMill can also fill the acrofields of a PDF document and at the same time stamp its' pages.

To do this the ml:acroform and other ml: elements are combined in one .xsl/.mill document

For more information please check the previous two sections Complete Acrofields of an existing PDF document and Stamp the page(s) of an existing PDF document.

For a complete example please check the Element_acrofield_FormFieldsEnumerator-form-and-stamp.mill example in the samples/mill/ directory contained in the download.

XMLMill User Guide