ColdFusion 9.0 Resources

Prefilling PDF form fields

Contents [Hide]

Nesting subforms

ColdFusion lets you prefill individual form fields with data extracted from a data source. For example, you can run a query to extract returning customer information from a data source based on a user name and password and populate the related fields in an order form. The customer can complete the rest of the fields in the form and submit it for processing. To do so, map the field names and the data structure of the PDF form to the fields in the data source.

To determine the structure of the PDF form, use the read action of the cfpdfform tag, as the following example shows:

<cfpdfform source="c:\forms\timesheet.pdf" result="resultStruct" action="read"/>

Then use the cfdump tag to display the structure:

<cfdump var="#resultStruct#">

The result structure for a form created in Acrobat form could look something like the following example:

struct
firstName	[empty string]
lastName	[empty string]
department	[empty string]
...	...

To prefill the fields in ColdFusion, you add a cfpdfformparam tag for each of the fields directly under the cfpdfform tag:

<cfpdfform action="populate" source="c:\forms\timsheet.PDF"> 
    <cfpdfformparam name="firstName" value="Boris"> 
    <cfpdfformparam name="lastName" value="Pasternak"> 
    <cfpdfformparam name="department" value="Marketing"> 
... 
</cfpdfform>

Forms created in LiveCycle from the standard blank forms contain a subform called form1. The result structure of a form created in LiveCycle could look like the following example:

struct
form1	struct
	txtfirstName	[empty string]
	txtlastName	[empty string]
	txtdepartment	[empty string]
	...	...

To prefill the fields in ColdFusion, add a cfpdfsubform tag for form1 and a cfpdfformparam tag for each of the fields to fill directly below the cfpdfsubform tag:

<cfpdfform source="c:\forms\timesheetForm.pdf" action="populate"> 
    <cfpdfsubform name="form1"> 
        <cfpdfformparam name="txtfirstName" value="Harley"> 
        <cfpdfformparam name="txtlastName" value="Davidson"> 
        <cfpdfformparam name="txtDeptName" value="Engineering"> 
        ... 
    </cfpdfsubform> 
</cfpdfform>

Note: In dynamic forms created in LiveCycle forms (forms saved as Dynamic PDF Form Files in LiveCycle Designer), you have the option to mark how many times a record is repeated. Therefore, if no record exists for a subform, the subform does not appear in the structure returned by the read action of the cfpdfform tag. You view these forms in LiveCycle Designer to see the hierarchy.

Nesting subforms

Although Acrobat forms do not contain subforms, some contain complex field names. For example, an Acrobat form could contain the following fields: form1.x.f1, form1.x.f2, form1.x.f3, and so on.

Because the cfpdfparam tag does not handle field names with periods in them, ColdFusion treats forms with complex field names created in Acrobat the same way as subforms created in LiveCycle. Therefore, the result structure of an Acrobat form with complex field names would look like the following example:

struct
form1	struct
	x	struct
		f1	[empty string]
		f2	[empty string]
		...	...

In ColdFusion, to prefill the fields in forms created in Acrobat, nest the field names as subforms:

<cfpdfform action="populate" source="acrobatForm.pdf"> 
    <cfpdfsubform name="form1"> 
        <cfpdfsubform name="x"> 
            <cfpdfformparam name="f1" value="AGuthrie"> 
            <cfpdfformparam name="f2" value="123"> 
            <cfpdfformparam name="f3" value="456"> 
        </cfpdfsubform> 
    </cfpdfsubform> 
</cfpdfform>

Often, forms created in LiveCycle contain subforms within the form1 subform. For example, the following grant application contains nested subforms:

struct
form1	struct
	grantapplication	struct
		page1	struct
			orgAddress	[empty string]
			orgCity	[empty string]
			orgState	[empty string]
			...	...
		page2	struct
			description	[empty string]
			pageCount	[empty string]
			...	...

To populate the fields in ColdFusion, map the structure by using nested cfpdfsubform tags:

<cfpdfform source="c:\grantForm.pdf" destination="c:\employeeid123.pdf" action="populate"> 
    <cfpdfsubform name="form1"> 
        <cfpdfsubform name="grantapplication"> 
            <cfpdfsubform name="page1"> 
                <cfpdfformparam name="orgAddress" value="572 Evergreen Terrace"> 
                <cfpdfformparam name="orgCity" value="Springfield"> 
                <cfpdfformparam name="orgState" value="Oregon"> 
                ... 
            </cfpdfsubform> 
            <cfpdfsubform name="page2"> 
                <cfpdfformparam name="description" value="Head Start"> 
                <cfpdfformparam name="pageCount" value="2"> 
                ... 
            </cfpdfsubform> 
        </cfpdfsubform> 
    </cfpdfsubform> 
</cfpdfform>

Note: A PDF file can contain only one interactive form. Therefore, if a PDF file contains subforms, a Submit button submits data for all the subforms simultaneously.