Implement template inheritance via `{{% BLOCKS }}` pragma. #130

bobthecow · 2013-01-13T22:25:29Z

This is a proof-of-concept implementation of template inheritance via blocks.

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. In addition, it would have a number of blocks defined. The blocks look like Mustache sections, but they're denoted with {{$ block }} tags instead of #.

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

The blocks defined here are {{$ title }}, {{$ stylesheets }}, {{$ header }}, {{$ content }} and {{$ scripts }}.

By default, blocks merely delineate sections of the template which can be extended (replaced) in subtemplates. If the parent template itself is rendered, the block tags are simply rendered as if they are truthy sections.

This layout template can then be extended by other sub-templates, which declare their intention by adding a parent=layout to the {{% BLOCKS }} pragma tag:

<!-- page.mustache -->
{{% BLOCKS parent=layout}}

{{$ title }}My Alsome Page{{/ title }}

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

{{$ header }}
  <h1>My page has some items!</h1>
{{/ header }}

{{$ content }}
  <ul>
    {{# items }}
      <li><a href="{{ link }}" title="{{ name }}">{{ name }}</a></li>
    {{/ items }}
  </ul>
{{/ content }}

Upon rendering this page.mustache, the subtemplate blocks will be substituted for the parent blocks, resulting in (approximately) this:

<!DOCTYPE html>
<html>
  <head>
    <title>My Alsome Page</title>
    <link rel="stylesheet" href="/assets/css/page.css">
  </head>
  <body>
    <header>
      <h1>My page has some items!</h1>
    </header>
    <section id="content">
      <ul>
        {{# items }}
          <li><a href="{{ link }}" title="{{ name }}">{{ name }}</a></li>
        {{/ items }}
      </ul>
    </section>
    <script src="/assets/js/default.js"></script>
  </body>
</html>

In our example, we didn't override every block: the {{$ scripts }} block retained its default value. We could also create a new subtemplate which extends page.mustache, say custom-page.mustache. That subtemplate might only replace the {{$ content }} block of page.mustache, and inherit the rest.

Note that page.mustache could even define new blocks. Maybe add a {{$ main }} and {{$ complimentary }} section inside {{$ content }}:

{{$ content }}
  <div id="main" role="main">
    {{$ main }}{{/ main }}
  </div>
  <div id="complimentary" role="complimentary">
    {{$ complimentary }}{{/ complimentary }}
  </div>
{{/ content }}

Then sub-subtemplates could choose to override just the {{$ main }} block, while leaving {{$ content }} and {{$ complimentary }} intact.

bobthecow · 2013-01-13T22:29:57Z

See also mustache/spec#38 for an ongoing discussion (with several recommendations which resemble this one).

rafi · 2013-01-19T13:22:25Z

Awesome.. Can't wait. Is this planned for 2.2 or 2.3 ?

bobthecow · 2013-01-19T20:51:54Z

Probably 2.2.

nicolas-t · 2013-04-21T14:18:49Z

It seems that this feature has been implemented in the current version (2.3) of mustache.php, but I can't find the documentation for it.
Should I use the OP's syntax ?
Thanks

rafi · 2013-04-21T14:32:48Z

It doesn't look like feature/template-inheritance branch has been merged into 2.3

bobthecow · 2013-04-21T17:04:00Z

@rafi is right. This feature has not been merged yet. Feel free to use the feature branch in the interim though.

nicolas-t · 2013-04-21T20:28:37Z

oops sorry, didn't notice there is a branch per feature.
Why isn't the template-inheritance not merged yet ? can I help ?

bobthecow · 2013-05-04T18:16:24Z

@nicolas-t It hasn't been merged because there's not really a consensus on how template inheritance should work in Mustache yet. See mustache/spec#38 for discussion.

Specifically:

This implementation only allows single inheritance, while the Twitter implementation allows multiple inheritance.
GRMustache and this implementation use {{$ foo }} to denote inheritance blocks, while the Twitter implementation uses {{< foo }}.
This implementation and the Twitter implementation override parent blocks, while GRMustache concatenates parent blocks.

rafi · 2013-08-09T08:27:43Z

Any news on this awesome feature?
Can it be merged safely with 2.4.0 ?

bobthecow · 2013-08-09T17:24:14Z

I just rebased the feature branch onto dev, so it has all the latest and greatest v2.4.0 stuffs.

bobthecow · 2013-09-09T04:04:18Z

@calmdev I got a notification (and see a comment on your profile) but nothing shows up here. I take it you got it working?

calmdev · 2013-09-09T19:10:36Z

@bobthecow actually no, I was not able to get it working. I tried with the latest dev and feature/template-inheritance branch. It's odd I spent all weekend trying to figure out why it would not work. I removed the comment here, because I didn't want to confuse anyone until I was absolutely sure it was not working....

I downloaded a copy of the master back in January for a project I was working on before this PR was opened and remember manually merging the changes into the master that I was working with when I saw this PR. For some reason that copy works perfectly fine, but is obviously well behind now.

I'd really love it if you could verify that the examples posted here are working for you with the lastest dev and feature/template-inheritance branches to assure I'm not just going crazy. I'm working on a implementation for use with a custom content management system on www.fit.edu, but it might be a show stopper or create some resistance with the managers if I am not able to get the latest versions working.

I'm itchin' to get us moved over to Mustache.php

The issue I was running into seemed specifically related to the parser throwing an exception when blocks were encountered.

WinWinHost · 2013-11-13T00:00:56Z

Hey Guys,
I tried to run some of templates via the PHP parser, and I got errors around where template inheritance happens.
Not sure what the issue is.

We have a JAR to do the same thing, and I wanted to implement the PHP version, being a LAMP guy.
The main thing is this jar has handlebars in the name. I thought they do the same thing.
Maybe I am confused, handlebars vs mustache. And not an issue of PHP vs Java.

WinWinHost · 2013-11-13T00:15:05Z

Yeah, so I think there is a difference between JAVA and PHP versions.
https://gist.github.com/spullara/1854699

So how does the open source community stay on the same page?
I see someone else is doing the JAVA version, and there is already a big difference between features.
Kind of a killed my entire LAMP stack implementation of mustache.

bobthecow · 2013-11-13T01:04:52Z

@WinWinHost they're different because there's no consensus on how it should work between the different implementations, and it's not in the spec. There are almost as many ways to implement template inheritance as there are mustache libraries with template inheritance. Unless and until it actually gets standardized, there will be differences.

WinWinHost · 2013-11-13T05:04:00Z

What do you think the LOE would be on rewriting that functionality over into the PHP version?
And if some one were to do it, do you think you would merge it in?
It would be great if I could have a PHP equal to stand up to the Java boys.

rafi · 2013-12-21T18:16:23Z

What's keeping this branch out of master?

bobthecow · 2013-12-21T18:26:45Z

@rafi This hasn't been released because there's no consensus on template inheritance between the different mustache implementations (see my comment above)

dtb · 2014-02-03T22:45:15Z

Hey @bobthecow, @jazzdan and I were having trouble getting this branch to work. We created this test, which fails with Mustache_Exception_SyntaxException: Unexpected closing tag: /title (stack trace).

Next we found that Mustache_Parser seems to refer to a pragmas variable, which doesn't exist. We applied this patch to see what would happen, and then the parser error went away, but the output seemed to only include the content from the child template, and not from the layout/parent template (output here).

bobthecow · 2014-02-03T23:31:19Z

@dtb Unfortunately this branch is effectively abandoned at this point. It hasn't kept up with development of the main library, and probably needs to be reimplemented on a fork from the current dev branch. See above for why I haven't taken that on yet :)

bobthecow · 2014-04-06T04:31:20Z

This will be deprecated by #198 when it's merged, so I'm preemptively closing this pull request.

bobthecow mentioned this pull request Jan 13, 2013

Proposal: Template inheritance mustache/spec#38

Closed

{{% BLOCKS }} pragma, initial implementation.

14166b7

samwyse mentioned this pull request Sep 8, 2013

Proposal: Mutable context objects mustache/spec#72

Closed

bobthecow closed this Apr 6, 2014

bobthecow deleted the feature/template-inheritance branch April 1, 2015 06:21

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Implement template inheritance via `{{% BLOCKS }}` pragma. #130

Implement template inheritance via `{{% BLOCKS }}` pragma. #130

bobthecow commented Jan 13, 2013

bobthecow commented Jan 13, 2013

rafi commented Jan 19, 2013

bobthecow commented Jan 19, 2013

nicolas-t commented Apr 21, 2013

rafi commented Apr 21, 2013

bobthecow commented Apr 21, 2013

nicolas-t commented Apr 21, 2013

bobthecow commented May 4, 2013

rafi commented Aug 9, 2013

bobthecow commented Aug 9, 2013

bobthecow commented Sep 9, 2013

calmdev commented Sep 9, 2013

WinWinHost commented Nov 13, 2013

WinWinHost commented Nov 13, 2013

bobthecow commented Nov 13, 2013

WinWinHost commented Nov 13, 2013

rafi commented Dec 21, 2013

bobthecow commented Dec 21, 2013

dtb commented Feb 3, 2014

bobthecow commented Feb 3, 2014

bobthecow commented Apr 6, 2014

Implement template inheritance via {{% BLOCKS }} pragma. #130

Implement template inheritance via {{% BLOCKS }} pragma. #130

Conversation

bobthecow commented Jan 13, 2013

bobthecow commented Jan 13, 2013

rafi commented Jan 19, 2013

bobthecow commented Jan 19, 2013

nicolas-t commented Apr 21, 2013

rafi commented Apr 21, 2013

bobthecow commented Apr 21, 2013

nicolas-t commented Apr 21, 2013

bobthecow commented May 4, 2013

rafi commented Aug 9, 2013

bobthecow commented Aug 9, 2013

bobthecow commented Sep 9, 2013

calmdev commented Sep 9, 2013

WinWinHost commented Nov 13, 2013

WinWinHost commented Nov 13, 2013

bobthecow commented Nov 13, 2013

WinWinHost commented Nov 13, 2013

rafi commented Dec 21, 2013

bobthecow commented Dec 21, 2013

dtb commented Feb 3, 2014

bobthecow commented Feb 3, 2014

bobthecow commented Apr 6, 2014

Implement template inheritance via `{{% BLOCKS }}` pragma. #130

Implement template inheritance via `{{% BLOCKS }}` pragma. #130