Usage

Setting up a FillPDF form

There are 3 steps to setting up a form with FillPDF:

1. Create the form which will supply the data, either a content type or a Webform.
2. Map the data fields to the form controls in the PDF.
3. Use a URL to merge the data into the PDF.

Create the form

To create the form into which users will enter data, you have the following options:

• Use content types (nodes) and fields
• Use Webform
• Use Ubercart

Getting PDF field information

To learn the PDF file's field names and value options, install pdftk and run pdftk yourfile.pdf dump_data_fields.

Map the fields

To map the form to a PDF, do the following:

1. Go to (YOUR SITE)/admin/structure/fillpdf
2. Upload a PDF template, a form mapping will be generated. Make sure the PDF document isn't encrypted. If it is encrypted and non-copyrighted (typical of government PDFs), then try a decrypting tool like "Advanced PDF Password Recovery." If you upload an encrypted PDF, you will have an empty list of fields when you attempt to download your submissions.
3. When editing fields, note the following:
   • Label is for your own use in identifying fields
   • PDF Key is the field name from the original PDF Form (such as text_field_1) and is the piece that maps the form field to the PDF field
   • Value is where you either enter static data to populate the field, or tokens to pull information form the users' forms. For example, if I created a content type with a text field called field_first_name, then I would enter [node:field_first_name] here. There is a list of tokens you can use at the bottom of that page.

     Note on checkbox/multiple-value fields: see #2147647: Checkboxes Solved for limitations/workarounds on multiple-value fields.

The FillPDF URL: Use a URL to merge the form data into the PDF

Once your user fills out a form, they'll need a link to download their PDF. You can place this link in a block, theme template, node, or even redirect the user to it directly from a Webform submission. As long as their browser ends up at the link, FillPDF will trigger.

Recommended format for entities (requires the Entity Tokens module):

An example of a FillPDF URL (without the website part) is:

/fillpdf?fid=1&entity_ids=node:1

Alternative formats:

• /fillpdf?fid=1&entity_type=node&entity_id=1
• /fillpdf?fid=1&entity_id=node:1

See the query string parameter reference below for complete documentation.

Legacy format (nodes only)

An example of a FillPDF URL (without the website part) is:

/fillpdf?fid=1&nid=1

This fills in FillPDF template #1 from node #1, according to the field value configuration in FillPDF template #1.

More examples

Here are some ways to generate the link:

• Add the link manually in HTML or with Views field rewriting. Examples:
  • Using a single node: <a href="/fillpdf?fid=1&nid=2">PDF</a>. If the Clean URLs Drupal setting is not enabled, the URL will be in the format:

    /?q=fillpdf&fid=10&nid=10

  • Using a single webform submission (common):

    <a href="/fillpdf?fid=1&webform[nid]=3&webform[sid]=4">PDF</a>

  • Multiple nodes or webform submissions; later nids override conflicting fields (note: webforms without sid default to latest submission)
    <a href="/fillpdf?fid=1&nids[]=1&nids[]=2&webforms[0][nid]=3&webforms[0][sid]=1&webforms[1][nid]=3">PDF</a>

  To create the link in an existing field on a Views view:

  • Add a Global: Custom text field
  • For the main text, type in the text you'd like for the link. An example of this is Generate PDF
  • Expand the option set labeled Rewrite results and click the checkbox for Output this field as a link. For Link path, use a link in the following format:

    fillpdf?fid=1&webform[nid]=3&webform[sid]=4

    You only need to set Link path, unless you know that you need other options on the link.

    A more dynamic example of this is the following, which you could use in a list of Webform Submissions:

    fillpdf?fid=1&webform[nid]=[nid_1]&webform[sid]=[sid_1]

    In this case, you need to add the Nid and Sid of the Webform twice and rearrange the first set (whose field tokens are [nid] and [sid]) to be below the Global: Custom text field that you added. Otherwise, views will replace [nid] and [sid] with the actual Nid and Sid, and this can be confusing to troubleshoot.

    Finally, note that you can create a link field for nodes in a View as well. Refer to the standard HTML link formats above. From fillpdf onward, the formats are the same, except for any dynamic replacements you choose to use in Views.

• Add the link in PHP (advanced). Examples:
  • Using a single node:

    echo l("PDF", fillpdf_pdf_link($form_id = 1, $node_id = 2));

  • Using a single webform submission (common):

    echo l("PDF", fillpdf_pdf_link($form_id = 1, null, $webform = array('nid'=>3,'sid'=>4)));

  • Multiple nodes or webform submissions; later nids override conflicting fields (note: webforms without sid default to latest submission)

    echo l("PDF", fillpdf_pdf_link($form_id = 1, $nids = array(1,2), $webforms = array( array('nid'=>3,'sid'=>1), array('nid'=>3)));

# Query string parameter reference

These are the query string parameters that may be used in a FillPDF URL:

entity_id

String. The entity from which to draw form data. Example: entity_id=taxonomy_term:1. If you omit the entity type, then the entity type is determined in this order: 1) the value of the entity_type query string parameter, 2) the default entity type configured for the FillPDF Form, 3) node.

