Permalink
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
316 lines (251 sloc) 12.1 KB
---
layout: documentation
title: Helpers
---
<h2>Helpers</h2>
<ul>
<li><a href="#helpers">Helpers</a>
<ul>
<li><a href="#site-variables-helper">Site Variables Helper</a></li>
<li><a href="#url-helper">URL Helper</a></li>
</ul>
</li>
<li><a href="#content-helpers">Content Helpers</a>
<ul>
<li><a href="#content-helpers-getFile">getFile()</a></li>
<li><a href="#content-helpers-getData">getData($key, $default = null)</a></li>
<li><a href="#content-helpers-getPermalink">getPermalink()</a></li>
<li><a href="#content-helpers-getUrl">getUrl()</a></li>
<li><a href="#content-helpers-getDate">getDate()</a></li>
<li><a href="#content-helpers-taxonomyList">taxonomyList($name)</a></li>
<li><a href="#content-helpers-getContent">getContent()</a></li>
<li><a href="#content-helpers-isPaginated">isPaginated()</a></li>
<li><a href="#content-helpers-hasPreviousNext">hasPreviousNext()</a></li>
<li><a href="#content-helpers-isDraft">isDraft()</a></li>
<li><a href="#content-helpers-getExcerpt">getExcerpt()</a></li>
<li><a href="#content-helpers-getEnvironment">getEnvironment()</a></li>
</ul>
</li>
<li><a href="#adding-helpers">Adding your own helpers</a></li>
</ul>
<hr/>
<h3><a name="helpers" href="#helpers">Helpers</a></h3>
<p>
Helpers are <a href="http://platesphp.com/engine/extensions/" target="_blank">extensions to Plates PHP</a> that
provide additional functionality to your templates. Helpers are available via <code class="language-php">$this</code>
within any project <code>phtml</code> file. Tapestry comes with two helpers built in and it is easy to extend
Tapestry by adding your own.
</p>
<h4><a name="site-variables-helper" href="#site-variables-helper">Site Variables Helper</a></h4>
<p>
The site variables helper provides an interface by which you can access <a href="<?= $this->site('documentation/site-variables') ?>">site variables</a>,
its usage is:
</p>
<pre class="language-php"><code>&lt;?= $this->site(string $key, mixed $default = null) ?&gt;</code></pre>
<p>
The helper will return the configured site variable for the given <code class="language-php">$key</code>,
or <code class="language-php">$default</code> 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 <code class="language-php">null</code>.
</p>
<p>
The source code for the site variable helper can be found in <a
href="https://github.com/tapestry-cloud/tapestry/blob/master/src/Plates/Extensions/Site.php" target="_blank">/src/Plates/Extensions/Site.php</a>.
</p>
<h4><a name="url-helper" href="#url-helper">URL Helper</a></h4>
<p>
The URL helper is a wrapper for the
<a href="https://github.com/tapestry-cloud/tapestry/blob/master/src/Entities/Url.php" target="_blank">Url entity class</a>.
It requires that the <code>url</code> site variable be set so that it may return absolute urls to its given input.
</p>
<p>
It's usage is:
</p>
<pre class="language-php"><code>&lt;?= $this->url(string $uri = '') ?&gt;</code></pre>
<p>
It will append the provided <code class="language-php">$uri</code> to the configured <code>url</code> site variable,
producing an absolute url to the location you provide.
</p>
<aside class="notice red">
<p>
<strong>Note:</strong> If the URL helper is used and the <code>url</code> site variable is not defined, Tapestry will return an error and exit.
</p>
</aside>
<p>
The source code for the URL helper can be found in <a
href="https://github.com/tapestry-cloud/tapestry/blob/master/src/Plates/Extensions/Url.php" target="_blank">/src/Plates/Extensions/Url.php</a>.
</p>
<hr/>
<h3><a name="content-helpers" href="#content-helpers">Content Helpers</a></h3>
<p>
While certain variables such as <code>$title</code> 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.
</p>
<p>
To assist with this Tapestry provides a number of <em>content helper functions</em> which can be accessed from
<code class="language-php">$this</code>, or from any file within a collection array.
</p>
<aside class="notice blue">
<p>
Content helpers are provided by the
<a href="https://github.com/tapestry-cloud/tapestry/blob/b9d7e3ce5c0e24809cc7e07591572c171c788ae1/src/Entities/ViewFileTrait.php" target="_blank">ViewFileTrait</a>.
</p>
</aside>
<h4><a name="content-helpers-getFile" href="#content-helpers-getFile">getFile()</a></h4>
<p>
This method will return the internal
<a href="https://github.com/tapestry-cloud/tapestry/blob/b9d7e3ce5c0e24809cc7e07591572c171c788ae1/src/Entities/File.php" target="_blank">Tapestry\Entities\File</a>
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.
</p>
<h4><a name="content-helpers-getData" href="#content-helpers-getData">getData($key, $default = null)</a></h4>
<p>
This method has a mixed return depending upon the value of the file's data found matching the <code class="language-php">$key</code>.
In addition to values that Tapestry sets, any <a href="<?= $this->url('documentation/front-matter') ?>">front matter</a>
that you set for the file will be made available via this method.
</p>
<p>
By default if a data value is not found matching the provided <code class="language-php">$key</code>, this method will return <code class="language-php">null</code>
</p>
<h4><a name="content-helpers-getPermalink" href="#content-helpers-getPermalink">getPermalink()</a></h4>
<p>
This method will return the compiled permalink for the file in question.
</p>
<h4><a name="content-helpers-getUrl" href="#content-helpers-getUrl">getUrl()</a></h4>
<p>
This method will return the compiled permalink for the file in question as an absolute url. This uses the
<a href="#url-helper">URL Helper</a> and as such requires the <code>url</code> site variable be set.
</p>
<h4><a name="content-helpers-getDate" href="#content-helpers-getDate">getDate()</a></h4>
<p>
This method will return an instance of <code>DateTime</code> 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.
</p>
<h4><a name="content-helpers-taxonomyList" href="#content-helpers-taxonomyList">taxonomyList($name)</a></h4>
<p>
This method will return an <code>array</code> containing taxonomy defined for <code class="language-php">$name</code>.
</p>
<p>
e.g. <code class="language-php">&lt;?php= $this->taxonomyList('tags') ?&gt;</code>
</p>
<h4><a name="content-helpers-getContent" href="#content-helpers-getContent">getContent()</a></h4>
<p>
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.
</p>
<h4><a name="content-helpers-isPaginated" href="#content-helpers-isPaginated">isPaginated()</a></h4>
<p>
This method will return a boolean value telling you if the file in question contains paginated data. If
<code class="language-php">true</code> is returned you can then use the <a href="#content-helpers-getData">getData</a>
method to obtain the associated Paginator.
</p>
<h4><a name="content-helpers-hasPreviousNext" href="#content-helpers-hasPreviousNext">hasPreviousNext()</a></h4>
<p>
This method will return a boolean value telling you if the file in question contains
<code class="language-php">$previous_next</code> data.
</p>
<p>
If <code class="language-php">true</code> is returned you can then use the <a href="#content-helpers-getData">getData</a>
method to obtain the associated <code class="language-php">$previous_next</code> value.
</p>
<aside class="notice blue">
<p>
Both the <code>isPaginated()</code> and <code>hasPreviousNext()</code> method refer to pagination functionality.
</p>
<p>
For further information visit the <a href="<?= $this->url('documentation/collections') ?>/#pagination">pagination
section</a> of the collections chapter.
</p>
</aside>
<h4><a name="content-helpers-isDraft" href="#content-helpers-isDraft">isDraft()</a></h4>
<p>
This method will return a boolean value telling you if the file in question is a draft or not.
</p>
<h4><a name="content-helpers-getExcerpt" href="#content-helpers-getExcerpt">getExcerpt($limit = 50, $more = '&amp;hellip;')</a></h4>
<p>
This method will return an excerpt of the content up to a maximum of <code>$limit</code> characters with <code>$more</code> appended.
</p>
<p>
The character length of this methods output doesn't always match the <code>$limit</code>, but will never exceed it, this is because
it generates excerpts with full words.
</p>
<h4><a name="content-helpers-getEnvironment" href="#content-helpers-getEnvironment">getEnvironment()</a></h4>
<p>
This method will return a string value equal to the environment at time of execution.
</p>
<hr/>
<h3><a name="adding-helpers" href="#adding-helpers">Adding your own helpers</a></h3>
<p>
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 <a href="<?= $this->url('documentation/kernel') ?>">Kernels</a> register method.
</p>
<aside class="notice blue">
<p>
More in-depth details on writing extensions to the PHP Plates engine can be found
<a href="http://platesphp.com/engine/extensions/" target="_blank">here</a>.
</p>
</aside>
<p>
To provide an example: The source code of this documentation contains the following Plates Extension:
</p>
<pre class="language-php"><code>&lt;?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!';
}
}</code></pre>
<p>
This simple example renders <code><?= $this->test() ?></code> within the page template in place of
<code class="language-php">&lt;?= $this->test() ?&gt;</code>. To load the extension the kernel gets the
<code>Tapestry\Plates\Engine</code> from Tapestry's IoC and injects a new instance of <code>TestPlatesExtension</code>
into it via the engines <code>loadExtension</code> method. See below for the actual code:
</p>
<pre class="language-php"><code>&lt;?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()
{
// ...
}
}</code></pre>
<p>
Both examples above are included within the
<a href="https://github.com/tapestry-cloud/tapestry-cloud-src" target="_blank">source code</a> for this documentation
and if you look at the
<a href="https://github.com/tapestry-cloud/tapestry-cloud-src/blob/master/source/documentation/helpers.phtml#L114" target="_blank">source</a>
for this page you will notice <code class="language-php">&lt;?= $this->test() ?&gt;</code> was used above to display its example output.
</p>