# Usage

The Ortus PDF extension will give you the following available tags:

* `cfpdfform`
* `cfpdfformparam`

### cfpdfform/cfpdfformparam

This tag allows you to manipulate existing PDF forms, usually edited in Adobe Acrobat or LiveCycle Designer. You will be able to do the following:

* Embed a form with pre-filled FORM data and deliver it via `cfcontent or cfpdf or cfdocument` tags
* Render out a pre-filled FORM to disk with overwrite and flattening capabilities.
* Extract values from a PDF form as:
  * CFML Structure
  * XML string
  * XML file
  * FDF file

#### **Basic Usage**

```xml
<cfpdfform
    action = "populate"
    source = "PDF file pathname|byte array"
    destination = "output file pathname"
    overwrite = "yes|no"
    overwriteData = "yes|no"
    xmlData = "XML object|XML string|XML data filename"
    structData = "CFML Struct">
    
    <cfpdfformparam name="" value="" index="" />

</cfpdfform>

<cfpdfform
    action = "read"
    source = "pathname|byte array"
    result = "structure containing form field values"
    overwrite = "yes|no"
    xmlData = "variable containing xml values or an XML file path"
    fdfData = "The absolute file path to export the data as FDF"> 
</cfpdfform>
```

The `cfpdfform` tag can have nested `cfpdfformparam` tags in order to populate forms inside PDF documents.

### **`cfpdfform` attributes**

| **Parameter**     | **Required** | **Action**       | **Default** | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ----------------- | ------------ | ---------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **action**        | Yes          | ---              | `read`      | Action to perform: `populate or read`                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| **destination**   | Yes          | `populate`       | ---         | 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. Do not specify the destination when you embed a form in a PDF document.                                                                                                                                                                                                                                                        |
| **overwrite**     | No           | `populate, read` | No          | Specifies whether to overwrite the destination file (if action="populate") or the data file (if action="read"):                                                                                                                                                                                                                                                                                                                                                               |
| **overwriteData** | No           | `populate`       | No          | If enabled it will overwrite form field values, else it will only override them if the value is empty.                                                                                                                                                                                                                                                                                                                                                                        |
| **result**        | No           | `read`           | `pdfdata`   | ColdFusion structure that contains the form field values. If not used, the tag will create a variable called `pdfdata` for you in the `caller` scope.                                                                                                                                                                                                                                                                                                                         |
| **source**        | Yes          | `populate, read` | ---         | 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.                                                                                                                                                                                                                                                                                                                                       |
| **flatten**       | No           | `populate`       | true        | Will flatten the populated PDF so the form is sealed in the container PDF.                                                                                                                                                                                                                                                                                                                                                                                                    |
| **structData**    | No           | `populate`       | ---         | Instead of using nested `cfpdfformparam` tags, you can pass a struct of name-value pairs to populate a PDF form with.                                                                                                                                                                                                                                                                                                                                                         |
| **jsonData**      | No           | `populate,read`  | ---         | <p><strong>Populate</strong>: Instead of using nested <code>cfpdfformparam</code> tags, you can pass a JSON object of name-value pairs to populate a PDF form with.<br><strong>Read</strong> : If a string, this will be the name of the variable in the caller's <code>variables</code> scope that will contain the form data as a JSON string.</p>                                                                                                                          |
| **xmlData**       | No           | `read, populate` | ---         | <p><strong>Read</strong> : If a string, this will be the name of the variable in the caller's <code>variables</code> scope that will contain the Form data as an XML packet value. If this is a file path ending in <code>.xml</code> then the tag will export the XMl of the Form data to that file.<br><strong>Populate</strong> : The XML object, XML string or XML data filename to use when populating the PDF form instead of sub <code>cfpdfformparam</code> tags.</p> |
|                   |              |                  |             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |

### **`cfpdfformparam` attributes**

| **Parameter** | **Required** | **Default** | **Description**                  |
| ------------- | ------------ | ----------- | -------------------------------- |
| **name**      | Yes          | ---         | The name of the PDF form entry   |
| **value**     | Yes          | ---         | The value of the PDF form entry  |
| **index**     | ---          | ---         | ''Not implemented by Ortus PDF'' |

