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.

Category

Forms tags

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"/>

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"/>

See also

cfdocument, cfdocumentsection, cfform, cfinput, cfpdf, cfpdfformparam, Usagecfpdfparam, cfpdfsubform, cfprint, IsPDFFile, IsPDFObject, "Manipulating PDF Forms in ColdFusion"1 in the ColdFusion Developer's Guide

Attributes

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"1 in the ColdFusion Developer's Guide.

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.

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"1 in the ColdFusion Developer's Guide.

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>

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#"> 

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.

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#">

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"1 in the ColdFusion Developer's Guide.

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 ColdFusion Developer's Guide.

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.

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>