cfpdfform ColdFusion 9 Documentation

Description

Manipulates existing forms created in Adobe® Acrobat® and Adobe® LiveCycle® Designer. The following list describes some of the tasks you can perform with the cfpdfform tag:

Embed an interactive form created in Acrobat LiveCycle in a PDF document. You use the cfpdfform tag to embed the PDF form in a cfdocument tag.
Render an existing form created in Acrobat or LiveCycle. This includes prefilling fields from a database or an XML data file and processing form data from an HTTP post or PDF submission.
Extract or prefill values in stored PDF forms and save the output to a file or use it to update a data source.

History

ColdFusion 8: Added this tag.

Syntax

populate 
<cfpdfform 
    required 
    action = "populate" 
    source = "PDF file pathname|byte array" 
    optional 
    XMLdata = "XML object|XML string|XML data filename| 
        URL that returns XML data" 
    destination = "output file pathname" 
    overwrite = "yes|no"/ 
    fdf = "true|false> <!---New attribute that populates data in FDF format instead of      
    XML with subforms and params---> 
    fdfdata = "file name to be imported" <!--- New attribute populates data in FDF format 
    from the AcroForm---> 
read 
<cfpdfform 
    required 
    action = "read" 
    source = "pathname|byte array" 
        at least one of the following: 
    XMLdata = "variable name for XML data" 
    result = "structure containing form field values" 
    optional 
    overwrite = "yes|no"/> 
    fdfdata = "filename to be exported to"

Note: You can specify this tag’s attributes in an attributeCollection attribute whose value is a structure. Specify the structure name in the attributeCollection attribute and use the tag’s attribute names as structure keys.

Attributes

Attribute	Action	Req/Opt	Default	Description
`action`	NA	Required		Action to perform on the source: `populate` `read`
`destination`	`populate`	Optional	Write to browser	Pathname for the output file. You can specify an absolute pathname or a pathname relative to the context root. The file extension must be PDF or XDP. The file extension determines the format of the file. (The XDP format applies only to LiveCycle forms.) If you do not specify the destination, ColdFusion displays the form in the browser. Do not specify the destination when you embed a form in a PDF document.
`overwrite`	`populate` `read`	Optional	`no`	Specifies whether to overwrite the destination file (if `action="populate"`) or the data file (if `action="read"`): `yes` `no`
`overwriteData`	`populate`	Optional	`no`	Specifies whether to overwrite existing data in PDF form fields with data from the data source: `yes`: Overwrite existing data in the form fields with that from the data source. `no`: Retain existing data in form fields and populate only those fields without data. This attribute applies to data supplied from an XML data source and from the `cfpdfparam` and `cfpdfsubform` tags.
`result`	`read`	Optional (see Description)		ColdFusion structure that contains the form field values. Specify the `XMLdata` attribute or the `result` attribute; you can specify both.
`source`	`populate` `read`	Required		Pathname of the source PDF (absolute on-disk or in-memory path, or path relative to the context root) or byte array representing a PDF.
`XMLdata`	`populate` `read`	Optional (see Description)		Pathname for the XML data file. If `action="populate"`, the data from this file, XML object, or XML string populates the form fields. You can specify a pathname relative to the context root or a relative pathname. If `action="read"`, ColdFusion writes the data to the variable. Specify either the `XMLdata` attribute or the `result` attribute for the `read` action; you can specify both.
fdf	`populate`	Optional	false	If set to true, the system creates FDF with subforms and params instead of an XML
fdfdata	`populate` `read`	Optional		For populate, you specify the file name from where the FDF data is imported. For read, you specify the file name where the FDF data is exported.

Usage

ColdFusion supports two types of interactive forms: forms created in Adobe Acrobat 6.0 or earlier, and forms created in Adobe LiveCycle. In Adobe Acrobat Professional and Standard 7.0, Adobe introduced Adobe® LiveCycle® Designer for creating PDF forms. ColdFusion supports forms created in LiveCycle Designer 7.0 and later.

Forms created in Acrobat have a flat structure: a list of fields at the same level. Forms created in LiveCycle Designer are hierarchical, often composed of nested subforms. To map the data to the form field, you use cfpdfsubform tags to recreate the structure of the form in ColdFusion. For examples, see the Usage section of the cfpdfsubform tag, and “ Manipulating PDF Forms in ColdFusion in the Developing ColdFusion Applications.

