[Ember](http://emberjs.com)'s convention of template hierarchy is very specific.  Learn it once, and you'll know it every time.



**Note:** Code examples use [Emblem](http://emblemjs.com/) templates and [CoffeeScript](http://coffeescript.org).  Vanilla Handlebars and JavaScript would work just as well.

## Outlets

Ember templates make use of a special helper called `outlet`.  You can have one main, unnamed outlet or many named outlets.  The main thing to remember is that a child template will always render inside its parent's outlet -- so always put outlets in templates that have children.

## Application Template

There is a top-most template that all of your templates will render inside of.  This is called the application template.  It is specified in one of two ways.  If you are including your templates as script tags, simply create a script tag that doesn't have a `data-template-name` or `id` attribute, a la:

```html
<script type="x-emblem">
  h1 My Application
  == outlet
</script>
```

If you are [precompiling your Ember templates](/post/precompile-ember-templates), which you should, you have a directory for templates.  You will put your file, called `application.emblem` in the root of that directory.  The contents of `templates/application.emblem` would be the same:

```jade
h1 My Application
== outlet
```

## Route Templates

If you have a top-level route, it will have a top-level template.  Your route's template will have only the application template as its parent.  So, your about route:

```coffeescript
App.Router.map ->
  @route 'about'
```

Will have an about template at `templates/about.emblem` and you could define a route as `AboutRoute`.  It will render inside of `application.emblem`'s outlet.

## Resource Templates

Resources are interesting because you can nest other routes inside them.  Nesting routes will also result in nesting templates.  If I defined a `league` resource with a nested route for creating new leagues, it might look something like this:

```coffeescript
App.Router.map ->
  @resouce 'league', ->
    @route 'new'
```

There are two leaf routes (and thus templates) that are created here:

- `LeagueIndexRoute`, which uses `templates/league/index.emblem`
- `LeagueNewRoute`, which uses `templates/league/new.emblem`

Note that you create a `league` directory inside your `templates` directory for nesting these templates.  Precompiled templates will be created at:

- `Ember.TEMPLATES["league/index"]`
- `Ember.TEMPLATES["league/new"]`

If you wanted to use the `linkTo` helper in a template to link to these routes, you would use this syntax:

```jade
linkTo 'league.index' | List Leagues
linkTo 'league.new' | New League
```

And now as far as templates, there is *one more* that we're missing.  There is a root league template that these two league leaf templates render inside of.  It should live at `templates/league.emblem`.  This template would be useful for showing UI elements that are common to all league resource things.  In the case where there is no such need, this template will probably only contain a single outlet:

```jade
== outlet
```

So the final template hierarchy for `league.new`, for example, is `application.emblem > league.emblem > league/new.emblem`.

There is a bit of a chatter on the Githubs about whether the root resource template is good form or not.  As in, why would you create a file that contains nothing but an empty outlet?  Couldn't the framework infer that if it was missing?

## Children Need All Parents

Create all parents in your template chain, from the application template to the leaves.  The worst thing that can happen if you don't is that nothing will render at all, and no error messages will be displayed (pretty bad and unhelpful).

Most of the time, Ember will try to be helpful and give you a console warning:

> WARNING: The immediate parent route ('a') did not render into the main outlet and the default 'into' option ('p') may not be expected

In other words: You're trying to render a child template that either doesn't have a parent template it needs or the parent template does not specify a main outlet.

Ember's convention of template hierarchy is very specific.  Learn it once, and you'll know it every time.

Ember Parent Templates

[Ember](http://emberjs.com) is very specific about what version of [Handlebars](http://handlebarsjs.com) it requires.  This is probably good, but it's also a pain to work with as different versions of the two libraries are released independently.  There are a few good tools to help us out.



## Released Independently

In a prime example, recently there was a new version of Handlebars released: `1.0.0-rc.4`.  Ember happens to be on version `1.0.0-rc.3`.  That version has a hard dependency on Handlebars `1.0.0-rc.3`.  In other words, the latest Ember code relies on an older version of Handlebars.

## Bower

If you include these 3rd party libraries in your source code under a `lib` directory or something of that nature, you *always* have plenty of work to do.  Naturally, you just copy in the exact versions of the scripts that are needed.

Hopefully you're trying to make use of a mostly awesome tool, [Bower](http://bower.io).  It helps you manage these 3rd party libraries in a way similar to npm.  You provide a descriptor of your project's dependencies, `component.json`.  And you install things similarly via the `bower` cli.

## Specify a Bower Version

If I run:

```
bower install handlebars --save
```

It saves a dependency in my `components.json` for Handlebars for the latest version it could find.  This won't do for us.  We need to specify the versions.

Our strategy will be: take the latest version of Ember and then specifically match the Handlbars version.  Finally, we should type:

```
bower install ember --save
bower install handlebars#1.0.0-rc.3
```

As of this writing, that is the version of handlebars that is required.  Bower will recognize any semver git tag name or branch name after the hash `#` sign.

I like our version strategy for a project that is under active development in that it keeps us on the latest Ember.  But, if you're on a project that's been built to an Ember version and not deployed for a long time, you may want to make a very specific dependency out of Ember as well, so the two are guaranteed in sync for future deploys.

Specific versions of Ember require specific versions of Handlebars.  Here's a way to help them match.

Match Ember and Handlebars Versions

[Ember](http://emberjs.com) makes use of the wonderful [Handlebars](http://handlebarsjs.com) templates.  These templates, in order to be performant, must be precompiled.  Based on the Ember docs, it's not abundantly clear how this is to happen.  Here's a solution that works well.



## Ember Docs for Precompilation

Every official Ember doc will put templates in a `script` tag with the `type="text/x-handlebars"`.  But this is never how you'd write any serious (-ly awesome) app in production.  [The docs](http://emberjs.com/guides/templates/handlebars-basics/) say:

> "If you are using build tools to manage your application's assets, most will know how to precompile Handlebars templates and make them available to Ember.js."

Which tools?  Why would I want to precompile?  How *are* they made available to Ember?  Read, Ember journeyman, read on...

## Grunt

We'd love for this precompilation to happen previous to the running of your app.  Again, this is in hopes of increased performance.  [Grunt](http://gruntjs.com) is a great little Nodejs-based tool for build-level tasks.

## Emblem

Grunt comes with a variety of plugins.  We're going to use one called [grunt-emblem](https://github.com/wordofchristian/grunt-emblem/).  [Emblem](http://emblemjs.com/) is a fantastic templating syntax layered on top of Handlebars (still a dependency).  Its syntax looks very similar to Haml or Ruby Slim or Jade.  It may well be the most flexible of all of them, and it simplifies some Ember helper syntax very nicely.

## Versions Matching

As I've said before, [matching Ember dependency version can be a pain](/post/match-ember-handlebars-version/).  With precompilation, you have one more dependency to match.  Now not only do you care about the version of Handlebars that Ember uses at runtime, but you care about the version of Handlebars that is used to precompile your templates.  If the precompile Handlebars version doesn't match the runtime Handlebars version, your app will die at runtime.  `grunt-emblem` helps immensely with this.

## grunt-emblem

I haven't found another Handlebars precompile plugin that helps as much as `grunt-emblem`.  It solves the precompile version problem by letting you utilize the actual runtime Handlebars as the precompile Handlebars script.

It is also nice in that it puts the precompiled templates into the collection that Ember expects to find templates in, namely `Ember.TEMPLATES`.  As you can find on the [`grunt-emblem` Github page](https://github.com/wordofchristian/grunt-emblem/), your grunt config will look something like the following:

```coffeescript
matchdep = require 'matchdep'

module.exports = (grunt) ->
  grunt.initConfig

    watch:
      ember_templates:
        files: ['app/views/templates/**/*.emblem']
        tasks: ['emblem', 'livereload']

    emblem:
      compile:
        files:
          "app/static/templates/ember_templates.js": ["app/views/templates/**/*.emblem"]
        options:
          root: "app/views/templates/"
          dependencies:
            jquery: "app/static/js/components/jquery/jquery.js"
            ember: "app/static/js/components/ember/ember.js"
            emblem: "app/static/js/components/emblem/dist/emblem.js"
            handlebars: "app/static/js/components/handlebars/handlebars.js"

  matchdep.filterDev('grunt-*').forEach grunt.loadNpmTasks

  grunt.renameTask 'regarde', 'watch'

  grunt.registerTask 'dev', [ 'livereload-start', 'watch' ]

```

This particular config has a couple other niceties.  Let me enumerate the awesome:

- Line 6 - Not only can we precompile the templates, but we'll precompile on the fly, whenever `.emblem` files are change in the specified directories.
- Line 8 and 14 - We're precompiling `.emblem` templates, but this plugin can do regular Handlebars syntax as well
- Line 16 - `root` is the substring that will be stripped out of your template name.  For instance, you don't want your template to be called `app/views/templates/home`.  Your home route in Ember will want your template called `home`.  `root` to the rescue -- bam!
- Line 17 - These `dependencies` are the libraries that you use at runtime and that Handlebars needs at compile time.  As I said, this plugin simply rocks because of the ability to specify your own Handlebars script.
- Line 23 - Remember how you used to have a whole list of npm tasks registered.  This little beaut will load all `grunt-*` dependencies.
- Line 25 - `regarde` is a cool name, but I understand what `watch` means a bit better. Rename it.

This setup requires the following dependencies:

```
npm install matchdep grunt grunt-regarde grunt-contrib-livereload grunt-emblem --save-dev
```

So now, seriously, go write some Emblem templates.  So fun, so precompiled.

When you're working with Ember's Handlebars templates, you're going to want to precompile them for performance reasons.

Precompile Ember Templates

Have you ever wanted to do something special every nth time through a Handlebars loop?  The built-in `{{#each}}` will loop through your items just fine.  It lacks a few features.  For one, you don't have access to the loop index, though you can [find it](https://rockycode.com/blog/handlebars-loop-index/).  Without the index and simple comparisons like modulus, length of the array, and equals, you'll be creating your own Handlebars helpers.  Here's an example of one.



## Extend the context

Inside a block helper in Handlebars, when you call `options.fn`, you pass the context to the first block.  We can extend what attributes are available in that context.  The `everyNth` helper below extends this context with variables that are useful for doing "every nth" operations:

1. isModZero
2. isModZeroNotFirst
3. isLast

The code in full looks like this:

```js
Handlebars.registerHelper('everyNth', function(context, every, options) {
  var fn = options.fn, inverse = options.inverse;
  var ret = "";
  if(context && context.length > 0) {
    for(var i=0, j=context.length; i<j; i++) {
      var modZero = i % every === 0;
      ret = ret + fn(_.extend({}, context[i], {
        isModZero: modZero,
        isModZeroNotFirst: modZero && i > 0,
        isLast: i === context.length - 1
      }));
    }
  } else {
    ret = inverse(this);
  }
  return ret;
});
```

Note: This implementation uses [underscore `_.extend()`](https://underscorejs.org/#extend).

## Scenario: Print rows

Here's a scenario where this is useful:  In twitter bootstrap, each "span" div is inside of a "row-fluid" div (if using bootstrap responsive.css).  So, if I want three things, let's say videos, per row printed in the markup, you can't just use `{{#each}}` because all it does is iterate through the videos.  You could print the "span4"s but you wouldn't know when to print the "row-fluid".  Hence, we need our helper.

```html
{{#everyNth myArray theNumberN}}
{{/everyNth}}
```

Our new helper `everyNth` allows us to write code like this:

```html
{{#everyNth vids 3}}
  {{#if isModZeroNotFirst}}
    </div>
  {{/if}}
  {{#if isModZero}}
    <div class="row-fluid">
  {{/if}}
  <div class="span4">
    <div class="thumb">
      <a href="{{ linkUrl }}"><img src="{{ image }}" /></a>
    </div>
  </div>
  {{#if isLast}}
    </div>
  {{/if}}
{{/everyNth}}
```

To clarify the need and usage of these new variables:

1. **isModZero** - in this example, every 3 videos should be on a row.  When mod 3 is 0, create a row.
2. **isModZeroNotFirst** - when I create a row (mod 3 is 0), I also need to end the row, except before the first row.
3. **isLast** - if the length of the video array is not divisible by 3, the last row needs to close anyway.

The helper is simple, essentially just a copy of `#each` with a few new variables in context.  That's the beauty of Handlebars helpers.  With this little baby you can determine where you are in your iterations through your array.

What are some of the things you use Handlebars helpers for?

Every nth Item in Handlebars Loop

HandlebarsJs is a great Javascript templating engine.  It's pretty much Mustache templates on steriods -- or Rogaine or something like that.  Well, there's a great for loop, but it'd be cool if it had a loop index built in.  It doesn't have one as of the current version (1.0.0.beta.6).  But, we can make an easy helper.



## Update: "Native"

Thanks to a bit of looking, Zander (see comment thread below), has discovered that Handlebars [now supports a native loop index accessor called `@index`](https://github.com/wycats/handlebars.js/issues/250#issuecomment-9514811).  And there's a [jsfiddle to prove it](http://jsfiddle.net/mpetrovich/gER9M/).  Thanks, Zander.

## When We're Helping We're Happy

Compared to Mustache templates, Handlebars has the Rogaine element of helper functions.  You have the ability to register as many custom functions for use in your templates as you find useful.  And we're gonna make a sweet one.

Lots of languages have the built-in ability to let you access the current index of a `for` loop.  We'll have to build our own

## For Loop Index Helper

The default Handlebars loop helper is `{{#each}}` .  We will replace it with `{{#iter}}`.  It essentially copies the current implementation of the for loop and adds a few more parameters to the loop context.

```js
Handlebars.registerHelper('iter', function(context, options) {
  var fn = options.fn, inverse = options.inverse;
  var ret = "";
  
  if(context && context.length > 0) {
    for(var i=0, j=context.length; i<j; i++) {
      ret = ret + fn(_.extend({}, context[i], { i: i, iPlus1: i + 1 }));
    }
  } else {
    ret = inverse(this);
  }
  return ret;
});
```

The key line is:

```js
fn(_.extend({}, context[i], { i: i, iPlus1: i + 1 }))
```

`fn()` is the call to execute the block of the template surrounded by `{{#iter}}`.  We pass in `context[i]` as in the normal loop, but we extend it with `i` (the 0-based index) and `iPlus1` (for a 1-based index).

Here's an example usage:

```js
{{#iter myArray}}
  {{i}}. {{myModelField}}
{{/iter}}
```

This would print a list of numbers, then a period, the field values.  Pretty sweet eh?  Use Handlebars and bring new life and lushness to your crop of js templating.  Now with an index in your for loops!  

Note: This code snippet makes use of [underscore.js](http://underscorejs.org/).  You could easily not use `_.extend()`.

HandlebarsJs is a great Javascript templating engine.  It's pretty much Mustache templates on steriods -- or Rogaine or something like that.  Well, there's

Handlebars For-Loop Index

If you have to store your text strings for internationalization (i18n) on the server, that's <a href="https://jaketrent.com/post/i18n-strings-javascript/">one thing</a>.  But, if you can store them in Javascript, you might think about using RequireJs and its i18n plugin, because it makes it nice and easy.



Get the Plugin
--------------

RequireJs is a single [download](https://requirejs.org/docs/download.html).  It's an AMD-style module loader.  And it rocks.  Especially if you dig those little arrows ![arrow img](https://requirejs.org/i/arrow.png)!  

The [i18n plugin](https://requirejs.org/docs/api.html#i18n) is another .js file to [download](https://requirejs.org/docs/download.html#i18n).


Specify your Strings
--------------------

The i18n uses the philosophy that you have a default/fallback language specified that usually the entire set of strings that your app will display.  Then, you can specify a set of those strings in another language or even partially implement them.  For instance, if my default language is English and I have 10 strings total but then I only specify 6 of those strings in the Spanish version of the bundle, then English will be used for the remaining 4 as the fallback language.

Your directory structure should look something like this:

```bash
js/
  nls/
    spa/
      str.js
    str.js
  main.js
  require.js
  i18n.js
```

The important thing is that there is a subdirectory as sibling to main.js, your main Require module, that is named 'nls'.  This is what the plugin looks for by default.  The names of the 'str.js' files don't matter.  In fact you can have as many and name them things with meaning in to app if you'd like.

Here's an example bundle of the English/default bundle:

```javascript
define({
  'root': {
    welcome: 'Welcome!',
    eng_only_idiom: 'You have got to be pulling on my leg!'
  },
  'spa': true
});
```

In the `root` property, we default an object with string keys and the English text that we want associated with that key.  The name 'root' specifies that this is the default set of strings.

Below, we list a new property for each language code that our app supports (or doesn't if it's listed as false, but I just leave them off if they're false).  You can use whatever language code you care to use.  On our app, the server is feeding us a three-letter language code with no locale.  Browsers will feed you a two-letter code, with locale if available (eg, 'es-mx').

The Spanish bundle would look something like this:

```javascript
define({
  welcome: '¡bienvenido'
});
```

Note that only the `welcome` string was implemented.  English only things or unsupported or not-yet translated strings can just remain unmentioned in the language bundle.

Specify RequireJs Locale
------------------------

In our main Require module, we want to specify which is the current language so the plugin knows which language bundle to look up and use.  That might look like this:

```javascript
require({
  locale: lang
}, ['myModule'], function (myModule) {
  var myMod = new myModule()
  myMod.doCoolStuff();
});
```

We haven't used the language string yet.  We've only specified the current user's language.  In my case, with the language code being provided by the server, `lang` is a global js var that gets rendered on the html page from the server.  You could interrogate the browser langugage here instead via Javascript if you'd like.

Use i18n Strings in a Require Module
------------------------------------

We know what strings we need to have translated.  We know our current user's language.  And now finally we need to use our bundles.  Here's how to import the bundle via the i18n plugin into your require module:

```javascript
define(['i18n!nls/str'], function(str) {
  return {
    doCoolStuff: function () {
      alert(str.welcome);
    }
  }
});
```

Note that we require as a dependency the main/English `str.js`.  And because we import it with the 'i18n!' prefix, it will be read as a language bundle and the appropriate language's bundle will be used.  So if the require `locale` was set to 'spa', then we would see '¡bienvenido' alerted to our screen.  Pretty dang exciting. 

Bonus:  With Handlebars!
------------------------

But you wouldn't normally just blast out strings via your Javascript code.  At least, if you love your sanity, you'll stop using string concatenation and a Javascript-based templating language.  There are many out there, but one that I have recent success with is [HandlebarsJs](https://handlebarsjs.com/).  It's a superset of mustache -- based on the same syntax but with built-in helpers and ability to extend with other custom helper functions.

So, if we were using a Handlebars template to blast our i18n strings plus markup to the DOM, our handlebars template could look like this:

```javascript
<h1>{{ str.welcome }}</h1>

```

And you could import it and use it in your module:

```javascript
define(['i18n!nls/str', 'text!template'], function (str, myTmpl) {
  return {
    doCoolStuff: function () {
      var compiledTmpl = Handlebars.compile(myTmpl);
      document.body.appendChild(compiledTmpl({ str: str }));
    });
  }
});
```

Note that I'm making a couple leaps here:  Have the RequireJs [text plugin](https://requirejs.org/docs/api.html#text) available, and have handlebars.js available. 

Compile the template with handlebars and then pass in the `str` module as a property called `str` (or whatever) to the template and then just access it like the Javascript objec that it is within the template, using `str.welcome` or `str.eng_only_idiom` or whatever other strings you invent in that wild, internationalized mind of yours.

If you have to store your text strings for internationalization (i18n) on the server, that's <a href="https://jaketrent.com/post/i18n-strings-javascript/">on