#### **Examples**

**Populating a PDF Form with sub params**

```xml
<cfpdfform 
    action="populate" 
    source="#datapath#/report.pdf" 
    destination="#workpath#/report-out.pdf" 
    overwrite="true"
    overwriteData="true"
    result="myresult"
    flatten="true">
    <cfpdfformparam name="full_name" value="Ortus Rocks" />
    <cfpdfformparam name="exam_date" value="#dateFormat( now(), "mmmm dd, yyyy")# #timeFormat( now(), "medium")#" />
    <cfpdfformparam name="strategy_overview" value="Drink a lot of water!" />
    <cfpdfformparam name="strategy_tips" value="Eat a lot of cheese!" />
</cfpdfform>

<!-- Deliver the file -->
<cfcontent file="#workpath#/report-out.pdf" type="application/pdf" reset="true" />
```

**Populating a PDF Form with a struct**

```xml
<cfset data = {
    "full_name" 		= "Ortus Rocks",
    "exam_date" 		= "#dateFormat( now(), "mmmm dd, yyyy")# #timeFormat( now(), "medium")#",
    "strategy_overview" = "Drink a lot of water!",
    "strategy_tips" 	= "Eat a lot of cheese!"
}>
<cfpdfform 
    action="populate" 
    source="#datapath#/report.pdf" 
    overwrite="true"
    overwriteData="true"
    structData=data
    flatten="true">
</cfpdfform>
```

**Populating a PDF Form with a JSON object**

```xml
<cfset jsonData = '{
    "full_name" 		: "Ortus Rocks",
    "exam_date" 		: "#dateFormat( now(), "mmmm dd, yyyy")# #timeFormat( now(), "medium")#",
    "strategy_overview" : "Drink a lot of water!",
    "strategy_tips" 	: "Eat a lot of cheese!"
}'>
<cfpdfform 
    action="populate" 
    source="#datapath#/report.pdf" 
    overwrite="true"
    overwriteData="true"
    jsonData="#jsonData#"
    flatten="true">
</cfpdfform>
```

**Populating a PDF Form from and XML file and stream to browser**

```xml
<cfpdfform 
    action="populate" 
    source="#datapath#/report.pdf" 
    overwrite="true"
    overwriteData="true"
    xmlData="c:\temp\data.xml"
    flatten="true">
</cfpdfform>
```

**Reading a PDF Form**

```xml
<cfpdfform 
    action="read"
    source="#dataPath#/report.pdf"
    result="formData">

<cfdump var="#formData#">
```

**Reading a PDF Form as JSON Data**

```xml
<cfpdfform 
    action="read"
    source="#dataPath#/report.pdf"
    jsonData="formData">

<cfdump var="#isJSON( formData )#">
<cfdump var="#formData#">
```

**Reading a PDF Form as XML Data**

```xml
<cfpdfform 
    action="read"
    source="#dataPath#/report.pdf"
    xmlData="formData">

<cfdump var="#isXML( formData )#">
<cfdump var="#formData#">
```

**Reading a PDF Form as XML Data into an XML output file**

```xml
<cfpdfform 
    action="read"
    source="#dataPath#/report.pdf"
    xmlData="c:\temp\export.xml">
```

**Reading a PDF Form in FDF format and outputting to a file**

```xml
<cfpdfform 
    action="read"
    source="#dataPath#/report.pdf"
    fdfData="c:\temp\export.fdf">
```

**XML Data**

If you will be populating forms or extracting forms, the format in XML will be the following:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<fields
><exam_date
>October 31, 2013 10:00am</exam_date
><full_name
>Populated by XML</full_name
><keystrengths
>After training, the dimensions of Radical Innovation upon which 
you performed highest were RECEPTIVITY and SELF-INQUIRY.</keystrengths
></fields>
```

<br>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ortuspdf.ortusbooks.com/essentials/usage.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.