Configuration

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

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:

// return an array ##
return [ 'global' 			=> [

	'config'				=> [
		
		// run ALL contexts ##
		'run' 				=> true,
		
		// ALL context debugging ##
		'debug'				=> false,

		// return strategy
		'return'       	 	        => 'echo'

	],

]];

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:

// filter Willow Config ##
// Priority -- Q = 1, Q Plugin = 10, Extension = 10, Parent Theme = 100, Child Theme = 1000 ##
\add_filter( 'q/willow/config/load', 
	function( $args ){
		$source = null; // context source ##
		return self::filter( $args, $source );
	}
, 1, 1 );

\add_filter( 'q/willow/config/load', 
	function( $args ){
		$source = 'plugin'; // context source ##
		return self::filter( $args, $source );
	}
, 10, 1 );

\add_filter( 'q/willow/config/load', 
	function( $args ){
		$source = 'extend'; // context source ##
		return self::filter( $args, $source );
	}
, 50, 1 );
		
\add_filter( 'q/willow/config/load', 
	function( $args ){
		$source = 'parent'; // context source ##
		return self::filter( $args, $source );
	}
, 100, 1 );

\add_filter( 'q/willow/config/load', 
	function( $args ){
		$source = 'child'; // context source ##
		return self::filter( $args, $source );
	}
, 1000, 1 );

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.