Custom Templates Guidelines - Read This First

Starting with Shield 9.1, we'll be offering the ability to change the content shown to users through the use of custom templates.

Please note that this is a Premium feature only. 

This is an advanced feature and without due care, you may break functionality of your Shield plugin. Our support team will endeavor to assist you, but if you follow the rules outlined in this article you can't go wrong and oftentimes we'll just point you to this article if it appears your templates aren't following the guidelines.

The Shield Security support team will not create customized templates for you - if you need this, but don't have the expertise to create the templates, you will need to hire a suitable developer to do this for you.

Guidelines For Shield Security Templates

Guideline #1

Templates may only be created, edited and stored within your active theme directory.  If you edit the templates within the Shield plugin, you'll lose these customizations with each Shield plugin upgrade.

You must store your custom templates in your theme directory. (unless you use the WP filter provided. See Guideline #10)

Guideline #2

Custom templates for the Shield Security plugin are only stored within the ` shield_templates` directory inside your active theme.  They cannot be stored anywhere else (at this time).

For example, if your theme is 'twentyeleven`, then the custom templates directory will be:

/wp-content/themes/twentyeleven/shield_templates/

If you have a child theme (highly recommended), use your child theme directory, not the parent theme, for the same reasons as outlined in Guideline #1.

Guideline #3

The name of the template file must exactly match the name of the original template file that you're customizing, and it must follow the same folder structure.  This includes the filename and its extension. (all files will have the extension .twig)

For example, all email templates are in a subfolder: email

Extending the example from Guideline #2, if you wish to extend email template "my_email.twig", the full path to the custom template would be:

/wp-content/themes/twentyeleven/shield_templates/email/my_email.twig

Guideline #4

The templating engine is TWIG, and so all files must have the .twig extension.

It also means you cannot embed PHP directly into the template files. Trying to do so will have no effect.  You may however use TWIG language if you're familiar with it.

Guideline #5

Some templates use important variables. If you don't include the necessary variable, then you will likely break your installation and things won't run as you expect.

If you try to include or access non-existent variable, the system will generate a fatal error while trying to render the template.

An example of this is the 2-Factor Authentication email... if you don't output the variable for your 2FA code, then your email won't contain the 2FA code and your users wont be able to login.

We'll make it clear in the documentation for each template which elements are important. If you retain those elements exactly as-is from the original template, then you won't go wrong.

Guideline #6

TWIG is a templating language and if you don't follow the syntax, it'll break processing with a fatal error, just like with PHP. If you have any doubts, refer to the original template for the syntax.

For example, to print a variable, you'd use the double braces syntax:   {{ variable_name }} 

This syntax must be precise. You must use double-braces and the precise name of a variable (that exists). If you get the variable name wrong, it'll break. If you use single-braces, it'll break.

Guideline #7

As stated, Shield uses TWIG templates. To make things easier, we use inheritance and most templates extend other templates. This allows us to compose templates more quickly without needing to re-write and repeat common code and content.

You must include all the extra "bits and pieces" in the templates or you may break functionality, particularly the " extend" command and "block"s.

As always, if you hit an error, you can simply copy in the original template and start editing from there once again.

Guideline #8

Not all emails and pages are template-ready. Please check the documentation on which templates are available to customize.

Please do feel free to reach out to us if there's an element you'd like to see templated for customisation and we'll do what we can to help.

Guideline #9

All original Shield Security templates are found in the twig-templates directory inside the Shield Security plugin:

/wp-content/plugins/wp-simple-firewall/templates/twig/

Simply locate the template you want to edit and copy it to your templates directory inside your theme.

For example, let's say you want to edit the 2FA email template. This is found here:

/wp-content/plugins/wp-simple-firewall/templates/twig/email/lp_2fa_email_code.twig

To start creating your customised version of this template, remember Guideline #3 - the name of the template and any subfolders must match exactly the original.  In this case, the original is:

/email/lp_2fa_email_code.twig

So you then need to:

  1. Create a directory "email" inside your "shield_templates" directory within your theme.
  2. Copy the file (do not delete or move it) "lp_2fa_email_code.twig" to the new "email" directory.
  3. Edit the new file to reflect the content you desire, remembering to respect Guideline #5

Guideline #10

As of Shield v15 you can now use the WP filter provided to allow you to store templates in any location, not only in your themes directories. This assumes you are a PHP developer and understand how to use WP hooks and filters.

The WordPress filter in this case is: 'shield/custom_template_dirs'

To use this filter, the following requirements apply:

  • An array of strings is passed to this filter which contains all available paths to Shield template directories.
  • The callable function to attach to this filter must return an array. If not, the plugin will generate a fatal PHP type error.
  • Simply add the path to your custom template directory, to this array. This could be in a plugin or elsewhere.
  • You will then be able to add customised templates to this new directory, just as you would if it were in your theme directory as outlined in the guidelines above.