The entity type should be specified with its Drupal machine name. This can be found in the hook_entity_info implementation in the programming code of the module that provides the entity. For taxonomy terms, for example, the developer would check taxonomy_entity_info in the Taxonomy module and see that the machine name is taxonomy_term.

entity_type

String. The entity type of the entity specified in entity_id. Note: This does not work for entity_ids[]. Example of entity_type: entity_type=taxonomy_term&entity_id=1.

entity_ids[]

Array of strings. The entities from which to draw form data. Allows drawing data from multiple sources (see examples above). Entities you specify later in the URL take precedence over earlier ones: for each field, the last non-empty value is used. Example: entity_ids[]=taxonomy_term:1&entity_ids[]=taxonomy_term:7

webform[nid], webform[sid]

Integer. The Webform node and submission from which to draw form data.

webforms[][nid], webforms[][sid]

Array of integer. The Webform nodes and submissions from which to draw form data. Ignored if webform is set.

uc_order_id, uc_order_ids[]

Integer or array of integers. The Ubercart orders from which to draw data.

uc_order_product_id, uc_order_product_ids[]

Integer or array of integers. The Ubercart orders products (Order Products) from which to draw data.

fid

Integer. The FillPDF Form ID of the PDF to put the data into. You can find this when editing the form.

sample

If set to "true" (exact string), each field will be filled with its field name.

download

Integer. If set to 1, always send a PDF to the browser, even if a destination_path is set for the PDF.

flatten

Integer. If set to 0, leave form fields editable. Default is to flatten the PDF so that fields cannot be edited.

nid (deprecated; install Entity Tokens and use entity_id instead)

Integer. The node from which to draw form data.

nids[] (deprecated; install Entity Tokens and use entity_ids[] instead)

Array of integer. The nodes from which to draw form data. Ignored if nid is set.

Handling the filled PDF

FillPDF offers three ways to deal with the generated PDF:

1. Prompting the user to download it
2. Saving the PDF to a specific path
3. Saving the PDF to a specific path, and then redirecting the user to that file. This generally allows them to view it in their browser.

Private files

If you use private files, then in order to be redirected to the generated file, the user needs permission to generate that file in the first place. This does not affect direct download either way; that checks for appropriate permissions as well.

Changing the redirect path

When a visitor clicks a FillPDF Link for a PDF that is configured to be saved to a file, the visitor is redirected to the homepage by default. To change the place they are redirected, use the destination query string parameter that Drupal provides.

For example, this link — assuming the PDF is set up to be saved to file — will redirect the user to the homepage after saving: fillpdf?fid=1&nid=1

To make it redirect them to their user account page, use: fillpdf?fid=1&nid=1&destination=user

Notice the addition of &destination=user to change the redirect path.

Updating the PDF

When you edit a FillPDF configuration, look for the Update PDF upload field. You can upload a new PDF, and this will automatically transfer over mappings to the new PDF. Field mappings referencing a PDF key that can't be found in the new PDF will not be transferred.

Exporting and importing field mappings

If you upload a new copy of a PDF but don't want to update an existing configuration, you will need to copy the field mappings from the old version to the new one.

1. Go to the (YOUR SITE)/admin/structure/fillpdf page.
2. Click "Export FillPDF field mappings" next to the old PDF.
3. Select-all and copy the FillPDF Form Mappings.
4. Go back to the (YOUR SITE)/admin/structure/fillpdf page.
5. Click Import FillPDF field mappings next to the new PDF.
6. Paste into the box Paste code.
7. Click Import.

Filling in PDF Image Fields

1. Ensure you have created:
   1. For entity bundles or Node content types (deprecated, entities and Entity Token module recommended): a File or Image field attached to the entity bundle (e.g. content type, user, taxonomy vocabulary, etc.).
   2. For a Webform: a File component
2. When configuring your field mapping on the relevant PDF field screen, use the field token corresponding to the image field:
   1. For entity bundles: The format is [entity_token_type:field_name], where entity_token_type is the token prefix used by the entity type and field_name is the name of your image field.
      1. Example for field_image on a node content type: [node:field_image]
      2. Example for field_image on a taxonomy vocabulary: [term:field_image]
   2. For Webforms: The format is [submission:values:form_key], where form_keyis the ID of the component (you see this, among other places, when you edit it).

Ensure that there are no spaces around the token and that it is in the Value field.

Requirements

• You must use FillPDF LocalServer or a paid FillPDF Service subscription.
• The PDF field must be a Button field, and we recommend making the background transparent. You can also use the ImageField field type from Adobe LiveCycle Designer.

Transforming field values

Sometimes the way Drupal stores field values isn't the way the PDF expects. For example, PDF checkboxes often need to be sent a value of Yes or Off to show checked or unchecked states, respectively. However, your field may be a Boolean or Integer field and store 0 or 1.

Using field value transformation, you can tell FillPDF to send Off to the PDF instead of 0 and Yes instead of 1. This can be done at both the PDF and individual field levels, with field-level transformations overriding PDF-level ones. See the Transform Values section when setting up your field mappings for full instructions on how to configure this.