Usage

Setting up a FillPDF form

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

1. Identify the entity type that will supply the data.
2. Map the data fields to the form controls in the PDF.
3. Use a URL to merge the data into the PDF.

How to map 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
   • Fill pattern 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 CCK form 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 form submission. As long as their browser ends up at the link, FillPDF will trigger.

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

/fillpdf?fid=1&entity_id=1

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

You can use any entity type and ID that provides tokens with FillPDF. See the sample Webform link below to see an example of using something other than node entities.

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&entity_id=2">PDF</a>. If the Clean URLs Drupal setting is not enabled, the URL will be in the format:

    /?q=fillpdf&fid=10&entity_id=2

  • Multiple nodes; later nids override conflicting fields
    <a href="/fillpdf?fid=1&entity_ids[]=1&entity_ids[]=2">PDF</a>

  • Using a single webform submission (common):

    <a href="/fillpdf?fid=1&entity_type=webform_submission&entity_id=4">PDF</a>

  • Mixing and matching different entity types (nodes and Webform submissions in this case):
    <a href="/fillpdf?fid=1&entity_ids[]=node:1&entity_ids[]=node:2&entity_ids[]=webform_submission:1&entity_ids[]=webform_submission:5">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&entity_id=[nid]

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

• Add the link in PHP (advanced). See \Drupal\fillpdf\Service\LinkManipulator (the fillpdf.link_manipulator service).

# 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 annotation above the class implementing the entity in the programming code of the module that provides the entity. For taxonomy terms, for example, the developer would check the @ContentEntityType annotation above the \Drupal\taxonomy\Entity\Term class the Taxonomy module and see that the machine name (id) 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

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.

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:
   • For entity bundles: a File or Image field attached to the entity bundle (e.g. content type, user, taxonomy vocabulary, etc.)
   • For a Webform: an Image component
2. When configuring your field mapping on the relevant PDF field screen, use:
   • 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]
   • For webforms: the [webform_submission:values:element_id] token, where element_id is the key displayed next to the component name on the Webform component overview page. This works for Image fields and Signature fields.

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 hosted service (none currently offered).
• 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.