bnomei/kirby3-handlebars

Kirby 3 Component for semantic templates with Handlebars and Mustache

Installs: 106

Dependents: 0

Suggesters: 0

Stars: 0

Watchers: 0

Forks: 0

Open Issues: 1

Type:kirby-plugin

2.1.2 2019-02-17 21:26 UTC

README

GitHub release License Kirby Version Kirby 3 Pluginkit

Kirby 3 Component, Snippet and Page Method for semantic templates with Handlebars and Mustache

Commercial Usage

This plugin is free but if you use it in a commercial project please consider to

Installation

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

Dependencies

Performance

  • LightnCandy is extremely fast and lightweight.
  • Templates are only precompiled to native PHP on modification.
  • Render output is cached even without Kirbys Page Cache. The render cache is devalidated if either template or data is modified.

Usage without Component

templates/render-unto.hbs

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

templates/home.hbs

{{ page.title }} of <i>{{ c }}</i>.

controllers/home.php

<?php
return function ($site, $page, $kirby) {
  return ['c'=>'Cassia', 'g'=>null];
};

templates/home.php

<?php
  snippet('plugin-handlebars', [
    'template' => 'render-unto',
    'data' => [
        'c' => 'Caesar', 
        'g' => 'God'
    ]
  ]);
  // => Render unto Caesar the things that are Caesar's, and unto God the things that are God's.

  // or
  echo $page->template();
  // => home

  echo $page->handlebars(); // template of page as string 'home', data from site/controllers/home.php
  // => Home of <i>Cassia</i>.
  
  echo $page->handlebars('render-unto', ['g'=>'Gods']); // template 'render-unto', data from site/controllers/home.php merged with custom array
  // => Render unto Cassia the things that are Cassia's, and unto God the things that are God's.

  hbs('render-unto', ['c' => 'Caesar', 'g' => 'God']);

TIP: you can also get the output in a variable setting snippets return-param to true. $output = snippet(..., [...], true);

Usage as Template Component

  • Put your handlebars templates in the site/templates/ folder.
  • See below on how turn on Component and configure File extension in settings.
  • Prepare data in Controllers stored at site/controllers/* which will be available in the templates
  • In case you do not have a handlebar template with matching name it will fallback to kirbys php template logic.

Settings

component

  • default: false if true all templating will be handled by this plugin.

no-escape

  • default: true 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.

dir.templates

  • default: callback returning kirby()->roots()->templates()

dir.partials

  • default: callback returning kirby()->roots()->templates().'/partials'

extension.input

  • default: hbs

extension.output

  • default: lnc, hbs compiled to php

cache.render

  • default: true, cache render based on hash of data

cache.files

  • default: true, cache paths of template and partial files

cache.lnc

  • default: true, cache compiled php

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.