About Template Engine Factory
A module integrating template engines such as Twig. It allows to render pages or individual templates via template engine and encourages to separate logic from markup by implementing a simple MVC pattern.
Category 1 | Development Tools Modules that have more to do with assisting development of a site rather than managing its content. |
---|---|
Category 2 | Markup Generation Markup modules that are called upon to generate or parse markup (like HTML). Markup modules are most often used on the front-end of a site (rather than admin). |
Category 3 | Other Modules Modules that have a unique purpose not covered by existing categories. |
Release State | Stable Should be safe for use in production environments. * |
Author | |
Module Version | 1.1.3 |
Class Name | TemplateEngineFactory |
Compatibility | 2.5, 2.6, 2.7, 3.0 |
Date Added | July 3, 2014 |
Last Updated | February 14, 2019 |
Recommended By | New recommendations may take up to 1 day to appear. |
Details
Attention! Version 2.x of this module differs from the 1.x version in many ways and introduces backwards compatibility breaks. If you are updating from version 1.x, please take a look at the update guide.
The 1.x version of the module is available on the 1.x branch.
Instructions
This module's files should be placed in /site/modules/TemplateEngineFactory/
How to install or uninstall modules
README
Template Engine Factory
A ProcessWire module integrating template engines such as Twig. It allows to render pages or individual templatesvia template engine and encourages to separate logic from markup by implementing a simple MVC pattern.
- For a quick introduction, please read the Getting Started section of this readme.
- More information is available in the official Documentation.
Version
2.x
of this module differs from the1.x
version in many ways. Modules providing template engines must beinstalled with Composer. Twig is currently the only template engine implemented for the2.x
major version. Pleasetake a look at the update guide, as the new version introduces backwardscompatibility breaks. The1.x
version of the module is available on the 1.x branch.
Requirements
- ProcessWire
3.0
or newer - PHP
7.0
or newer - Composer
Installation
Execute the following command in the root directory of your ProcessWire installation:
composer require wanze/template-engine-factory:^2.0
This installs the module and its bundled template engine called TemplateEngineProcessWire. This template engine usesProcessWire's internal TemplateFile
class for rendering. Other template engines are added to the factory by installingseparate ProcessWire modules.
Installing Twig and other template engines
Each template engine is a separate ProcessWire module. For example, if you want to use Twig,execute the following command:
composer require wanze/template-engine-twig:^2.0
This will install the TemplateEngineTwig and TemplateEngineFactory modules in one step, no need to install bothseparately. It also installs the Twig dependencies for us, pretty neat! ✌️
ℹ️ This module includes test dependencies. If you are installing it on production with
composer install
, make sure topass the--no-dev
flag to omit autoloading any unnecessary test dependencies!.
Configuration
The module offers the following configuration options:
Template Engine
The template engine used to render pages and templates. Any installed engine is listed here.Path to templates
Relative path from the site directory where template files are stored. E.g.templates/views/
resolves to/site/templates/views/
.Enable automatic page rendering
Check to delegate the rendering of pages to the template engine.You may enable or disable this behaviour for specific templates.API variable to interact with the template engine
Enter a name for the API variable used to pass data fromthe ProcessWire template (Controller) to the template engine.Enabled templates
Restrict automatic page rendering to the templates selected here.Disabled templates
Select templates of pages that should not automatically be rendered via template engine.Do not use in combination with the Enabled templates configuration,either enable or disable templates.
More configuration options might be available in the module providing a template engine, e.g. themodule TemplateEngineTwig offers several configuration related to Twig.
Available Template Engines
- ProcessWire A template engine using ProcessWire's TemplateFile class for rendering. This engine is bundled withthis module, but it is not installed automatically. Install the module TemplateEngineProcessWire and select theengine in the TemplateEngineFactory module configuration.
- Twig See: https://github.com/wanze/TemplateEngineTwig
Getting Started
This section assumes that Twig is used as active template engine, but the usage is excatly the same for any othertemplate engine.
Using the Template Engine to render templates
Assume the following Twig template exists in /site/templates/views/foo.html.twig
<h1>{{ title }}</h1>
{% if body %}
<p>{{ body }}</p>
{% endif %}
The template can be rendered anywhere with the Template Engine Factory module:
$factory = wire('modules')->get('TemplateEngineFactory');
// Render foo.html.twig with some data.
$factory->render('foo', ['title' => 'Foo', 'body' => 'Hello World']);
Automatic Page Rendering
If enabled, this feature uses the template engine to render ProcessWire pages when calling Page::render
.By default, the module tries to find a Twig template matching the same name as the ProcessWire template:
/site/templates/views/home.html.twig
corresponds to/site/templates/home.php
/site/templates/views/about.html.twig
corresponds to/site/templates/about.php
ProcessWire templates have access to a $view
API variable which can be used to pass data to the template engine.As the template engine is now responsible to output markup, ProcessWire templates can be seen as Controllers.They process the request and pass data to the View layer via the $view
API variable.
Examples
Consider the following ProcessWire template in /site/templates/home.php
// Form has been submitted, do some processing, send mail, save data...
if ($input->post->form) {
// ...
$session->redirect('./');
}
// Forward some data to twig
$view->set('nav_items', $pages->get('/')->children());
The corresponding Twig template in /site/templates/views/home.html.twig
might look like this:
<h1>{{ page.title }}</h1>
<ul class="nav">
{% for item in nav_items %}
<li><a href="{{ item.url }}">{{ item.title }}</a></li>
{% endfor %}
</ul>
<form name="form">
<input type="text" name="email">
<input type="submit" value="Submit">
</form>
Note that the ProcessWire template does not echo out any markup. It just contains business logic and uses the $view
APIvariable to pass data to the Twig template. That's it! The most simple MVC pattern available in ProcessWire. ????
Comments
No comments yet. Be the first to post!
Post a Comment
Your e-mail is kept confidential and not included with your comment. Website is optional.
- Admin Helpers
- Authentication
- Core Modules
- Development Tools
- Email/WireMail
- Field Types
- Import/Export
- Input Fields
- Language Modules
- Language Packs
- Logs/Monitoring
- Markup Generation
- Photo/Video/Audio
- Premium Modules
- Process Modules
- Proof of Concept
- SEO/Accessibility
- Site Profiles
- Social, Feeds, Services
- Text Formatters
- Other Modules
- Users and Access
Disclaimer
*Use modules at your own risk. There are no guarantees or warranties. It is recommended that you backup your site and database before installing new modules.