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


This is an advanced feature and without due care, you may break functionality of your Shield plugin. Our support team will endeavour 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.


There is no way around this - you must store your custom templates in your theme directory.


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 page 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