Adding Willow templates to WordPress

Willow is a Template Engine built for WordPress, this article shows you how to create and register templates with a .willow extension for admin selection and frontend rendering.

Adding Willow templates to WordPress

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


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.

That’s it – happy coding 🙂

Gist List


No comments on this article yet.

Add a Comment

Your email address will not be published.

These HTML tags work: <a href=""> <code> <strong> <pre>


Our Services
Validate your ideas before diving in. Consultancy
Dig deep, audit your data, prepare for action Discovery
Get everything in shape to smooth the project path. Shaping
Let us help you realize your imagination Design
Rock-solid WordPress tools, built to last. Development
Without water, the garden will not grow. Support

Quinta de Sant’Ana, Portugal
Quinta de Sant’Ana, Portugal

Quinta de Sant'Ana overlooks the picturesque village of Gradil with its cobbled streets, white washed houses and hospitable inhabitants.

Projects: View All or

Willow is a Logic~less Template Engine built for WordPress. Willow plays nicely with ACF, is quick to learn and developer-focused.

Releases: View All or