Willow

Data Fetching and Returning

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
Version 1.4.8
Latest Changes:

* New: html_entity_decode filter


Documentation about each release is updated as often as possible, but may lag behind the Master Branch or other generated documentation.

Featured Work
Quinta de Sant’Ana, Portugal
Quinta de Sant’Ana, Portugal

Quinta de Sant'Ana overlooks the picturesque village of Gradil with its cobbled streets, white washed houses and hospitable inhabitants.


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 actiongroup and partial contexts which are designed for specific use-cases:


Action

WordPress actions are perhaps what make it such a popular and flexible tool, as they provide developers with a simple and powerful way 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 facilitates 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 most single field types and repeater fields.

Group fields used along-side JSON formatted ACF configuration settings make for an extremely powerful and portable toolset for development – the ACF classes in Willow mean that little to zero additional data controllers are required between adding fields and rendering data in templates.

<div class='col-12 card-columns'>
	{~ group~frontpage_feature {+ [array] 
		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 scripts, normally plain html, which might render a button or a call to action, they cannot contain other Willow 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: willow/library/context/partial.php

public static function get( $args = null ) {

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

}

If no 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 and name of the partial file is important due to how the configuration lookups work


Dot Notation

When data returned from a context/task includes arrays of arrays, variables can be accessed directly using dot notation – take the following example which returns both all the commits and also the latest commit version from an ACF group called work_commit

This Willow is stored in it’s own configuration file, located at library/view/context/parent/group/group~work_commit.willow

<span class="ml-1">
	<a 
		class="p-1 p-sm-2 btn btn-primary" 
		href="#commits" 
		data-modal-toggle='modal' 
		data-modal-size="modal-lg" 
		data-modal-title='Commit History' 
		data-modal-body="<table class='table'><thead><tr><th scope='col'>Release</th><th scope='col'>Details</th></tr></thead><tbody>{@ {: work_commit :} <tr><td>{{ work_commit_version }}</td><td>{{ [e] work_commit_message }}</td></tr> @}</tbody></table>" data-modal-target='#q_modal'>
			Version: {{ work_commit.0.work_commit_version }}
	</a>
</span>

The Willow is called simply from the template using the following tag:

{~ group~work_commit ~}

Note that the latest version is available via Version: {{ work_commit.0.work_commit_version }}

Another example, again pulling data from ACF – this time from a field group called frontpage_work

configuration sits in its own file at library/view/context/parent/group/group~frontpage_work.willow

<h5 class="row"><div class="col-12 my-3 ml-3">{{ frontpage_work_title }}</div></h5>

<div class="card mb-3">
	<a href="{{ frontpage_work_top.post_permalink }}">
		<img class="fit card-img-top lazy" style="max-height: 200px" src="" 
			data-src="{{ frontpage_work_top.src {+ [array] config->handle = square-sm +} }}" />
	</a>
	<div class="card-body">
		<h5 class="card-title">
			<a href="{{ frontpage_work_top.post_permalink }}">
				{{ frontpage_work_top.post_title }}
			</a>
		</h5>
		<p class="card-text">frontpage_work_top.post_excerpt</p>
		<span class="badge badge-pill badge-primary ml-1">
			{{ frontpage_work_top.category_name }}
		</span>
	</div>
</div>

The Willow is called from the template using:

{~ group~frontpage_work ~}

One of the fields defined in the field group is named frontpage_work_top and is defined as a Post Object type – the data formatter in Willow has converted the returned Object into a dot notated array, with each field value available at frontpage_work_top.post_excerpt or frontpage_work_top.post_title – these can then be used directly as Willow variables – such as {{ frontpage_work_top.post_excerpt }}


Context Extension

Most Willow contexts include only one task, a getter which looks for a matching context/task ( class::method ) in the 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( '\willow\get\post', $method )

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

This can be rendered from the template using

{~ ui~hello ~}

With the configuration in a willow file located at library/view/context/parent/ui/ui~hello.willow

{@ {: data :}
        <div class="col-12">YOU are {{ who }} and the time is {{ time }}</div>
@}