Inheritance - bobthecow/mustache.php GitHub Wiki

Getting started with inheritance

Make sure you're using Mustache.php v3.0.0 or higher.

{
    "require": {
          "mustache/mustache": "~3.0"
    }
}

Install the package with composer install or composer update.

Let's adapt the hello world example from the repo README to use inheritance.

<?php

$m = new \Mustache\Engine([
  'partials' => [
    'parent' => 'Hello {{$ planet }}planet{{/ planet }}'
  ],
]);

echo $m->render('{{< parent }}{{$ planet }}world!{{/ planet }}{{/ parent }}', []);

This returns:

Hello world!

Deep Dive

Why inheritance?

Say we have a template named layout.mustache. This would be our generic site layout template, consisting of all the sorts of things you'd expect in a layout template. Many of these values in layout.mustache would really be dependent on what is being rendered into it. For example each page probably specifies additional JavaScript files that should be loaded. Beyond that, it is nice to have a convenient way for pages to share common markup, without having to split the common markup into {{> top }} and {{> bottom }} partials.

In other templating languages this behavior is achieved using a feature called template inheritance. Content templates are said "inherit" from layout templates.

Another Example

Let's take a look at a content template that inherits from a layout template.

<!-- layout.mustache -->
<!DOCTYPE html>
<html>
  <head>
    <title>{{$ title }}My Awesome Site{{/ title }}</title>
    {{$ stylesheets }}
      <link rel="stylesheet" href="/assets/css/default.css">
    {{/ stylesheets }}
  </head>
  <body>
    <header>
      {{$ header }}
        <h1>Welcome to My Awesome Site</h1>
      {{/ header }}
    </header>
    <div id="content">
      {{$ content }}
        <p>Hello, World!</p>
      {{/ content }}
    </div>
    {{$ scripts }}
      <script src="/assets/js/default.js"></script>
    {{/ scripts }}
  </body>
</html>

<!-- article.mustache -->
{{< layout }}
{{$ title }}{{ article.title }}{{/ title }}

{{$ stylesheets }}
      <link rel="stylesheet" href="/assets/css/default.css">
      <link rel="stylesheet" href="/assets/css/article.css">
{{/ stylesheets }}

{{$ content }}
<p>{{ article.body }}</p>
{{/ content }}

{{$ scripts }}
      <script src="/assets/js/default.js"></script>
      <script src="/assets/js/article.js"></script>
{{/ scripts }}
{{/ layout }}

Rendering article.mustache with this context:

[
  'article' => [
    'title' => 'How to do x, y and z',
    'body' => '<p>First do x, then do y, then do z.</p>'
  ],
]

would result in this rendered output:

<!-- layout.mustache -->
<!DOCTYPE html>
<html>
  <head>
    <title>How to do x, y and z</title>
      <link rel="stylesheet" href="/assets/css/default.css">
      <link rel="stylesheet" href="/assets/css/article.css">
  </head>
  <body>
    <header>
      <h1>Welcome to My Awesome Site</h1>
    </header>
    <section id="content">
      <p>First do x, then do y, then do z.</p>
    </section>
      <script src="/assets/js/default.js"></script>
      <script src="/assets/js/article.js"></script>
  </body>
</html>

Caveats

Many tokens are not allowed directly inside the parent ({{< }}) tags including sections ({{# }}), inverted sections ({{^ }}), partials ({{> }}) and tokenizer directives ({{= }}). For example, all of the following templates will result in compiler errors:

{{< foo }}{{# bar }}{{$ baz }}{{/ baz }}{{/ bar }}{{/ foo }}

{{< foo }}{{^ bar }}{{$ baz }}set by template{{/ baz }}{{/ bar }}{{/ foo }}

{{< foo }}{{> qux }}{{$ baz }}set by template{{/ baz }}{{/ foo }}

{{< foo }}{{=<% %>=}}<%={{ }}=%>{{/ foo }}

More Information

Extensive template inheritance tests are available here.

The template inheritance spec discussion can be found at this mustache spec pull request.

Acknowledgements

Thanks to @sayrer for the template inheritance feature in hogan.js, which we stole, tests and all. Much thanks to my coworkers @dtb, @mdg and @benburry at @Etsy. And thanks to @bobthecow for a lot of feedback and help with this implementation.