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 );

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