1 Handlebars

SproutCore comes bundled with Handlebars, a semantic templating language. These templates look like regular HTML, with embedded handlebars expressions:

Hello, <b>{{name}}</b>!

You should store your Handlebars templates inside your application’s resources/templates directory. Make sure you save them with a .handlebars extension. At runtime, SproutCore will compile and load these templates so they are available for you to use in your views.

2 SC.TemplateView

An SC.TemplateView is a view that is responsible for rendering a Handlebars template and inserting it into the DOM.

To tell the TemplateView which template to use, set its templateName property. For example, if I saved a template to a file called sayhello.handlebars, I would set the templateName property to "sayhello".

Hello, <b>{{name}}</b>!

var view = SC.TemplateView.create({
  templateName: 'sayhello',
  name: "Bob"
});

3 Handlebars Basics

As you’ve already seen, you can print the value of a property by enclosing it in a Handlebars expression, or a series of braces, like this:

My new car is {{color}}.

This will look up and print the TemplateView’s color property. For example, if your view looks like this:

App.CarView = SC.TemplateView.extend({
  color: 'blue'
});

Your view would appear in the browser like this:

My new car is blue.

All of the features described in this guide are bindings aware. That means that if the values used by your templates ever change, your HTML will be updated automatically. It’s like magic.

In order to know which part of your HTML to update when an underlying property changes, Handlebars will insert marker elements with a unique ID. If you look at your application while it’s running, you might notice these extra elements:

My new car is <span id="sc232">blue</span>.

Because all Handlebars expressions are wrapped in these markers, make sure each HTML tag stays inside the same block. For example, you shouldn’t do this:

<!-- Don't do it! -->