populate action

Use the populate action to populate PDF form fields from the specified data file. You can specify a destination to write the output to a file or write the populated form directly to the browser. To display the interactive PDF form in the browser, do not specify a destination.

The following example shows how to populate a PDF form with an XML data file and display the completed form in a browser:

<cfpdfform source="c:\payslipTemplate.pdf" action="populate" XMLdata="c:\formdata.xml"/>

This example shows how to populate a PDF form with an XML data file and write the completed form to a new PDF file:

<!--- Specify an XML file to populate a PDF form. ---> 
<cfpdfform source="c:\payslipTemplate.pdf" 
    destination="c:\employeeid123.pdf" action="populate" 
    XMLdata="c:\formdata.xml"/>

Also, you can specify a URL that returns XML data. In the following example, "http://test1.com/xyz" returns XML content:

<cfpdfform source= "#sourcefile#" action="populate" XMLdata= 
    "http://test1.com/xyz" destination="#resultfile#" overwrite="true"/>

For forms created in Acrobat, you can write the output to a PDF file only. For forms created in LiveCycle, you have the option to write the output to an XML Data Package (XDP) file. An XDP file is an XML representation of a PDF file.

Note: Supplied values in form fields created in Acrobat or LiveCycle Designer are case sensitive. For example, if a check box in a form requires a “Yes” value, the value “yes” does not populate that field.

The file extension determines the file format: to save the output in XDP format, use an XDP extension in the destination filename:

<!--- Specify a an XML file to populate a PDF form. ---> 
<cfpdfform source="c:\payslipTemplate.pdf" 
    destination="c:\employeeid123.xdp" action="populate" 
    XMLdata="c:\formdata.xml"/>

You can use one or more cfpdfformparam tags within a cfpdfform tag to populate individual fields in a PDF form.

The following example shows how to populate an existing form created in Acrobat (payslipTemplate.pdf) and create a PDF form (employeeid123.pdf) with the employeeID and salary fields filled in:

<!--- This example shows how to populate two fields in a form created in Acrobat. ---> 
<cfpdfform source="c:\payslipTemplate.pdf" 
    destination="c:\employeeid123.pdf" action="populate"> 
        <cfpdfformparam name="employeeId" value="123"> 
        <cfpdfformparam name="salary" value="$85,000"> 
</cfpdfform>

ColdFusion requires that you reproduce the exact structure of the source PDF form to populate fields. To verify the structure of a PDF form in ColdFusion, use the read action of cfpdfform tag, and then use the cfdump tag to display the result structure. Use a cfpdfsubform tag for each level within the structure. For more information, see Manipulating PDF Forms in ColdFusion in the Developing ColdFusion Applications.

The following example shows how to populate a form created in LiveCycle. Many forms created from templates in LiveCycle contain a subform called form1. Use the cfpdfsubform tag to create a subform in ColdFusion.

<!--- This example shows how to populate two fields in a LiveCycle form.  
    ---> 
<cfpdfform source="c:\payslipTemplate.pdf"  
    destination="c:\employeeid123.pdf" action="populate"> 
    <cfpdfsubform name="form1"> 
        <cfpdfformparam name="employeeId" value="123"> 
        <cfpdfformparam name="salary" value="$85,000"> 
    </cfpdfsubform> 
</cfpdfform>

You can now import files in FDF format using the populate action. The following example shows how:

<cfpdfform source= "write_acrroform.pdf" action="populate" fdfdata="abc.fdf" destination="hello.pdf"> 
</cfpdfform>

If the fdf attribute for the populate action is set to true, it allows you to populate data in FDF format with subforms and params instead of XML, as shown in the following example:

<cfpdfform source="acroform2.pdf" destination="source_result17.pdf" action="populate" overwrite="true" fdf="true"> 
<cfpdfsubform name="Text1"> 
        <cfpdfsubform name="0"> 
        <cfpdfformparam name="0" value="Test1.0.0"> 
        <cfpdfformparam name="1" value="Test1.0.1"> 
        <cfpdfformparam name="2" value="Test1.0.2"> 
