Terrific Twig
, (*1)
Extension to embrace the Terrific frontend methodology in Twig., (*2)
Currently it adds a custom component tag to Twig which mimics Nitro's handlebars helper., (*3)
Installation
Using composer:, (*4)
$ composer require namics/terrific-twig
Requirements
The following versions of PHP are currently supported., (*5)
- ~~PHP 5.4~~ (Deprecated. Builds are failing since the tests are relying on
::class.)
- PHP 5.5
- PHP 5.6
- PHP 7
- HHVM
Setup
Step 1: Implement TemplateInformationProvider, (*6)
class TemplateInformationProvider implements TemplateInformationProviderInterface
{
public function getPaths()
{
return []; // List of path where Terrific Components can be found, e.g. (/var/www/example.com/frontend/components)
}
public function getFileExtension()
{
$fileExtension = 'html.twig';
return $fileExtension;
}
}
Step 2: Implement ContextProviderInterface, (*7)
class ContextProvider implements ContextProviderInterface
{
public function compile(Twig_Compiler $compiler, Twig_Node $component, Twig_Node $dataVariant, $only) {
// ...
}
}
Step 3: Add TerrificLoader, (*8)
$loader = ...;
$chain = new Twig_Loader_Chain([$loader, new TerrificLoader(new TemplateInformationProvider)]);
$twig = new Twig_Environment($chain);
Step 4: Add TerrificExtension, (*9)
$twig = new Twig_Environment($chain);
$twig->addExtension(new TerrificExtension(new ContextProvider));
Step 5: Profit!, (*10)
Usage
{# Includes the component, component's default data is merged with the context #}
{% component 'Example' %}
{# Includes the component, the default data is injected as a child context #}
{% component 'Example' only %}
{# Includes the component, but a variantion of the component data is merged with the context #}
{% component 'Example' 'example-variant' %}
{# Includes the component, but a variantion of the component data is injected as a child context #}
{% component 'Example' 'example-variant' only %}
{# Includes the component, data object is merged with the context #}
{% component 'Example' { title: 'Inject an Object' } %}
{# Includes the component, data object is injected as a child context #}
{% component 'Example' { title: 'Inject an Object' } only %}
Documentation
Extension
The extension provides terrific extensions to Twig. Currently the extension provides the ComponentTokenParser., (*11)
Token Parser
The token parser contains the parsing step for the component tag. It tokenizes the stream to different nodes (component, data) and an attribute (only)., (*12)
The functionality is based on the fantastic Twig_TokenParser_Include., (*13)
Node
The Node compiles the tokenized tag to PHP. To see some of the output, check the ComponentTest., (*14)
Loader
The TerrificLoader extends the Twig_Loader_Filesystem as it actually loads templates from the filesystem. An implementation of TemplateLocatorInterface provides the paths where the loader should search for templates., (*15)
An implementation of TemplateInformationProviderInterface should return a list of paths where templates live. These should be in the form of ['frontend/components/atoms', 'frontend/components/molecules', 'frontend/components/organisms']. The component directory will be provided by the TerrificLoader (Example/example.[ext])., (*16)
Context Provider
This is the tricky part. An implementation of ContextProviderInterface decides which data will be made available to Twig templates.
TODO: More on that., (*17)
ConfigReader
Reads nitro's config.json and parses essential information such as the component paths and file extension., (*18)
Credits
This project is partially sponsored by Namics., (*19)
Wallogit.com
