ldf / gutenberg
PHP based templa
Requires
- php: >=7.1
Requires (Dev)
- fzaninotto/faker: ~1.7
- mockery/mockery: ~1.1.
- phpmetrics/phpmetrics: dev-master
- phpunit/phpunit: ~7
This package is auto-updated.
Last update: 2024-04-28 21:03:46 UTC
README
Gutenberg is a view renderer written in PHP and based on the fact that view must be totally separated from logic.
This system will allow you to easily substitute some variables for values and compose views in an easy way for a CMS, but you will not find control structures such as if/ese statements or even template inheritance. If you are looking for this kind of feature, I recommend to have a look at Blade or Twig.
How to install
You can install Gutenberg with composer:
composer require ldf/gutenberg
Instantiate Gutenberg
Gutenberg is instantiated by a builder class called Gutenberg
:
$Gutenberg = Gutenberg::ForWorkspace('./path/to/templates');
By using the fluent api, you will be able to set up some extra behaviours. The following lines will build a Gutenberg object with Wipe Out mode enabled:
// Get the object $Gutenberg = Gutenberg::ForWorkspace('./path/to/templates') ->withWipeOut(); // Call the render function to get the rendered page return $Gutenberg->render('page', [ 'var1' => 'value1', 'var2' => 'value2', ]);
Template files
Template files are just .html files (as they are expected to contain just html with a couple of Guttemberg tweaks). They must be place in a workspace.
A workspace is essentially a path to a directory.
Templates are referenced by an id which, by convention, resolves to a file in the workspace.
For example, a template identified by myTemplate
will resolve to path ./workspace/myTemplate.html
and
another tempalte identified by partials/_widget
will resolve to path ./workspace/partials/_widget.html
- By the way, it is recommended that, by convention you prefix your partial files with underscore
_
(you may recognize this convention).
If you decide to an extension other than .html
for your templates, you can specify this as part of your
identifier with something like myTemplate.tpl
.
Keywords
Gutenberg provides some expressions to allow you to define some dinamic points in your templates.
Generally speaking
Expressions in Gutenberg are anything you place between double curly braces.
If you want to print double curly braces you must use the html entity instead:
The value of variable "myvar" is {{ myvar }} {{This will be displayed in the html.|;|
Variables
Variables will be refered as {{ varname }}
import
{{ import _partialTemplateId }}
Please, notice that in this case the Id begins with an underscore _
. This way Gutenberg knows that this template
is a partial template.
Partial templates, by convention must begin by underscore. Indeed, if they don't begin by underscore they import
expression will be ignored.
Also notice that you are already in a workspace, so you can not import templates from another workspace. This way you are forced to avoid cross dependencies.
wrapper
{{ wrapper tplname}}
We don't support inheritance -no, we don't like inheritance. Instead, you are able to wrap templates. Think of wrapping as a sort of reverse-import in which the wrapped template can define one -and only one- template to be wrapped.
When you use wrapping, the source code file must start exactly by the wrapper command.
Wrappers use the {{ content }}
mark to define the place were the inner template will be wrapped.
comments
{{-
(a.k.a X-Wing operator)
The rest of the line is a comment and will be ingored. For multiple-line comments you can send some X-Wing spaceships:
{{-
{{- This is a multi-line comment.
{{- You can use it as header of template files.
{{- Everything you write in a comment will be ignored and will not appear in the ouput.
{{-
<strong>
This will be rendered
</strong>
Now, be a good kid and go add some comments to your code.
Control structures
So, how can I add some structures such as if
/else
or foreach
? The answer is easy: you can't.
Logic should not be on your templates, so you must take care of passing exactly some ready-to-use substitution values.
Extra options
By using the builder, you will be able to configure some extra options
WipeOut
You can enable wipe out feature by calling withWipeOut
.
When Wipe out option is enabled any Gutenberg tag which is not recognized, e.g. {{ unknownVariable }}, will be cleaned from the template. An E_USER_WARNING level error will be raised.
$Gutenberg = Gutenberg::ForWorkspace('./path/to/templates') ->withWipeOut() ->get();
Extending Gutenberg's functionality.
Gutenberg provides a feature to add some custom compilers. This will allow you to create your own language expressions. You can add your own language expression calls by implementing ICompiler:
class MyCustomCompiler implements \Ldf\Gutenberg\ICompiler { public function compile(string $tpl) : string { ... } }
You can add as many custom compilers as you want.
Gutenberg::ForWorkspace('./FakeTemplates') ->addCustomCompiler($myCustomCompiler1) ->addCustomCompiler($myCustomCompiler2)
Just take into account that compilers are executed sequentially, begining by the core compilers and the core options. Custom compilers will be executed at the end.