</cfpdfsubform> 
<cfpdfsubform name="1"> 
        <cfpdfformparam name="0" value="Test1.1.0"> 
        <cfpdfformparam name="1" value="Test1.1.1"> 
        <cfpdfformparam name="2" value="Test1.1.2"> 
    </cfpdfsubform> 
</cfpdfsubform> 
 
<cfpdfsubform name="Text2"> 
    <cfpdfformparam name="0" value="Test2.0"> 
        <cfpdfformparam name="1" value="Test2.1"> 
            <cfpdfformparam name="2" value="Test2.2"> 
            <cfpdfformparam name="3" value="Test2.3"> 
        </cfpdfsubform> 
<cfpdfformparam name="Text3" value="Test3"> 
<cfpdfformparam name="Text4" value="Test4"> 
<cfpdfformparam name="checkbox1" value="Yes"> 
<cfpdfformparam name="listbox1" value="item4"> 
<cfpdfformparam name="radiobutton1" value="2"> 
</cfpdfform>

read action

Use the read action to read the data from the source PDF form and generate a result structure that contains the form fields and their values. Also, you can use the read action to generate an XML data file from a PDF source file.

The following example shows how to read a PDF file and generate a result structure from the data:

<!--- Use the read action to retrieve the values from the saved PDF. ---> 
<cfpdfform source="c:\employeeid123.pdf" result="resultStruct" action="read"/>

You can use the cfdump tag to display the result structure:

<cfdump var="#resultStruct#">

You can use the result fields in ColdFusion, for example, #resultStruct.employeeId# and #resultStruct.salary#.

The following example shows how to read a PDF file and write the data to an XML file:

<cfpdfform source="c:\employeeid123.pdf" result="c:\employeeid123.xml" overwrite="yes"  
    action="read"/>

The following example shows how to read a PDF file into a variable that contains XML data:

<cfpdfform source="c:\employeeid123.pdf" XMLdata="myXMLdata" action="read"/>

The following example shows how to read a PDF file into an XML data variable and generate a result structure. The cffile tag writes the data to an XML file:

<cfset sourcefile = "Grant Application Updated.pdf"> 
<cfset resultfile = "Expandpath('datafile_result1.xml')"> 
<!--- Use the cfpdfform tag to read data extracted from a form into an XML data variable and 
    generate a result structure. ---> 
<cfpdfform source= "#sourcefile#" action="read" xmldata="xmldata" result="resultstruct"/> 
<!--- Use the cffile tag to write the XML data to a file. ---> 
<cffile action="write"file="#resultfile#" output="#xmldata#"> 
<!---- Use the cfdump tag to display the result structure. ---> 
<cfdump var="#resultstruct#">

Extracting data from a PDF submission

Use the following code to extract data from a PDF submission and write it to a structure called fields:

<!--- The following code reads the submitted PDF file and generates a result structure called 
    fields. ---> 
<cfpdfform source="#PDF.content#" action="read" result="fields"/>

Use the cfdump tag to display the data structure, as follows:

<cfdump var="#fields#">

Note: When you extract data from a PDF submission, always specify "#PDF.content#" as the source.

You can set the form fields to a variable, as the following code shows:

<cfset empForm="#fields.form1#">

Use the populate action of the cfpdfform tag to write the output to a file. Specify "#PDF.content#" as the source. In the following example, the unique filename is generated from a field on the PDF form:

<cfpdfform action="populate" source="#PDF.content#" 
    destination="timesheets\#empForm.txtsheet#.pdf" overwrite="yes"/>

Extracting data from an HTTP post submission

An HTTP post submission transmits the data from the PDF form, but not the form itself. You can extract data from the PDF form fields, but you cannot write the output directly to a file. To extract the data and update a database, for example, you must map the fields in the database to the structure and HTTP post data exactly.

Note: The structure of the HTTP post data (after submission) is not the same as the structure of the PDF form (before data submission). For examples of both, see Manipulating PDF Forms in ColdFusion in the Developing ColdFusion Applications.

To determine the structure of the HTTP post data, use the cfdump tag with the form name as the variable to display the data structure, as follows:

<cfdump var="#FORM.form1#">

Note: When you extract data from an HTTP post submission, always specify the form name as the source. For example, specify "#FORM.form1#" for a form generated from a template in LiveCycle Designer. When data extraction that uses the cfpdfform tag results in more than one page, instead of returning one structure, ColdFusion returns one structure per page.

