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 – note that extension classes can specify the context they wish to extend, but can have matching class names if used within namespaces ) 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 any 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, which means changes are slower and more prone to errors.
- Templates can quickly become muddled and less readable, reducing the developer experience.
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, reducing redundancy and increasing portability.
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/willow/global.php – this includes top level settings, as follows:
Configuration files are loaded in order, as follows:
- 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 )
Plugin ( in the current set-up, this is the Q plugin, if active )- 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 normally 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 willow/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.