Helpers
Helpers
Helpers are extensions to Plates PHP that provide additional functionality to your templates. Helpers are available via $this within any project phtml file. Tapestry comes with two helpers built in and it is easy to extend Tapestry by adding your own.
Site Variables Helper
The site variables helper provides an interface by which you can access site variables, its usage is:
<?= $this->site(string $key, mixed $default = null) ?>The helper will return the configured site variable for the given $key, or $default if the site variable is not found. In cases where the site variable is not found and you do not provide a default fall back, it will return null.
The source code for the site variable helper can be found in /src/Plates/Extensions/Site.php.
URL Helper
The URL helper is a wrapper for the Url entity class. It requires that the url site variable be set so that it may return absolute urls to its given input.
It's usage is:
<?= $this->url(string $uri = '') ?>It will append the provided $uri to the configured url site variable, producing an absolute url to the location you provide.
The source code for the URL helper can be found in /src/Plates/Extensions/Url.php.
Content Helpers
While certain variables such as $title are made available to templates by default, it can be difficult to identify certain properties of a page without placing extensive PHP code within your template, often leading to a mess of duplication.
To assist with this Tapestry provides a number of content helper functions which can be accessed from $this, or from any file within a collection array.
getFile()
This method will return the internal Tapestry\Entities\File class for the page in question; this is useful if you are writing advanced functionality and need to be able to modify the File class directly.
getData($key, $default = null)
This method has a mixed return depending upon the value of the file's data found matching the $key. In addition to values that Tapestry sets, any front matter that you set for the file will be made available via this method.
By default if a data value is not found matching the provided $key, this method will return null
getPermalink()
This method will return the compiled permalink for the file in question.
getUrl()
This method will return the compiled permalink for the file in question as an absolute url. This uses the URL Helper and as such requires the url site variable be set.
getDate()
This method will return an instance of DateTime with the date value of the file in question. Unless you have set the date value via front matter or within the filename this will equal the last modified timestamp.
taxonomyList($name)
This method will return an array containing taxonomy defined for $name.
e.g. <?php= $this->taxonomyList('tags') ?>
getContent()
This method will return the content for the file in question. If the file has yet to be rendered this will return the files content directly from disk.
isPaginated()
This method will return a boolean value telling you if the file in question contains paginated data. If true is returned you can then use the getData method to obtain the associated Paginator.
hasPreviousNext()
This method will return a boolean value telling you if the file in question contains $previous_next data.
If true is returned you can then use the getData method to obtain the associated $previous_next value.
isDraft()
This method will return a boolean value telling you if the file in question is a draft or not.
getExcerpt($limit = 50, $more = '…')
This method will return an excerpt of the content up to a maximum of $limit characters with $more appended.
The character length of this methods output doesn't always match the $limit, but will never exceed it, this is because it generates excerpts with full words.
Adding your own helpers
Adding Helpers to Tapestry is done on a per site basis by writing an extension to the Plates engine and loading it via the project Kernels register method.
To provide an example: The source code of this documentation contains the following Plates Extension:
<?php namespace TapestryCloud\Lib;
use League\Plates\Engine;
use League\Plates\Extension\ExtensionInterface;
class TestPlatesExtension implements ExtensionInterface
{
public function register(Engine $engine)
{
$engine->registerFunction('test', [$this, 'test']);
}
public function test()
{
return 'hello world!';
}
}This simple example renders hello world! within the page template in place of <?= $this->test() ?>. To load the extension the kernel gets the Tapestry\Plates\Engine from Tapestry's IoC and injects a new instance of TestPlatesExtension into it via the engines loadExtension method. See below for the actual code:
<?php namespace TapestryCloud;
use Tapestry\Modules\Kernel\KernelInterface;
use Tapestry\Plates\Engine;
use Tapestry\Tapestry;
use TapestryCloud\Lib\TestPlatesExtension;
class Kernel implements KernelInterface
{
private $engine;
private $container;
public function __construct(Tapestry $tapestry)
{
$this->container = $tapestry->getContainer();
$this->engine = $this->container->get(Engine::class);
}
/**
* This method is executed by Tapestry when the Kernel is registered.
*
* @return void
*/
public function register()
{
include (__DIR__ . '/lib/TestPlatesExtension.php');
$this->engine->loadExtension($this->container->get(TestPlatesExtension::class));
}
/**
* This method of executed by Tapestry as part of the build process.
*
* @return void
*/
public function boot()
{
// ...
}
}Both examples above are included within the source code for this documentation and if you look at the source for this page you will notice <?= $this->test() ?> was used above to display its example output.