Nitrogen Pumpkin Mulch

    wax-on
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/wax-on package

    1.2.2 • Public • Published

    Wax On

    Build Status NPM Dependency Status NPM Verion

    Wax On adds support to Handlebars for template inheritance with the block and extends helpers.

    Directly inspired by template Inheritance in Pug and works the same way in Handlebars.

    Install

    npm install --save wax-on

    Usage

    // app.js
     
    const Handlebars = require("handlebars");
    const wax = require("wax-on");
     
    // register Wax On helpers with Handlebars
    wax.on(Handlebars);
    wax.setLayoutPath("/path/to/layouts");

    Extends

    The extends helper allows a template to extend a layout or parent template. It can then override certain pre-defined blocks of content.

    Note: You can have multiple levels of inheritance, allowing you to create powerful hierarchies of templates.

    Block

    Handlebars blocks can provide default content if desired, however optional as shown below by block scripts, block content, and block foot.

    {{! layout.hbs }}
     
    <!DOCTYPE html>
    <html lang="en">
    <head>
     
        <meta charset="utf-8">
        <title>
            My Site — {{title}}
        </title>
        {{#block "scripts"}}
            <script src="/jquery.js"></script>
        {{/block}}
     
    </head>
    <body>
     
        {{#block "content"}}{{/block}}
     
        {{#block "foot"}}
            <div id="footer">
                <p>
                    some footer content
                </p>
            </div>
        {{/block}}
     
    </body>
    </html>

    Now to extend the layout, simply create a new file and use the extends helper as shown below, giving the path (server only). You may now define one or more blocks that will override the parent block content, note that here the foot block is not redefined and will output “some footer content”.

    {{! page-a.hbs }}
     
    {{#extends "layout"}}
     
        {{#block "scripts"}}
            <script src="/jquery.js"></script>
            <script src="/pets.js"></script>
        {{/block}}
     
        {{#block "content"}}
            <h1>
                {{title}}
            </h1>
            {{#each pets as |petName|}}
                <p>{{petName}}</p>
            {{/each}}
        {{/block}}
     
    {{/extends}}

    It’s also possible to override a block to provide additional blocks, as shown in the following example where the content block now exposes a sidebar and primary block for overriding, or the child template could override the content block all together.

    {{! sub-layout.hbs }}
     
    {{#extends "layout"}}
     
        {{#block "content"}}
            <div class="sidebar">
                {{#block "sidebar"}}
                    <p>nothing</p>
                {{/block}}
            </div>
            <div class="primary">
                {{#block "primary"}}
                    <p>nothing</p>
                {{/block}}
            </div>
        {{/block}}
     
    {{/extends}}
    {{! page-b.hbs }}
     
    {{#extends "sub-layout"}}
     
        {{#block "content"}}
            <div class="sidebar">
                {{#block "sidebar"}}
                    <p>nothing</p>
                {{/block}}
            </div>
            <div class="primary">
                {{#block "primary"}}
                    <p>nothing</p>
                {{/block}}
            </div>
        {{/block}}
     
    {{/extends}}

    Block Append / Prepend

    The block helper also allows you to prepend or append blocks in addition to the default behavior of replacing blocks. Suppose for example you have default scripts in a head block that you wish to utilize on every page, you might do this:

    {{! layout.hbs }}
     
    <!DOCTYPE html>
    <html lang="en">
    <head>
     
        {{#block "head"}}
            <script src="/vendor/jquery.js"></script>
            <script src="/vendor/caustic.js"></script>
        {{/block}}
        
    </head>
    <body>
     
        {{#block "content"}}{{/block}}
        
    </body>
    </html>
    {{! page.hbs }}
     
    {{#extends "layout"}}
     
        {{#block "head" mode="append"}}
            <script src="/vendor/three.js"></script>
            <script src="/game.js"></script>
        {{/block}}
     
    {{/extends}}

    The append and prepend helpers make this common use case even easier.

    {{! page.hbs }}
     
    {{#extends "layout"}}
     
        {{#append "head"}}
            <script src="/vendor/three.js"></script>
            <script src="/game.js"></script>
        {{/append}}
     
    {{/extends}}

    Todo

    In chronological order (most recent first); not in order of priority. Please create an issue if you'd like any of these changes or to recommend other changes.

    • add support for running in the browser (client-side)
    • investigate possibility of using partial blocks in addition to the extends helper

    Change Log

    The Wax On change log can be found in the CHANGELOG.md file within the project.

    License

    Wax On is available under the MIT License.

    Install

    npm i wax-on

    DownloadsWeekly Downloads

    55

    Version

    1.2.2

    License

    MIT

    Unpacked Size

    28 kB

    Total Files

    28

    Last publish

    Collaborators

    • keithws