<div {{#if isUrgent}}class="urgent"{{/if}}>

3.1 {{#if}}, {{else}}, and {{#unless}}

Sometimes you may only want to display part of your template if a property exists. For example, let’s say we have a view with a person property that contains an object with firstName and lastName fields:

App.SayHelloView = SC.TemplateView.extend({
  person: SC.Object.create({
    firstName: "Joy",
    lastName: "Clojure"
  })
});

In order to display part of the template only if the person object exists, we can use the {{#if}} helper to conditionally render a block:

{{#if person}}
  Welcome back, <b>{{person.firstName}} {{person.lastName}}</b>!
{{/if}}

If the expression evaluates to falsy, we can also display an alternate template using {{else}}:

{{#if person}}
  Welcome back, <b>{{person.firstName}} {{person.lastName}}</b>!
{{else}}
  Please log in.
{{/if}}

To only render a block if a value is falsy, use {{#unless}}:

{{#unless hasPaid}}
  You owe: ${{total}}
{{/unless}}

{{#if}} and {{#unless}} are examples of block expressions. These allow you to invoke a helper with a portion of your template. Block expressions look like normal expressions except that they contain a hash (#) before the helper name, and require a closing expression.

3.2 {{#with}}

Sometimes you may want to invoke a section of your template with a context different than the SC.TemplateView. For example, we can clean up the above template by using the {{#with}} helper:

{{#with person}}
  Welcome back, <b>{{firstName}} {{lastName}}</b>!
{{/with}}

3.3 Binding Element Attributes with {{bindAttr}}

In addition to text, you may also want your templates to dictate the attributes of your HTML elements. For example, imagine a view that contains a URL:

App.LogoView = SC.TemplateView.extend({
  logoUrl: 'http://www.mycorp.com/images/logo.png'
});

The best way to display the URL as an image in Handlebars is like this:

<div id="logo">
  <img {{bindAttr src="logoUrl"}} alt="Logo">
</div>

This generates the following HTML:

<div id="logo">
  <img src="http://www.mycorp.com/images/logo.png" alt="Logo">
</div>

If you use {{bindAttr}} with a Boolean value, it will add or remove the specified attribute. For example, given this SproutCore view:

App.InputView = SC.TemplateView.extend({
  isSelected: true
});

And this template:

<input type="checkbox" {{bindAttr checked="isSelected"}}>

Handlebars will produce the following HTML element:

<input type="checkbox" checked>

3.4 Binding Class Names with {{bindAttr}}

The class attribute can be bound like any other attribute, but it also has some additional special behavior. The default behavior works like you’d expect:

App.AlertView = SC.TemplateView.extend({
  priority: "p4",
  isUrgent: true
});

<div {{bindAttr class="priority"}}>
  Warning!
</div>

This template will emit the following HTML:

<div class="p4">
  Warning!
</div>

If the value to which you bind is a Boolean, however, the dasherized version of that property will be applied as a class:

<div {{bindAttr class="isUrgent"}}>
  Warning!
</div>

This emits the following HTML:

<div class="is-urgent">
  Warning!
</div>

Unlike other attributes, you can also bind multiple classes:

<div {{bindAttr class="isUrgent priority"}}>
  Warning!
</div>

3.5 Localized Strings with {{loc}}

SproutCore has built-in support for localized applications. To emit a localized version of a string, use the {{loc}} helper:

{{loc myLocalizedString}}

4 Building a View Hierarchy

So far, we’ve discussed writing templates for a single view. However, as your application grows, you will often want to create a hierarchy of views to encapsulate different areas on the page. Each view is responsible for handling events and maintaining the properties needed to display it.

4.1 {{view}}

To add a child view to a parent, use the {{view}} helper, which takes a path to a view class.

// Define parent view
App.UserView = SC.TemplateView.extend({
  templateName: 'user',

  firstName: "Albert",
  lastName: "Hofmann"
});

// Define child view
App.InfoView = SC.TemplateView.extend({
  templateName: 'info',

  posts: 25,
  hobbies: "Riding bicycles"
});

User: {{firstName}} {{lastName}}
{{view App.InfoView}}

<b>Posts:</b> {{posts}}
<br>
<b>Hobbies:</b> {{hobbies}}

If we were to create an instance of App.UserView and render it, we would get a DOM representation like this:

User: Albert Hofmann
<div>
  <b>Posts:</b> 25
  <br>
  <b>Hobbies:</b> Riding bicycles
</div>

4.2 Relative Paths

Instead of specifying an absolute path, you can also specify which view class to use relative to the parent view. For example, we could nest the above view hierarchy like this:

App.UserView = SC.TemplateView.extend({
  templateName: 'user',

  firstName: "Albert",
  lastName: "Hofmann",

  InfoView: SC.TemplateView.extend({
    templateName: 'info',

    posts: 25,
    hobbies: "Riding bicycles"
  })
});

User: {{firstName}} {{lastName}}
{{view InfoView}}

4.3 Setting Child View Templates

If you’d like to specify the template your child views use (instead of having to place them in a separate Handlebars file), you can use the block form of the {{view}} helper. We might rewrite the above example like this:

App.UserView = SC.TemplateView.extend({
  templateName: 'user',

  firstName: "Albert",
  lastName: "Hofmann"
});

App.InfoView = SC.TemplateView.extend({
  posts: 25,
  hobbies: "Riding bicycles"
});

User: {{firstName}} {{lastName}}
{{#view App.InfoView}}
  <b>Posts:</b> {{posts}}
  <br>
  <b>Hobbies:</b> {{hobbies}}
{{/view}}

When you do this, it may be helpful to think of it as assigning views to portions of the page. This allows you to encapsulate event handling for just that part of the page.

4.4 Setting Up Bindings

So far in our examples, we have been setting static values directly on the views. But to best implement an MVC architecture, we should actually be binding the properties of our views to the controller layer.

Let’s set up a controller to represent our user data:

App.userController = SC.ObjectController.create({
  content: SC.Object.create({
    firstName: "Albert",
    lastName: "Hofmann",
    posts: 25,
    hobbies: "Riding bicycles"
  })
});

Now let’s update App.UserView to bind to App.userController:

App.UserView = SC.TemplateView.extend({
  templateName: 'user',

  firstNameBinding: 'App.userController.firstName',
  lastNameBinding: 'App.userController.lastName'
});

When we only have a few bindings to configure, like with App.InfoView, it is sometimes useful to be able to declare those bindings in the template. You can do that by passing additional arguments to the {{#view}} helper. If all you’re doing is configuring bindings, this often allows you to bypass having to create a new subclass.

User: {{firstName}} {{lastName}}
{{#view App.InfoView postsBinding="App.userController.posts"
        hobbiesBinding="App.userController.hobbies"}}
  <b>Posts:</b> {{posts}}
  <br>
  <b>Hobbies:</b> {{hobbies}}
{{/view}}

4.5 Modifying a View’s HTML

When you append a view, it creates a new HTML element that holds its content. If your view has any child views, they will also be displayed as child nodes of the parent’s HTML element.

By default, new instances of SC.View create a <div> element. You can override this by passing a tagName parameter:

{{view App.InfoView tagName="span"}}

You can also assign an ID attribute to the view’s HTML element by passing an id parameter:

{{view App.InfoView id="info-view"}}

This makes it easy to style using CSS ID selectors:

/** Give the view a red background. **/
#info-view {
  background-color: red;
}

You can assign class names similarly:

{{view App.InfoView class="info urgent"}}

You can bind class names to a property of the view by using classBinding instead of class. The same behavior as described in bindAttr applies:

App.AlertView = SC.TemplateView.extend({
  priority: "p4",
  isUrgent: true
});

{{view App.AlertView classBinding="isUrgent priority"}}

This yields a view wrapper that will look something like this:

<div id="sc420" class="sc-view is-urgent p4"></div>

5 Displaying a List of Items

If you need to display a basic list of items, use Handlebar’s {{#each}} helper:

App.PeopleView = SC.TemplateView.extend({
  people: [ SC.Object.create({ name: 'Steph' }),
            SC.Object.create({ name: 'Tom' }) ]
});

{{#each people}}
  Hello, {{name}}!
{{/each}}

This will print a list like this:

<ul>
  <li>Hello, Steph!</li>
  <li>Hello, Tom!</li>
</ul>

5.1 SC.TemplateCollectionView

Sometimes you will need each item in your list to handle events. In that case, you will need more sophistication than what {{#each}} can provide. You can use the {{#collection}} helper to create a new SC.TemplateCollectionView. You can bind the instance of SC.TemplateCollectionView to an array, and it will create a new SC.TemplateView for each item.

Usually, you will bind the collection to an SC.ArrayController, like this:

App.peopleController = SC.ArrayController.create({
  content: ['Steph', 'Tom', 'Ryan', 'Chris', 'Jill']
});

{{#collection SC.TemplateCollectionView contentBinding="App.peopleController"}}
  Hi, {{content}}!
{{/collection}}

Remember that under the hood, SC.TemplateCollectionView creates a new view for each item in the bound array. By default, each new view will be an instance of SC.TemplateView. You can tell the collection which type of view to create instances of by subclassing SC.TemplateCollectionView and supplying a custom class:

App.PeopleCollectionView = SC.TemplateCollectionView.extend({
  itemView: SC.TemplateView.extend({
    mouseDown: function(evt) {
      window.alert('You clicked on ' + this.get('content'));
    }
  })
});

{{#collection App.PeopleCollectionView contentBinding="App.peopleController"}}
  Hi, {{content}}!
{{/collection}}

If you run this code, you should see an alert every time you click on one of the items.

The {{#collection}} helper takes the same options as {{#view}}, as described above. For example, you can set an HTML id attribute on the container of SC.TemplateCollectionView like this:

{{collection App.MyCollectionView id="my-collection"}}

What if you want to set the class name of every child view, though? If you prepend an option with item, that option will instead be set on the child. For example, let’s say you wanted to set a class name on each item in your collection:

{{collection App.MyCollectionView itemClass="collection-item"}}

6 Using SC.TemplateView Inside Desktop Controls

If you’re building a desktop-style application, you can get the best of both native and web worlds by integrating SC.TemplateViews into SproutCore’s other controls. For example, you can easily embed an SC.TemplateView inside an SC.ScrollView:

App.mainPage = SC.Page.design({
  mainPane: SC.MainPane.extend({
    childViews: ['scrollView'],

    scrollView: SC.ScrollView.design({
      contentView: SC.TemplateView.design({
        templateName: 'main_page'
      })
    })
  })
});

7 Changelog

• May 5, 2011: Initial version by Tom Dale

Chapters

1. Handlebars

2. SC.TemplateView

3. Handlebars Basics

   • {{#if}}, {{else}}, and {{#unless}}

   • {{#with}}

   • Binding Element Attributes with {{bindAttr}}

   • Binding Class Names with {{bindAttr}}

   • Localized Strings with {{loc}}

4. Building a View Hierarchy

   • {{view}}

   • Relative Paths

   • Setting Child View Templates

   • Setting Up Bindings

   • Modifying a View’s HTML

5. Displaying a List of Items

   • SC.TemplateCollectionView

6. Using SC.TemplateView Inside Desktop Controls

7. Changelog