Data fetching and returning

Context and Task

Context and task are two key aspects of Willow, they are equivalent to Class and Method in PHP and all Willows retrieve data from a single public php method within a class

Willow comes with the following "contexts", which can be extended via plugins, themes or external libraries

• action
• extension
• group
• media
• meta
• module
• navigation
• partial
• post
• taxonomy
• ui
• user
• widget
• wordpress

There use in most cases is totally liberal, as such you can extend the ui context to return data related to taxonomies or wordpress - the available contexts are provided as a broad group of labels by which to group similar functions, rather than as rigid constraints.

The exceptions to the above rule are the action, group and partial contexts which are designed for specific use-cases:

Action

WordPress actions are perhaps what make it such a popular and flexible tool ( it's certainly not because of its beautiful code! ), as they allow developers to change many aspects of how data stored in the database is retrieved and displayed.

Actions are also required to load in assets or to hook callbacks, as such they are a required part of templating - here is a simple example of how WIllow can be used to call the wp_head action

{~ action~wp_head ~}

WordPress actions might return data, such as loading assets, Willow allow this behaviour by wrapping the action callback in output buffering, capturing the returned data and adding it to the template in the defined spot where the action is called.

Group

The group context was designed to work with ACF groups, returning data in the correct format for rendering single fields and repeater fields, but this functionality is only available if the Q Plugin is also installed and active:

<div class='col-12 card-columns'>
	{~ group~frontpage_feature {+ [a] 
		config = debug: false & 
		markup = template: " 
		{@ {: frontpage_feature :}
		<div class='card'>
			<div class='card-body'>
				<h5 class='card-title'>{{ title }}</h5>
				<p class='card-text'>{{ content }}</p>
				<a href='{{ url }}' class='btn btn-primary'>More</a>
			</div>
		</div>
		@}"
	+} ~}
</div>

The Group context can still be extended like any other context.

Partial

Partials are simply re-usable collections of html, such as a button or a call to action, they cannot contain other tags and are not parsed by Willow before being rendered.

Partials are stored as text files with a .willow extension - here is an example from one of our Q Themes:

{> search_trigger <}

library/view/context/parent/partial/partial~search_trigger.willow

<div class="row ml-0">
	<div class="col-12 list-group list-group-flush border-top">
		<div class="list-group-item">
			You can also
			<a 
				class="ml-1 btn btn-primary text-white p-2 q-scroll-top" 
				data-toggle="collapse" 
				data-target="#search_content"
				aria-controls="search_content" 
				aria-expanded="false" 
				aria-label="Search navigation"
				href="#">
				Search our Work
			</a>
		</div>
	</div>
</div>

When you call a Partial, Willow simply looks for a matching stored configuration file and returns the data, as shown below:

file: q-willow/library/context/partial.php

public static function get( $args = null ) {

	return core\config::get([ 'context' => $args['context'], 'task' => $args['task'] ]);

}

If not matching context/task pair is found, no data will be returned and the partial will render nothing, being removed from the template by the parser cleanup process.

The location of the partial file is important due to how the configuration lookups work - read more

Context Extension

Most Willow contexts include only one task, a getter which looks for a matching context/task ( class::method ) in the Q plugin - take the following example:

{~ post~title ~}

This Willow will hit the post context and look for a task title, the process for that look up works in the following order:

1. Check for a registered extension, with a class post and a public method title
2. Check for a public method within the base post class with a method title
3. Check for a matching getter method in the Q plugin i.e. method_exists( '\q\get\post', $method )

The following example shows how to extend the ui context ( it would work for any other context )

<?php

namespace q\theme\context;

// willow ##
use q\willow; // to extend ##

// register class to render ##
\q\theme\context\ui::run();

class ui {

	public static function run( $args = null ) {

		// check for willow ##
		if( ! class_exists( 'q_willow' ) ){ return false; }

		$class = new \ReflectionClass( __CLASS__ );
		$methods = $class->getMethods( \ReflectionMethod::IS_PUBLIC );
		foreach( $methods as $key ){ $public_methods[] = $key->name; } // match format returned by get_class_methods() ##

		// register new class methods ##
		\add_action( 'after_setup_theme', function() use ( $public_methods ) {
			willow\context\extend::register([ 
				'context' 	=> str_replace( __NAMESPACE__.'\\', '', __CLASS__ ), 
				'class' 	=> __CLASS__,
				'methods' 	=> $public_methods // public only 
			]);
		}, 2 );

	}



    /**
     * Example extension method
     *
     * @param       Array       $args
     * @since       4.1.0
     * @return      Array
     */
    public static function hello( $args = null ) {

		// define key + values ##
		return 
			[ 
				'data' => [ // 
					'0' => [
						'who' 	=> 'You',
						'time' 	=> rand(),
					],
					'1' => [
						'who' 	=> 'Me',
						'time' 	=> rand(),
					]
				]
			]
		;

	}
}