fvsch / kirby-twig

Twig templating support for Kirby CMS 2. For Kirby 3, use https://github.com/amteich/kirby-twig
MIT License
70 stars 8 forks source link
deprecated kirby-cms kirby-plugin twig-templates

Twig Plugin for Kirby CMS

What it looks like

Before:

<?php /* site/templates/hello.php */ ?>
<h1><?= $page->title() ?></h1>
<ul>
<?php foreach ($page->children() as $child): ?>
  <li><a href="https://github.com/fvsch/kirby-twig/blob/main/<?= $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="https://github.com/fvsch/kirby-twig/blob/main/{{ 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:

Other topics:

Credits