Willow

Templates

Willow uses it's own proprietary file extension - .willow - and provides two filters to register custom and native templates with WordPress for admin selection and frontend rendering.
Version 2.1.1
Latest Changes:

* Update: moved all object instatiation to plugin hook - all objects are stored in a global getters and setters and accessed via willow() function.


Documentation about each release is updated as often as possible, but may lag behind the Master Branch or other generated documentation.

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


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.