Overview
Willow intentionally uses non-PHP templates, using a .willow extension instead – there are two main reasons why:
- It is explicitly clear that these templates are only for use by Willow – they will be ignored by most other applications
- They are not PHP files, so it is not possible to place standard PHP inside them – which ensures a clean separation of logical concerns.
Willow templates are designed to be added to a theme, but can also be pushed in from plugins – there are several requirements that need to be met to make this work correctly, this article will show a few real-life examples.
Willow looks for templates which have a .willow extension – and they cannot contain plain PHP nor the comment block required to register new templates – so instead, Willow provides two filters to control native and custom templates.
Native Templates
Native templates are ones which WordPress understands within the scope of the template hierarchy – common examples are index.php for the blog, frontpage.php for the frontpage, archive.php for a specific list of posts, etc.
Custom templates are anything that is added outside of the scope of WordPress native templates – you can choose any file name and add unlimited custom templates, and for those reasons it’s good to have this planned before you start to reduce redundancy and to maintain a standardized approach and location.
As mentioned, Willow will only parse templates with a .willow extension – so we need to convert the expected native templates to match – this is achieved using the first of two view filters: willow/view/native – templates will also have to be placed inside the library/view directory – from the root of the active theme
Here is an example from the config file of our standard Willow child theme:
Note that we need to pass the template value as well as both function and argument values in an array of arrays – these are parsed in a hierarchical order, where the list if iterated over until the first positive matching condition is met – the matching template value is then parsed back to WordPress.
The function and argument values are passed to a simple “is” check – for example when the argument post is passed to the function is_singular this will return true when those same conditions are met in the WordPress template hierarchy check – namely, on singular post views.
In order to fully understand how this template logic is applied, check out the filter class in the repo.
Custom Templates
WordPress custom templates are a great developer tool – and they tie in perfectly with ACF groups to allow for custom data models and front-end views.
Custom templates are selectable in the admin via the Page Attributes panel, but we also need to filter our new templates into the WordPress template hierarchy, so that they are found and used correctly on the frontend – Willow also provides a simple filter process to achieve this.
The examples below shows how we can add one or multiple custom templates at the same time, via the filter willow/view/custom
Single Custom Template:
Multiple Custom Templates:
The code snippet above should be run from your active theme ( or from a plugin, following the instructions below ) to register the new custom templates, which will need to be placed in the library/view folder.
Plugin Templates
Adding custom templates from plugins is also possible, and in some cases make sense when, for example the plugin provides a new feature such as a login page or member list, which requires a custom template from the front-end.
In order to tell Willow that we are trying to add a template from a plugin, we also need to pass the class name in to the array we send to the registration filter – the example below shows how.
It is important to remember that in the same way that we require templates to be in a specific location when we add them from a theme – library/view – this is also expected when adding from a plugin – but Willow also require a few additional features to make this work.
The reference class will also require a static method called get_plugin_path which will validate the existence of the template file when checked – you can see a simple example of such a method inside the main plugin.php class in Willow.
The following examples from our WP User plugin, shows how we add a custom template and instruct Willow to load this from the plugin files, over the active theme.
Helper
The helper function get() is a lookup method, which prioritizes child theme over parent theme, and both over any plugin – this means that any file can be referenced and replaced simply from the child theme, just by giving it the same name and placing it in the same location within the theme – you can see the code in action here.
Server Level Protection
When the Willow plugin is activated, it updates the .htaccess file in the root of WordPress to protect direct read access to .willow file extensions – this means that they are not directly viewable – returning a 403 error – like PHP, they are designed to be parsed ( by PHP ) – and return HTML.