cfpdfform
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:
Categories
Related
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 | Description | Required | Default |
|---|---|---|---|
| action | NA | ||
| destination | populate | ||
| fdf | populate | ||
| fdfdata | populate read | ||
| overwrite | populate read | ||
| overwriteData | populate | ||
| result | read | ||
| source | populate read | ||
| XMLdata | populate read |
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#">
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#">
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>
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>
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 />
<i>Signature</i></p></td>
<td width="150"><hr />
<i>Today's Date</i></p></td></tr>
</cfdocumentsection>
</cfdocument>