Neanderthals Programming Machines

    hogan-xpress

    2.0.0 • Public • Published

    Build Status downloads npm Code Climate Test Coverage dependencies Greenkeeper badge

    hogan-xpress

    Mustache template engine for express 3 and 4. Supports partials, layouts, and lambdas.

    Uses twitter's hogan.js engine.

    Supports

    • Partials (Allows you to modularize, to move pieces of templates to their own file - think of these as "included" templates)
    • Layouts (Allows you to consolidate common elements of your templates - think of these as "parent" templates)
    • Caching (Makes your app more efficient by reducing unnecessary rendering)
    • Lambdas (Allows you to create custom filters/lambdas)

    Migration Note

    If you are coming from hogan-express (no longer maintained):

    I've migrated away from coffeescript (I'm sure no one will miss that). I've also cleaned up a few minor, known bugs, but not all the open bugs/pull requests from the original project, so please feel free to reopen issues and/or resubmit pull requests. Also, I don't have a bounty of free time, so if you're interested in helping maintain this, please email me. I'd much rather have several contributors/maintainers than a single point of failure (as we had on the previous project).

    The major focus of this project still has to be performance, so while adding features is nice, it can't be at the cost of speed. This migration was originally about 4/100s of a second slower rendering a complicated page. To try to assure we maintain performance, I've added benchmarking tests and, over time, I've been able to improve the rendering performance of this library to where it competes with or is better than the original library. However, the last time I tried using this library, there was definitely a memory leak. But I was still using essentially the same code as the old library, just updated to javascript (and not the coffeescript generated kind). I've recently completely restructured this, so hopefully that will resolve the memory leak issue.

    Installation

    npm install --save hogan-xpress

    Usage

    Setup

    To use hogan-xpress, map the file extension of your choice to the hogan-xpress engine in your app setup. For example:

    app.set('view engine', 'html')      // use .html extension for templates
    app.set('layout', 'layout')         // use layout.html as the default layout
    app.set('partials', {foo: 'foo'})   // define partials available to all pages
    app.enable('view cache')
    app.engine('html', require('hogan-xpress'))

    Rendering a template

    Within your app route callback, define res.locals and call res.render, passing any partials required by your template. For example:

    app.get('/', function(req, res) {
      res.locals = { name: 'Andrew' }
      res.render('template', { partials: {message: 'message'} })
    })

    This would render the layout (layout.html, defined in setup) using the template (template.html) and the specified partials (message.html).

    If layout.html contained:

    <p>
      <strong>Message Layout</strong>
      {{{ yield }}}
    </p>

    and template.html contained:

    <em>{{ name }} says {{> message }}</em>

    and message.html contained:

    Hello World.

    the callback would produce:

    <p>
      <strong>Message Layout</strong>
      <em>Andrew says Hello World.</em>
    </p>

    The special {{{ yield }}} variable in layout.html indicates the location in your layout file where your template is rendered. You can define your layout using app.set 'layout', ... or specify it when calling res.render. If a layout is not provided, the template is rendered directly.

    Custom yield tags

    You can define more extension points in layout.html using custom tags {{yield-<name>}}. For example:

    layout:

    <head>
      ...
      {{{yield-styles}}}
      {{{yield-scripts}}}
      ...
    </head>

    index:

    {{#yield-styles}}
      <style>
        ...
      </style>
    {{/yield-styles}}
     
    {{#yield-scripts}}
      <script>
        ...
      </script>
    {{/yield-scripts}}

    The page index.html will be rendered into {{yield}} without the content in {{#yield-styles}}...{{/yield-styles} and {{#yield-scripts}}...{{/yield-scripts}}. That content goes into accordingly named tags in layout.html. If {{{yield-styles}}} is missing, the styles tag content will not be rendered.

    Custom layouts

    To render a page with custom layout, just specify it in the options: res.render "admin.html", layout: "admin-layout"

    Custom Lambdas / Filters

    To create custom filters (or lambdas) you can just specify your filter functions in the options:

    app.get('/', function(req, res) {
     
      res.locals = { myDefaultLabel: "oops" } // here to show a little of how scoping works
     
      res.render('template', {
        message: 'This is a message. HERE.',
        mylist: [{label: "one", num: 1},{label: "two", num: 2},{num: 3}],
        lambdas: {
         lowercase: function(text) {
           return text.toLowerCase()
         },
         reverseString: function(text) {
           return text.split("").reverse().join("")
         }
        }
      })
    });

    Your function will recieve the fully interpolated string (not the pre-rendered template snippet).

    It will also receive a second parameter which is the context in which the lambda was called (this works within loops too) including top-level stuff that would be in res.locals for example. You shouldn't normally need this, but there are a few use cases for having access to that data.

    template:

    <p>Lowercase <strong>{{message}}</strong>: {{#lambdas.lowercase}}{{message}}{{/lambdas.lowercase}}</p>
    <ul>
      {{#mylist}}
      <li>{{num}}: {{label}} is {{#lambdas.reverseString}}{{label}}{{#lambdas.reverseString}} in reverse.</li>
      {{/mylist}}
    </ul>

    rendered html:

    <p>Lowercase <strong>This is a message. HERE.</strong>: this is a message. here.</p>
    <ul>
      <li>1: one is eno in reverse.</li>
      <li>2: two is owt in reverse.</li>
      <li>3: oops is spoo in reverse.</li>
    </ul>

    License

    hogan-xpress is released under the MIT License

    Contributing

    Please see the contribution guidelines.

    Install

    npm i hogan-xpress

    DownloadsWeekly Downloads

    92

    Version

    2.0.0

    License

    MIT

    Unpacked Size

    39 kB

    Total Files

    55

    Last publish

    Collaborators

    • tandrewnichols