File Structure

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

Data is gathered greedily, but merged logically - Willow out-of-the-box will search for configuration settings within itself, within a parent or child theme - in that order and will merge all collected data, prioritizing the later over the former, while trying to ensure that all required configuration settings are present - from the simple base model found in the file library/willow/global.php View

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/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/plugin/EXTENDED_PLUGIN/library/willow/post/post~title.php
• wp-content/plugin/EXTENDED_PLUGIN/library/willow/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 )

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:

$ui = new ui();
$ui->hooks();

class ui {
	
	function __construct(){}

	function hooks() {

		\add_action( 'init', [ $this, 'willow' ], 10 );

	}

	function willow(){

		if ( ! function_exists( 'willow' ) ) { return false; } 

		// register extension ##
		willow()->extend->register([
			'context' 	=> str_replace( __NAMESPACE__.'\\', '', __CLASS__ ), 
			'class' 	=> 'q\theme\child\context\navigation', // force context class ##
                        'lookup'	=> \q_user::get_plugin_path( 'library/willow/' ), // allow for extended .willow lookups ##
			'methods' 	=> 'public' // public only -- default ##
		]);

	}

}

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.