require-handlebars-plugin

Require.js Handlebars Plugin

Requirements

Should work in both the java and node build environments.

Require.js >= 2.1.x (The last tag to work for Require

…

javascript define('templates/helpers/roundNumber', ['handlebars'], function ( Handlebars ) { function roundNumber ( context, options ) { // Simple function for example return Math.round( context ); } Handlebars.registerHelper( 'roundNumber', roundNumber ); return roundNumber; });

Then in your templates, you can just do:

```mustache
{{roundNumber Data.ThreeFourths}}

The system will make sure these modules are pulled in automatically from that directory. But if in your app, you need a rounding module (perhaps in a view/datanormalization place), you could do this:

require(['templates/helpers/roundNumber'], function ( roundNumber ) {
  var threeFourths = (3/4);
  alert( roundNumber( threeFourths ));
});

It's just a module that happens to register itself.

You can specify a helper path callback in the config. The callback should be a function that gets a name of a helper as the only argument and returns the full path to be require()-d, e.g., the following callback allows for automatic loading of helper modules written in CoffeeScript (via the require-cs plugin) under a non-standard location:

require({
  hbs : {
    helperPathCallback: function(name) {return 'cs!/helpers/' + name;}
  }
}, ['main'])

Meta Data

Any template that begins with a comment, with only a valid json object in it will be read in as meta data for the template.

I encourage you to list the name of the template and give a description, though these aren't strictly necessary.

Styles

If you want to build stylesheets that are comprised of only styles needed by the templates that your app uses, I encourage you to add a styles property to the meta info:

{{!
{
  "name" : "template1",
  "description" : "A nice template.",
  "styles" : ["templatecss"]
}
}}

…

javascript
require(['hbs!template/one'], function ( tmplOne ) {
  console.log(
    'Variables referenced in this template: ',                     tmplOne.vars,
    'Partials/templates that this file directly depends on: ',     tmplOne.deps,
    'Helpers that this template directly depends on: ',            tmplOne.helpers,
    'The metadata object at the top of the file (if it exists): ', tmplOne.meta
  );
});

…

sh
cd ~/require-handlebars-plugin
python -m SimpleHTTPServer

You could also use the node 'serve' module.

npm install serve -g
serve .

Then visit http://127.0.0.1:8000/demo.html for the dev version.

And visit http://127.0.0.1:8000/demo-build.html for the production build version.

You should be able to see all of the templates and individual files in your network panel in dev mode, and just 2 minified files in build mode.

Config

There are several configurable options, which you can set in your require.config:

require.config({
  // ... other require config here

  // hbs config
  hbs: {
    helpers: false,               // When false, won't look for and try to automatically load
                                  // helpers (true by default)

    helperPathCallback:           // Callback to determine the path to look for helpers
      function (name) {           // ('/templates/helpers/'+name by default)
        return 'cs!' + name;
      },

    templateExtension: "html"     // Set the extension automatically appended to templates
                                  // ('hbs' by default)

    handlebarsPath:               // Custom path to handlebars for compiled templates
      'some/path/to/handlebars'   // ('hbs/handlebars' by default). Could simply be 'handlebars'
                                  // as long as it is defined in paths. If you are stubbing out
                                  // the plugin in an optimized build, use this to point to 
                                  // the runtime hbs (see demo/app.build.js)

    compileOptions: {}            // options object which is passed to Handlebars compiler
  }

})

Notes/QA

Partial Collision

This plugin registers every single template as a partial with it's modified module name and no file extension.

App/Template/One.handlebars is registered as App_Template_One

I'd encourage you to not call registerPartials in your code, and just use the automatic module registering, that way you definitely won't hit any collisions. You could also just be careful. We're all adults here.

Templates not loading cross-domain

In dev mode, loading the templates requires that you are on the same domain as your templates. This is standard same origin policy stuff. Once you build, though, it won't matter since there are no additional requests. Usually a few cleverly placed host overrides get you through the dev mode hurdles.

Other Templating Languages

Very little of this is specific to handlebars, but things are just a tiny bit too specific about how everything works to properly generalize this.

If you'd like to implement this for your templating language of choice, you'll need:

• Has a pre-compile type functionality (unless you don't care about builds)
• If it has some concept of partials, that you can register them externally
• It eventually returns a function that takes data context and outputs something you can deal with.
• For any of the meta-data, you'll need some fancy regex or an AST to walk through.

I'd just turn your template language into a module first (just the old global name, or whatever), then look through the references to Handlebars in hbs.js and see if your templating language does something similar. It's not a terribly complicated process.

License

Most of the code in this is from James Burke and Yehuda Katz in require.js and handlebars.js (respectively). Those projects are under their own license. Any other code added by me is released under the WTFPL license.