Willow

Configuration

Willow was designed to meet several specific front-end and back-end developmental needs. 
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.


Designed Usage

Willow was designed to meet several specific developmental needs – the key aims are:

  • Simplify process for UI developers who are not comfortable moving between PHP and html, by shifting all logic away from templates
  • Provide global and granular control over display and format of data using template and file-based configuration options
  • Be portable between environments, applications and projects
  • Be lightweight and fast-loading ( via caching and reducing db requests for data fetching )

Template Configuration

The simplest way to pass configuration options to willows is via template arguments, which are passed inside the argument tag, as shown in the following simple example:

Pass html markup with variable to willow

{~ ui~example {+ "<div class='row'>{{ variable }}</div>" +} ~}

The results are only rendered if the php function ( ui::example in this case ) is found, is public, returns data and the data is in the correct format – which is an array of strings or an array of strings and arrays ( only indexed arrays are accepted, keys don’t need to be sequential, but in some cases this will make things simpler ) – Read more about data collecting

Template based configuration is easier and quicker to use and takes priority over an file-based configuration, but suffers from several downsides:

  • It is not as portable or re-usable, as each template which re-uses the same configuration will need to include the same tag, means changes are slower and more prone to errors
  • Templates can quickly become muddled and less readable, reducing the UX of the UI developer.

In many cases, configuration starts in templates and then as it grows, becomes more stable or is required on multiple templates, moved out of its inline form into file-based configuration.


File-Based Configuration

Willow loads context files, based on tags found in the current template – how these files are loaded and their contents merged forms the basis of the file-based configuration system and is important to understand.

The only configuration file shipped with Willow is located at library/view/context/global.php – this includes top level settings, as follows:

Configuration files are loaded in order as follows:

  1. Child Theme ( if any and active )
  2. Parent Theme ( if any and active – if not using child<>parent pair, this will be the current active theme )
  3. Extensions ( configuration loaded via extended contexts who have defined a lookup value )
  4. Plugin ( in the current set-up, this is the Q plugin, if active )
  5. Willow – currently, only the global.php configuration file is shipped with Willow

Configuration is loaded in a contextual sense, based on tags parsed from the current template – debugging options control if this is stored in the wp_options table of the application database, as a transient – or pulled directly from the files ( which is presumably slower, but more direct for debugging purposes, as it avoid any caching ).

The filters that load configuration are located in “library/core/config.php” and run as follows:

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