backbone-template-manager

    0.7.0 • Public • Published

    Backbone Template-Manager

    Greenkeeper badge Build Status Npm version Bower version

    Simple template manager for your Backbone application. This library allows you to:

    • Use a template manager to query templates from the DOM or from a server.
    • Create view with a template manager to download templates.
    • Render view with your model and a default compile function (use _.template by default).

    Installation

    • With npm: npm install backbone-template-manager --save.
    • With bower: bower install backbone-template-manager --save.

    Once installed, import the library using ES6 import, or import the ES5 script (transpiled with babel):

    <script type="text/javascript" src="/vendors/backbone-template-manager/es5/backbone-template-manager.js"></script>

    View

    Here is an example:

    import Backbone from 'backbone';
    import {TemplateView} from 'backbone-template-manager';
     
    export class MyView extends TemplateView {
      initialize() {
        this.model = new Backbone.Model({
          id: 1,
          name: 'John Doe'
        });
      }
     
      templates() {
        return 'my-template';
      }
    }

    What happens here?

    1. View extends from TemplateView class.
    2. A model is attached to the view in the initialize function (class Backbone application).
    3. A template function return the template id associated to the view.

    And that's all!

    Note that following events will be triggered:

    • render:loading when the view start rendering (before any template download and rendering).
    • render:success when the view is fully rendered (templates are fetched, view is up to date).
    • render:error when the view cannot be rendered because of missing templates.

    How it works?

    The render method comes with a default implementation:

    • Get the templates to fetch.
    • Without templates, the render method do nothing).
    • Otherwise:
      • Trigger render:loading event and execute the view onBeforeRender method.
      • Get the default template manager of the view (basically, calls templateManager method view).
      • Download the template using its id (what happens here precisely depends on the template manager, more details later).
      • Calls the toJSON method from the view: by default return an object containing a model property (with model.toJSON as the value) and/or a collection property (result of collection.toJSON method).
      • Render the view using default compile function (use _.template under the hood).
      • Trigger render:success event and execute view onRendered and onRender methods without errors.
      • Trigger render:error event and execute view onRendered and onRenderError if something bad happened.

    How templates are downloaded?

    By default, templates are downloaded using Backbone.ajax.

    • The default http method is GET.
    • The requested URL is built with:
      • The template manager prefix (default is /templates/).
      • The template id.
      • The template manager suffix (default is .template.html).

    In the example below, the requested URL will be /templates/foo.template.html. Note that all downloaded templates are put in a cache, so don't worry about network request when you render a view several times!

    Override default template manager

    By default, the template manager fetch templates from a remote server using Backbone.ajax. Let's say you want to define your DOM in your HTML, such as:

    <script type="text/template" data-template-id="my-template">
      <div>Hello <%= name %></div>
    </script> 

    You can override the default template with an instance of the DomTemplateManager:

    import Mustache from 'mustache';
    import {overrideTemplateManager, DomTemplateManager} from 'backbone-template-manager';
     
    // Just given an instance of the new template manager as the first parameter.
    // Should be done when your application starts.
    overrideTemplateManager(new DomTemplateManager({
      // Override default selector.
      // Default is `[data-template-id="${templateId}"]`
      selector: templateId => `#${templateId}`
    }));

    By default, the selector in the DOM will be defined as [data-template-id="${templateId}"], but it may be override (see below).

    Now, the template method of your view must return the selector in the DOM to query the DOM appropriately:

    import Backbone from 'backbone';
    import {TemplateView} from 'backbone-template-manager';
     
    export class MyView extends TemplateView {
      initialize() {
        this.model = new Backbone.Model({
          id: 1,
          name: 'John Doe'
        });
      }
     
      templates() {
        return 'my-template';
      }
    }

    Note that the overrideTemplateManager method can also be used to override the default prefix, suffix and method parameters:

    import Mustache from 'mustache';
    import {overrideTemplateManager, RemoteTemplateManager} from 'backbone-template-manager';
     
    // Just given an instance of the new template manager as the first parameter.
    // Should be done when your application starts.
    overrideTemplateManager(new RemoteTemplateManager({
      prefix: '/app/templates',
      suffix: '.mustache',
      method: 'JSONP'
    }));

    Override default compile function

    The default compile function can be overridden with a custom implementation. Let's say you want to use Mustache (or Handlebars) as the default template engine:

    import Mustache from 'mustache';
    import {overrideCompile} from 'backbone-template-manager';
     
    // Override the compile function.
    // Compile function must return a function that can be used to render template
    // with data model.
    // Should be done when your application starts.
    overrideCompile(html => {
      return data => Mustache.render(html, data);
    });

    Dealing with partials

    Some libraries, such as Mustache, allow you to define partials:

    <div>
      <span>Hello {{ name }}</span>
      <div>{{ > user-view }}</div>
    </div>

    In the template below, user-view is a partial that can be set during template compilation:

    Mustache.render(mainTemplate, data, {
      'user-view': '<div>User information</div>'
    });

    This little library can deal with partials, simply defined an array of templates in your view:

    import Backbone from 'backbone';
    import {TemplateView} from 'backbone-template-manager';
     
    export class MyView extends TemplateView {
      initialize() {
        this.model = new Backbone.Model({
          id: 1,
          name: 'John Doe'
        });
      }
     
      templates() {
        return ['my-template', 'user-view'];
      }
    }

    When an array is defined as a template view, the first entry in the array will be the first argument of the compile function, other templates will be given as second argument as a dictionary where the entry is the template id and the value is the template. You can now render templates easily:

    import Mustache from 'mustache';
    import {overrideCompile} from 'backbone-template-manager';
     
    overrideCompile((html, partials) => {
      return data => Mustache.render(html, data, partials);
    });

    Dealing with JST

    The remote template manager can be optimized by sending all templates in a javascript file stored in a variable (see here) and query this dictionary instead of querying the remote server:

    import Mustache from 'mustache';
    import {overrideTemplateManager, RemoteTemplateManager} from 'backbone-template-manager';
     
    // Just given an instance of the new template manager as the first parameter.
    // Should be done when your application starts.
    overrideTemplateManager(new RemoteTemplateManager({
      JST: true
    }));

    Three options are available:

    • JST: true: assume that templates may already exist in window.JST.
    • JST: '__JST__': assume that templates may already exist in window.__JST__.
    • JST: {}: send the templates object directly during the construction.

    If templates does not exist in the JST variable, a classic HTTP request will be made as a fallback. Note that templates should be stored with the template id as the key (not the full URL), for example:

    import Backbone from 'backbone';
    import {TemplateView} from 'backbone-template-manager';
     
    export class MyView extends TemplateView {
      initialize() {
        this.model = new Backbone.Model({
          id: 1,
          name: 'John Doe'
        });
      }
     
      templates() {
        return 'my-template';
      }
    }

    The template manager will assume that window.JST will be equal to:

    {
      "my-template": "<div>My Template</div>"
    }

    History

    This little library has been created in 2013 (still used in production) and open sourced in 2016 after a rewrite in ES6.

    License

    MIT.

    Keywords

    Install

    npm i backbone-template-manager

    DownloadsWeekly Downloads

    0

    Version

    0.7.0

    License

    MIT

    Last publish

    Collaborators

    • mickael.jeanroy