ldf-gutenberg v0.2.2
, (*1)
Gutenberg is a view renderer written in PHP and based on the fact that view must be totally separated from logic., (*2)
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., (*3)
How to install
You can install Gutenberg with composer:, (*4)
composer require ldf/gutenberg
Instantiate Gutenberg
Gutenberg is instantiated by a builder class called Gutenberg:, (*5)
$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:, (*6)
// 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., (*7)
A workspace is essentially a path to a directory., (*8)
Templates are referenced by an id which, by convention, resolves to a file in the workspace., (*9)
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, (*10)
- 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., (*11)
Keywords
Gutenberg provides some expressions to allow you to define some dinamic points in your templates., (*12)
Generally speaking
Expressions in Gutenberg are anything you place between double curly braces., (*13)
If you want to print double curly braces you must use the html entity instead:, (*14)
The value of variable "myvar" is {{ myvar }}
{{This will be displayed in the html.|;|
Variables
Variables will be refered as
{{ varname }}, (*15)
import
{{ import _partialTemplateId }}, (*16)
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., (*17)
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., (*18)
wrapper
{{ wrapper tplname}}, (*19)
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., (*20)
When you use wrapping, the source code file must start exactly by the wrapper command., (*21)
Wrappers use the {{ content }} mark to define the place were the inner template will be wrapped., (*22)
{{- (a.k.a X-Wing operator), (*23)
The rest of the line is a comment and will be ingored. For multiple-line comments you can send some X-Wing spaceships:, (*24)
```html/gutenberg
{{-
{{- 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.
{{-
This will be rendered
, (*25)
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.
```php
$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:, (*26)
class MyCustomCompiler implements \Ldf\Gutenberg\ICompiler
{
public function compile(string $tpl) : string
{
...
}
}
You can add as many custom compilers as you want., (*27)
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., (*28)
Wallogit.com
