Before we jump right into the code, we're going to discuss the architecture Gravity PDF uses to register and load custom templates, how multisite sites differ from standard WordPress installations and briefly touch on the template hierarchy.
Jump To Section
- Working Directory
- Preparing the Infrastructure
- Template Structure
- Variables Available
- Template Tutorial – Part 1
When Gravity PDF is installed it automatically creates a folder called
PDF_EXTENDED_TEMPLATES in your WordPress upload directory. This folder is used to store temporary files, fonts and custom PDF templates. Any PHP files in the root of this folder will be classified as a PDF template1 and the system will automatically register it.
On a vanilla WordPress installation the full path to the
/wp-content/uploads/PDF_EXTENDED_TEMPLATES. Your installation may be different if defining custom
Preparing the Infrastructure
Setup Custom Templates tool function from
Forms -> Settings -> PDF -> Tools in your admin area will setup the required folder structure and automatically copy all the core templates to the
PDF_EXTENDED_TEMPLATES directory so you can easily begin templating. We recommend you copy and rename one of the core templates in
PDF_EXTENDED_TEMPLATES to use as a starting point for your custom template.
To correctly handle multisite installations the plugin creates a directory in
PDF_EXTENDED_TEMPLATES for each active multisite. The folders use the site ID parameter to determine which templates to load. For instance, site #5 will use the folder
/wp-content/uploads/PDF_EXTENDED_TEMPLATES/5/ for its templates.
The site ID can be found by looking at each site's
Edit URL in the
Network Admin -> Sites section of your admin area (you'll need to be logged in as a network administrator). Alternatively, the site ID column is automatically added to this page when using the Multisite Enhancements plugin.
When we designed the Gravity PDF template system we used the Theme hierarchy as a starting point. The plugin's core templates are like the parent theme, while the
PDF_EXTENDED_TEMPLATES directory acts like a child theme. All core template can be overridden by placing a file with the same name in
PDF_EXTENDED_TEMPLATES – which is what happens automatically when you follow the preparing the infrastructure step.
The hierarchy in Multisite installations function a similar way to standard WordPress sites, except there are three hierarchy layers instead of two. The core templates and
PDF_EXTENDED_TEMPLATES directory still act like parent and child themes, but the unique site folders act like a child "child theme".
The templates places in the root
PDF_EXTENDED_TEMPLATES directory are loaded by all sites in the network. While templates in a site-specific directory – like
PDF_EXTENDED_TEMPLATES/5/ – are, well, site specific. Keep in mind templates in site specific folders override templates in the root
PDF_EXTENDED_TEMPLATES directory. This setup becomes very useful when duplicating sites in your network, but in most cases you can just drop your custom template in the unique site folders.
Much like creating plugins or themes, all PDF templates must have the appropriate file headers to tell Gravity PDF more information about your template. Your header should include:
- Template Name: The name of your template, which will be displayed to the user when selecting templates.
- Description: A short summary about what your PDF template is for.
- Version: The current version number of your PDF template.
- Author: The PDF template author name
- Author URI: The author's website URL
- Group: The group your PDF should be assigned to. The group can be anything and helps users find the templates they're looking for.
- License: The license type the PDF template is released under e.g GPLv2
- Required PDF Version: The minimum Gravity PDF version required to run the template.
- Tags: Any PDF tags that can be used to better search for the plugin in the PDF Template Manager
A valid header might look like this:
The following variables are available to all PDF templates:
$form : The current Gravity Form object being processed. This is the main object in Gravity Forms and contains all properties of a particular form – form title, fields, notification, confirmation ect.
$entry : The current Gravity Form entry object being processed. This object contains all properties of a particular entry in raw format – accessing field data directly from the object should be avoided. The object is formatted as an associative array and the field IDs are the array keys.
$lead : An alias for $entry
$settings : The current PDF configuration settings in array format. Standard settings like filename and font size are stored in this array, as well as template-specific settings.
: An array of the current Gravity Forms fields which can be accessed using their field ID number –
print_r( $fields );. This is just a formatted version of the
$gfpdf : This is the main Gravity PDF object which contains all our helper classes (including data, form, options, notices, misc and log). Power users may find this useful.
: An associative array containing all of the above variables. For instance
For backwards compatibility, these variables are available to templates but are deprecated:
: The current form ID being processed. We recommend you use
: The current entry ID being processed. We recommend you use
$lead_ids : An array of the selected entries to be processed. This array was used in Gravity PDF v3 to process multiple entries in a single PDF, but this had a lot of performance problems and has been removed in v4+. We strongly recommend against using this.
Template Tutorial – Part 1
Now we've got all the theory out of the way let's create our first PDF template. In the traditional fashion, this will be a basic "Hello World" PDF.
To get started, create a new PHP file in your IDE of choice and call it
hello-world.php. We're going to add the following headers to the file to tell Gravity PDF about the template:
As you can see it's very simple to let Gravity PDF know about your PDF template. More information about each individual header is available in the Template Structure section.
Next we're going to layout the basic structure. Go ahead and add the following below the header section:
Think of Gravity PDF templates as HTML that is automatically included inside the
<body> tag – unlike Gravity PDF v3 templates you won't need to add a
<!DOCTYPE html> or
<head></head> mark-up. Any supported CSS can be placed in the
<style> tags, while your actual content should be included below that. Simple!
To finish off our example we've going to replace
<!-- The PDF content should be placed in here --> with
<h1>Hello World</h1>. Once done, save the example and upload it to your PDF working directory.
Once you've uploaded the template you'll be able to see your new Sol System group added to the template field when configuring new form PDF templates. Go ahead and configure a new form PDF with your Hello World template and then view the PDF. You should see a PDF with "Hello World" written in large text.
If you would like to change the appearance of the PDF we can add new styles to the document. We're going to change the
<h1> tag appearance by adding the following CSS inside the
Save and upload the template again. When you view it you'll see the heading is now centre-aligned, burgundy in colour, with a bottom border. How easy is that!
- For legacy reasons ensure you don't name your template