marionette.itemview.md

Marionette.ItemView

An ItemView is a view that represents a single item. That item may be a Backbone.Model or may be a Backbone.Collection. Whichever it is though, it will be treated as a single item.

Documentation Index

• ItemView render
• Events and Callback Methods
  • "before:render" / onBeforeRender event
  • "render" / onRender event
  • "before:close" / onBeforeClose event
  • "close" / onClose event
• ItemView serializeData
• Organizing ui elements
• modelEvents and collectionEvents

ItemView render

An item view has a render method built in to it, and uses the Renderer object to do the actual rendering.

You should provide a template attribute on the item view, which will be either a jQuery selector:

MyView = Backbone.Marionette.ItemView.extend({
  template: "#some-template"
});

new MyView().render();

.. or a function taking a single argument: the object returned by ItemView.serializeData:

my_template_html = '<div><%= args.name %></div>'
MyView = Backbone.Marionette.ItemView.extend({
  template : function(serialized_model) {
    var name = serialized_model.name;
    return _.template(my_template_html, {
        name : name,
        some_custom_attribute : some_custom_key
    }, {variable: 'args'});
  }
});

new MyView().render();

Note that using a template function allows passing custom arguments into the _.template function, including a third "settings" argument, as used in the example above.

According to the Underscore docs, using the "variable" setting "can significantly improve the speed at which a template is able to render." Using this setting also requires you to read data arguments from an object, as demonstrated in the example above.

Events and Callback Methods

There are several events and callback methods that are called for an ItemView. These events and methods are triggered with the Marionette.triggerMethod function, which triggers the event and a corresponding "on{EventName}" method.

"before:render" / onBeforeRender event

Triggered before an ItemView is rendered. Also triggered as "item:before:render" / onItemBeforeRemder.

Backbone.Marionette.ItemView.extend({
  onBeforeRender: function(){
    // set up final bits just before rendering the view's `el`
  }
});

"render" / onRender event

Triggered after the view has been rendered. You can implement this in your view to provide custom code for dealing with the view's el after it has been rendered.

Also triggered as "item:render" / onItemRender.

Backbone.Marionette.ItemView.extend({
  onRender: function(){
    // manipulate the `el` here. it's already
    // been rendered, and is full of the view's
    // HTML, ready to go.
  }
});

"before:close" / onBeforeClose event

Triggered just prior to closing the view, when the view's close() method has been called. Also triggered as "item:before:close" / onItemBeforeClose.

Backbone.Marionette.ItemView.extend({
  onBeforeClose: function(){
    // manipulate the `el` here. it's already
    // been rendered, and is full of the view's
    // HTML, ready to go.
  }
});

"close" / onClose event

Triggered just after the view has been closed. Also triggered as "item:close" / onItemClose.

Backbone.Marionette.ItemView.extend({
  onClose: function(){
    // custom closing and cleanup goes here
  }
});

ItemView serializeData

Item views will serialize a model or collection, by default, by calling .toJSON on either the model or collection. If both a model and collection are attached to an item view, the model will be used as the data source. The results of the data serialization will be passed to the template that is rendered.

If the serialization is a model, the results are passed in directly:

var myModel = new MyModel({foo: "bar"});

new MyItemView({
  template: "#myItemTemplate",
  model: myModel
});

MyItemView.render();

<script id="myItemTemplate" type="template">
  Foo is: <%= foo %>
</script>

If the serialization is a collection, the results are passed in as an items array:

var myCollection = new MyCollection([{foo: "bar"}, {foo: "baz"}]);

new MyItemView({
  template: "#myCollectionTemplate",
  collection: myCollection
});

MyItemView.render();

<script id="myCollectionTemplate" type="template">
  <% _.each(items, function(item){ %>
    Foo is: <%= foo %>
  <% }); %>
</script>

If you need custom serialization for your data, you can provide a serializeData method on your view. It must return a valid JSON object, as if you had called .toJSON on a model or collection.

Backbone.Marionette.ItemView.extend({
  serializeData: function(){
    return {
      "some attribute": "some value"
    }
  }
});

Organizing UI Elements

As documented in Marionette.View, you can specify a ui hash in your view that maps UI elements by their jQuery selectors. This is especially useful if you access the same UI element more than once in your view's code. Instead of duplicating the selector, you can simply reference it by this.ui.elementName:

Backbone.Marionette.ItemView.extend({
  tagName: "tr",

  ui: {
    checkbox: "input[type=checkbox]"
  },

  onRender: function() {
    if (this.model.get('selected')) {
      this.ui.checkbox.addClass('checked');
    }
  }
});

modelEvents and collectionEvents

ItemViews can bind directly to model events and collection events in a declarative manner:

Marionette.ItemView.extend({
  modelEvents: {
    "change": "modelChanged"
  },

  collectionEvents: {
    "add": "modelAdded"
  }
});

For more information, see the Marionette.View documentation.