Embedding PDF forms within a PDF document

You can use the cfpdfform tag inside the cfdocument tag to embed an existing interactive PDF form within a PDF document. Use at least one cfdocumentsection tag with the cfpdfform tag, but do not place the cfpdfform tag within the cfdocumentsection tag. For more information about embedding PDF forms, see Manipulating PDF Forms in ColdFusion in the Developing ColdFusion Applications.

Flattening forms created in Acrobat

You use the cfpdf tag to flatten forms created in Acrobat. ColdFusion does not support flattening forms created in LiveCycle. For more information, see Assembling PDF Documents in the Developing ColdFusion Applications.

Printing forms

Use the cfprint tag to print forms created in Acrobat. Markups, such as sticky notes, comments, and editorial revisions, are not printed with the form. You cannot use the cfprint tag to print forms created in LiveCycle Designer.

Exporting PDF Forms in FDF

In ColdFusion 9, you can now export PDF forms in FDF format using the read action. The following example shows how you can export a PDF form in FDF format:

<cfpdfform source= "acroform_export.pdf" action="read" fdfdata="abc.fdf" > 
</cfpdfform>

Example

The following example shows how to embed an interactive PDF form in a PDF document created with the cfdocument tag:

<!--- The following code extracts data from the cfdocexamples database based 
    on a username entered in a login form. ---> 
<cfquery name="getEmpInfo" datasource="cfdocexamples"> 
    SELECT * FROM EMPLOYEES 
    WHERE EMAIL = <cfqueryparam value="#form.username#"> 
</cfquery> 
 
<!--- The following code creates a PDF document with headers  
    and footers. ---> 
<cfdocument format="pdf"> 
    <cfdocumentitem type="header"> 
    <font size="-1" align="center"><i>Nondisclosure Agreement</i></font> 
    </cfdocumentitem> 
    <cfdocumentitem type="footer"> 
    <font size="-1"><i>Page <cfoutput>#cfdocument.currentpagenumber# of  
        #cfdocument.totalpagecount#</cfoutput></i></font> 
    </cfdocumentitem> 
     
<!--- The following code creates the first section in the PDF document. ---> 
    <cfdocumentsection> 
    <h3>Employee Nondisclosure Agreement</h3> 
    <p>Please verify the information in the enclosed form. Make any of the 
    necessary changes in the online form and click the <b>Print</b> button. 
    Sign and date the last page. Staple the pages together and return the 
    completed form to your manager.</p> 
    </cfdocumentsection> 
     
<!--- The following code embeds an interactive PDF form within the PDF 
    document with fields populated by the database query. The cfpdpfform tag 
    automatically creates a section in the PDF document. Do not embed the 
    cfpdfform within cfdocumentsection tags. ---> 
 
    <cfpdfform action="populate" source="c:\forms\embed.pdf"> 
        <cfpdfsubform name="form1"> 
            <cfpdfformparam name="txtEmpName" value="#getEmpInfo.FIRSTNAME# 
                #getEmpInfo.LASTNAME#"> 
            <cfpdfformparam name="txtDeptName" value="#getEmpInfo.DEPARTMENT#"> 
            <cfpdfformparam name="txtEmail" value="#getEmpInfo.IM_ID#"> 
            <cfpdfformparam name="txtPhoneNum" value="#getEmpInfo.PHONE#"> 
            <cfpdfformparam name="txtManagerName" value="Randy Nielsen"> 
        </cfpdfsubform> 
    </cfpdfform> 
 
<!--- The following code creates the last document section. Page numbering 
    resumes in this section. ---> 
    <cfdocumentsection> 
    <p>I, <cfoutput>#getEmpInfo.FIRSTNAME# #getEmpInfo.LASTNAME#</cfoutput>, 
        hereby attest that the information in this document is accurate and complete.</p> 
    <br/><br/> 
    <table border="0" cellpadding="20"> 
    <tr><td width="300"> 
    <hr /> 
    <p><i>Signature</i></p></td> 
    <td width="150"><hr /> 
    <p><i>Today's Date</i></p></td></tr> 
    </cfdocumentsection> 
</cfdocument>

cfpdfform