Once you have copied the above into your config file, you’ll need to rename the class to match your file name. This will ensure it can be automatically loaded when your template is used. There are a few rules to keep in mind for the class name:

The file extension is omitted (.php)

Any hyphens (-) should be replaced with underscores (_)

The class name should be in sentence case (the first character of each word separated by an underscore (_) should be upper case)

For instance, if you created a custom template called business-letter.php the class name should be Business_Letter:

The configuration() method allows you to return an array which defines the supported template settings. The array is split into two sub-keys: core and fields. The core key allows you to enable built-in fields like headers and footers, while the fields key allows you to implement your own fields using our settings API.

Gravity PDF has a number of built-in template-specific fields you can easily enable. Some of them are only applicable when using the $pdf->process_html_structure() method (the main way Core templates generate their mark-up) in your custom template, while others can be included in your PDF automatically.

Below is a sample of the configuration method with a number of core fields enabled:

Adding your own custom fields is where this feature gets really powerful. Using the fields sub-key you can define text, paragraph, rich text, radio buttons, select boxes, colour pickers or upload fields with a few lines of code:

The header, first_header, footer, first_footer, background_color and background_image core fields are automatically supported in custom PDF templates (provided you don’t override them with your own header/footer or background using @page). However, all custom fields will need appropriate logic included in your PDF template.

To do this, you’ll have to access a variable named $settings in the PDF template. This variable is an array that contains all the settings a user has defined (using the field ID as the array key) and is where your template settings will be located.

We like to use these methods to automatically install custom fonts (setUp()), and then clean-up additional template-related files when deleted (tearDown()).

The Delete function of the PDF Template Manager will only delete the template file, the configuration file and the template image. Any additional files included will not be removed automatically.

If you need to include additional files with your template, we recommend saving them to /install/Template_Name/ (substitute Template_Name). This will make it easy for you to clean-up when writing tearDown().

Below is a sample showing you how you can auto-install a font and clean-up your template’s files on delete. This assumes you’ve created the directory structure /install/Hello_World/font-fira-sans/ in your PDF working directory and have the listed fonts included.

Continuing on from our Part 3 Hello World Tutorial, we’re going to show you how to create a template configuration with core footer and background image support enabled. We’ll also add a new field that will determine if meta data should be included in the document.

First, let’s grab a copy of the basic PDF template PHP mark-up and save it in the config folder of our PDF working directory. Remember to save the file as hello-world.php – the same name we used for our template file. This sample code already has the class name changed to Hello_World, but you would normally update this to match your template’s file name.

The only area we’ll be focusing on is the empty array being returned in the configuration method. We’ll need to update this to include our two core fields and create our custom field. Let’s do the core fields first:

We’ve just told the system we want to enable the footer field and our background image field. If you edit your Hello World PDF settings in WordPress, you’ll see a new Template tab with our two core fields included. The system will automatically parse and store these fields when the PDF settings are saved.

Including a custom field is a little trickier, but we’re just defining array key/value pairs that tell Gravity PDF how to display a field:

We’ve just told Gravity PDF about a new radio field called Show Meta Data that has Yes/No options. By default the No value will be selected and a nice description about what the field does is shown just below the radio buttons. We’ve also prefixed our field ID with world_ so we don’t clash with any other fields. And because we are conscientious developers we’ve made all our strings translatable by wrapping them in the __() function. Make sure you only translate the option array values, and not the keys.

Now we’re capturing and saving the footer, background image and meta data toggle from the user we need to update our original Hello World PDF template. The core header/footer and background image fields will automatically be included, but we’ll need to update the PDF template to support our custom field.

If you remember from earlier the $settings array holds all our custom fields and is where we’ll find the meta data setting. To keep our PDF template clean we’ll set the settings variables at the beginning of the template (before the HTML).