fvsch/kirby-twig

Twig templating support for Kirby CMS

v3.0.3 2018-09-14 18:13 UTC

Requires

• php: >=5.4.0
• twig/twig: ^1.30

MIT

• Florens Verschelde

README

• Adds support for Twig templates to Kirby CMS 2.x.
• PHP templates still work, you don’t have to rewrite them if you don’t want to.

What it looks like

Before:

<?php /* site/templates/hello.php */ ?>
<h1><?= $page->title() ?></h1>
<ul>
<?php foreach ($page->children() as $child): ?>
  <li><a href="<?= $child->url() ?>"><?= $child->title() ?></li>
<?php endforeach; ?>
</ul>

After:

{# site/templates/hello.twig #}
<h1>{{ page.title }}</h1>
<ul>
{% for child in page.children %}
  <li><a href="{{ child.url }}">{{ child.title }}</li>
{% endfor %}
</ul>

Installation

Standard installation

1. Download the latest release.
2. Unzip, rename the kirby-twig-main folder to just twig and put it in your project’s site/plugins folder.

You should end up with a folder structure like this:

site
 └─ plugins
     └─ twig
         ├─ lib
         ├─ src
         └─ twig.php

Using Composer

Require fvsch/kirby-twig in your Composer dependencies:

composer require fvsch/kirby-twig:^3.0

Then, make sure your Kirby installation is autoloading Composer dependencies on both frontend and panel. For this, the safest way is to create your own custom plugin.

site
 └─ plugins
     └─ composer
         └─ composer.php

<?php
// site/plugins/composer/composer.php

// Composer autoload
require_once kirby()->roots()->index() . '/vendor/autoload.php';

Finally, register the plugin by adding this line to your newly created site/plugins/composer/composer.php, after having required the autoloader.

// Register the Twig plugin's template component
Kirby\Twig\Plugin::register();

Usage

Page templates

Now that the plugin is installed and active, you can write Twig templates in the site/templates directory. For example, if the text file for your articles is named post.txt, you could have a post.twig template like this:

{% extends '@templates/layout.twig' %}
{% block content %}
  <article>
    <h1>{{ page.title }}</h1>
    {{ page.text.kirbytext | raw }}
  </article>
{% endblock %}

See the {% extends '@templates/layout.twig' %} and {% block content %} parts? They’re a powerful way to manage having a common page layout for many templates, and only changing the core content (and/or other specific parts). Read our Twig templating guide for more information.

Rendering a template in PHP: the twig helper

This plugin also enables a twig PHP function for rendering template files and strings, like this:

<?php

// Render a simple template from the site/snippets directory
echo twig('@snippets/header.twig');

// Same, but passing some additionnal variables
echo twig('@snippets/header.twig', ['sticky'=>false]);

// Render a string
echo twig('Hello {{ who }}', ['who'=>'World!']);

If you work with Twig templates for pages, you might not need the twig() helper at all. But it can be useful when working with the Modules and Patterns plugins.

More documentation

Recommended reads:

• Twig templating guide for Kirby
• Displaying Twig errors

Other topics:

• Complete options documentation
• Using your own functions in templates
• Using Kirby Twig with other plugins

Credits

• Twig library: Fabien Potencier and contributors / New BSD License
• Twig plugin for Kirby: Florens Verschelde / MIT License