Handlebars: Templates

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 kql json files, controllers and models.

Queries

The plugin comes with some build-in queries that you can use right out of the box.

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

KQL Plugin

This plugin can use the KQL Plugin to query the data for the template. You can either use the KQL::run() in your controller or store the query as json in a file with the same filename as your template.

/site/templates/blog.hbs

<h1>{{ page.title }}</h1>
<nav>
  <ol>
    {{# page.posts }}
    <li><a href="{{ url }}">{{ title }}</li>
    {{/ page.posts }}
  </ol>
</nav>

/site/templates/blog.json

{
  "query": "page",
  "select": {  
    "title": true,
    "posts": {
      "query": "page.children.listed.flip.limit(10)",
      "select": {
        "title": true,
        "url": true
      }
    }
  }
}

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],
        ];
    }
}

Escaping

By default data sent to template will NOT be escaped. This way your templates can render data formated as html. You can use Kirbys Field Methods $field->kirbytext(), $field->html() or the Kirby\Toolkit\Str-Class functions to escape your text properly. Alternatively you can set it to false and use {{{ var }}} triple mustaches.

Settings

bnomei.handlebars.	Default	Description
compiler-flags	callback	By default data sent to template will NOT be escaped. This way your templates can render data formated as html. You can use Kirbys Field Methods $field->kirbytext(), $field->html() or the Kirby\Toolkit\Str-Class functions to escape your text properly.
extension-kql	json

Note: kirby, site, pages and page can not be used as top-level data keys. They will be overwritten by Kirby Objects and later pruned by the plugin for serialization.