Willow

File Structure

The location and structure of certain files are very important to how Willow works, so understanding the lookup process is equally important.
Version 1.4.8
Latest Changes:

* New: html_entity_decode filter


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.


Naming Conventions

When a template calls a Willow – for example

{~ post~title ~}

Willow will look for configuration settings in the following locations, in the following order:

  • wp-content/theme/child/library/willow/post/post~title.php
  • wp-content/theme/child/library/willow/post/post.php
  • wp-content/theme/child/library/willow/global.php
  • wp-content/theme/parent/library/willow/post/post~title.php
  • wp-content/theme/parent/library/willow/post/post.php
  • wp-content/theme/parent/library/willow/global.php
  • wp-content/plugin/EXTENDED_PLUGIN/library/willow/post/post~title.php
  • wp-content/plugin/EXTENDED_PLUGIN/library/willow/post/post.php
  • wp-content/plugin/EXTENDED_PLUGIN/library/willow/global.php

Each time a file is successfully found, its data is gathered and merged into a single data array

There are additional lookup options and checks not listed above, but this gives a good general idea of the order and process


Lookup Process

When a template calls a willow – for example {~ post~title ~} – Willow will firstly read any configuration passed inside template arguments, and then try to locate any relevant configuration files – it looks in defined places, in a defined order, limiting it’s search by the define context and task – in this case post + title

Willow will search for configuration files globally, contextually and also based on context + task – searching defined locations in a set order:

  • Child Theme ( if any and active )
  • Parent Theme ( if any and active – if not using child/parent pair, this will be the current active theme )
  • Extensions ( configuration loaded via extended contexts who have defined a lookup value )
  • Willow – currently, only the global.php configuration file is shipped with Willow

If there are multiple context~task files, for example a context/global.php in Willow and also one in the child theme – then both files are loaded and the values are merged, with the later loaded ( in this case, higher priority – Child ) values being taken over the first loaded values – so if Willow defines debugging as false, but the same value is set to true in the child configuration file, then the child value will be used.

In order to understand the finer details of how load priority works, it would make sense to study the config file directly.


Extending lookup locations

As Willow contexts can be extended, it is also required to allow plugins to extend the configuration lookup locations, this can be achieved by adding the lookup parameters to the context extension callback, as shown in the following example:

In this example, we are telling Willow to also look in the path wp-content/plugin/q-user/library/willow/ when running checks for willow configuration files.