Download the PHP package dakujem/latter without Composer

Latter

Latte view layer for PSR-7 frameworks and stacks. It's not a typo.

💿 composer require dakujem/latter

To use the awesome Latte templating language with a PSR-7 compliant framework like Slim, one can either struggle to set everything up by himself or use Latter.\ The latter is a better choice

• Latter is designed to reduce code repetition (render pipelines, render routines)
• Latter is a flexible thin layer that can be tuned and tamed as one desires
• set up once and forget

📖\ Check out the Latte documentation to get fluent in Latte.

Render Latte template to PSR-7 response

A very basic example to render a Latte template like the following

in Slim framework using Latter would be:

It would of course be an overkill to use Latte in a case like the one above.\ Most of the time, one will use Latte for more complicated templates with multiple variables, filters and macros.

In such applications, it will make sense to define a Latter\View service in a service container for dependency injection.

Cofigure Latte\Engine factory service

First, let's create a service container.\ I'll be using Sleeve, a trivial extension of Symfony Pimple container.

In most cases, a new Latte\Engine instance should be created for each template render. That is why a factory service should be defined. That is, every time the service is requested from the service container, a new instance will be returned.

💡\ Check out the documentation for the service container or framework you are using to configure this step correctly.

The definition should contain:

• installation of common filters
• installation of custom tags (macros)
• configuration of an appropriate Latte loader
• any other Latte\Engine setup calls needed

Now every time we call $container->get('latte'), a new instance of a configured Latte\Engine will be returned:

Note that we no longer need to prefix the template name with a full path, because of the FileLoader configuration.

Configure Latter\View service

Now let's define a Latter\View service.

An instance of Latter\View will now be available in the service container:

If an engine factory is provided to the View service, it is possible to omit providing the Engine instance for each rendered template.

The View service definition can contain these optional definitions:

• template aliases
• render routines (template rendering)
• render pipelines
• engine factory
• default parameters
• default render routine

Each of these are optional.

Template aliases

It is possible to create template aliases, so that the templates can be referred to using a different name.

To render a template using its alias:

Render routines

Render routines should be used to apply template-specific setup without the need for code repetition.

They may be used to

• define filters
• define tags (macros)
• modify input parameters
• modify template name
• or even to use a completely different Engine instance or render own Response

A render routine is a callable that receives a Runtime context object and returns a response, with the following signature:

Example:

One can render the routine exactly as he would render an alias:

Default render routine

A default render routine may optionally be registered, that will be used for all non-registered templates.

The default render routine has exactly the same signature as the named ones.

It will be used when rendering a template that has not been registered.

Default parameters

Default parameters are merged with the parameters provided to each render call.

If one wants to define per-template default parameters, render routines can be used.

Render pipelines

Pipelines allow multiple pre-render routines to be called one after another before the final rendering.\ The routines can be shared across multiple template render calls that share a common layout, common include(s), common setup (filters, variables) or other rendering logic.\ The most obvious case being layouts or common file / block includes.

First, appropriate pre-render routines have to be registered:

For pre-render routines used in pipelines, it is important to return a Runtime context object. If a Response was returned, the pipeline would end prematurely (this might be desired in certain cases though). Return value of any other kind is ignored.

Render calls using pipelines could look like these:

Pipelines are particularly useful when dealing with included templates (header, footer) or layout templates that require specific variables or filters to render.\ Example:

Both the above share the same layout, that needs specific setup done in the 'base-layout' pre-render routine:

This kind of rendering could be compared to tagging or decorating templates before rendering.

Alternatively, it is also possible to define the pipeline as a part of the rendering routine:

Explicit chaining

Sometimes it is desired to invoke one rendering routine from within another. This is possible using View::another or View::execute.

Note that these methods are not limited to using registered routines, they can execute any callable provided its signature fits.

Tips & tricks

Performance

Latte templates are compiled on first render. All subsequent renders will use compiled and optimized PHP code.

To slightly improve performance on production servers, auto-refresh can be turned off in the Engine factory:\ $engine->setAutoRefresh($container->settings['dev'] ?? true);\ This has its caveats, read the Latte docs beforehand.

Use {link} and n:href macros with Slim framework

It is possible to define {link} and n:href macros that behave similarly to the macros in Nette framework. These macros will generate URLs for named routes.

First make sure a filter that generates the URL is registered in the Latte Engine, then create a macro that uses the filter.

The above would be best done during the 'latte' service definition. See the test for more details.

Then it is possible to use the macros:

💡\ Note the difference to Nette framework - the first macro argument must be an array.\ In order for the query parameters to work, %node.args? is used in the macro. It is possible to replace %node.args? with %node.array? in order to ditch query parameters in favor of exact Nette {link} syntax.

Setting up the Engine before rendering

It is the intention of render routines to provide a place to set up the Latte\Engine instance before rendering a particular template, however, pipelines can be used to quickly set the engine up:

Contributions

... are welcome. 🍵

Go ahead and fork the repository, make your changes, then submit your PR.