README

Kirby Plugin for semantic templates with Handlebars and Mustache

Installation

• unzip master.zip as folder site/plugins/kirby-handlebars or
• git submodule add https://github.com/bnomei/kirby-handlebars.git site/plugins/kirby-handlebars or
• composer require bnomei/kirby-handlebars

Templates

You can can have handlebars and php templates in your /site/templates folder. The plugin will be used as template component for all files with hbs extension and default back to Kirbys core template component for the ones written in php.

Partials

Partials are stored at /site/template/partials. Think of them as reusable blocks injected into your handlebars templates before they get compiled.

/site/templates/partials/piece-of-cake.hbs

Piece of {{ cake }}

/site/templates/call-a-partial.hbs

{{> piece-of-cake }}

/content/pizza/call-a-partial.txt

Title: 🍕

/site/controllers/call-a-partial.php

<?php
return function ($site, $page, $kirby) {
    return ['cake' => $page->title()]; // cake => 🍕
};

localhost:80/pizza

Piece of 🍕

Data

For the template to render your content, it needs to know which data to use as variables and list in handlebars. This plugin gives you several ways to provide this data, and you can use them all at once. The data from queries will be merged (recursively) with data from controllers and models.

Built-in Queries

The plugin has a few queries built-in. This allows you to use the queried result directly in your handlebar templates. For example, you can use {{ page.title }} in any handlebar template without having to define that value yourself. You can override these in the bnomei.handlebars.queries option.

<article id="{{ page.slug }}">
  <h2>{{ page.title }}</h2>
  {{ page.text }}
</article>

{{ site.title }}
{{ site.url }}
{{ page.id }}
{{ page.title }}
{{ page.text }}
{{ page.url }}
{{ page.slug }}
{{ page.template }}

Optional parsing of queries in data strings

By default, plain strings from content, controllers, and models are rendered as literal data. This prevents editable content from executing Kirby Query methods before Handlebars renders.

If all rendered content is trusted, you can re-enable the old behavior:

return [
    'bnomei.handlebars.resolve-content-queries' => true,
];

With this option enabled, strings can contain Kirby Query placeholders:

/content/blog/unesco-heritage/post.txt

Title: Unesco heritage
----
Date: 2017-12-07
----
Art: twirling
----
Text:
On {{ page.date.toDate('d.m.Y') }} the Neapolitan art of pizza {{ page.art }} 
has joined Unesco’s list of intangible heritage.

/site/templates/post.hbs

<article id="{{ page.slug }}">
  <h2>{{ page.title }}</h2>
  {{ page.text }}
</article>

localhost:80/blog/unesco-heritage

<article id="unesco-heritage">
  <h2>Unesco heritage</h2>
  <p>On 07.12.2020 the Neapolitan art of pizza twirling 
has joined Unesco’s list of intangible heritage.</p>
</article>

Controllers

/content/home/home.txt

Title: Home

/site/controllers/home.php

<?php
return function ($site, $page, $kirby) {
    return [
        'c'=> 'Cassia',
        'counting' => [
            ['label' => 1],
            ['label' => 2],
            ['label' => 3],
        ],
    ];
};

/site/templates/default.hbs

{{ page.title }} of <i>{{ c }}</i>.
<ul>
{{# counting }}<li>{{ label }}</li>{{/ counting }}
</ul>

Models: Method

/site/models/home.php

<?php
class HomePage extends Page
{
    public function handlebarsData(): array
    {
        return [
            'c'=> 'Cassia',
            'counting' => [
                ['label' => 1],
                ['label' => 2],
                ['label' => 3],
            ],
        ];
    }
}

Models: Extend model from Plugin and define exported methods

<?php
class HomePage extends \Bnomei\HandlebarsPage
{
    // declare what public methods to export
    public static $handlebarsData = [
        'c',        // $this->c()
        'counting'  // $this->counting()
    ];

    public function c(): string
    {
        return 'Cassia';
    }
 
    public function counting(): array
    {
        return [
            ['label' => 1],
            ['label' => 2],
            ['label' => 3],
        ];
    }
}

handlebars()/hbs() helper

Maybe you just need to parse some handlebars when you create your data, or you do not use the template component at all. For the later disable the component with the bnomei.handlebars.component config setting and just use the provided helper functions. The hbs()/handlebars() take the same parameters as the Kirby snippet() function. This means they echo the result by default but take a third function parameter to enforce returning the value.

/site/templates/render-unto.hbs

Render unto {{ c }} the things that are {{ c }}'s, and unto {{ g }} the things that are {{ g }}'s.

/site/templates/non-hbs-template.php

<?php
// echo template 'render-unto'
// data from site/controllers/home.php merged with custom array
hbs('render-unto', ['c'=> 'Caesar', 'g'=>'God']);

Render unto Caesar the things that are Caesar's, and unto God the things that are God's.

// return template 'render-unto'
$string = hbs('render-unto', ['c' => 'Cat', 'g' => 'Dog'], true);
echo $string;

Render unto Cat the things that are Cat's, and unto Dog the things that are Dog's.

Settings

Dependencies

• https://github.com/devtheorem/php-handlebars

Disclaimer

This plugin is provided "as is" with no guarantee. Use it at your own risk and always test it yourself before using it in a production environment. If you find any issues, please create a new issue.

License

MIT

It is discouraged to use this plugin in any project that promotes racism, sexism, homophobia, animal abuse, violence or any other form of hate speech.