Configuration

There are several ways to configure Layouts and managed Views.

Options

There are a number of options you may wish to specify depending on how you wish to use LayoutManager.

Global

To configure at a global level, start with the configure call:

Backbone.Layout.configure({
  // Put options here.
});

From here you specify global values that will appear in options for all Views (managed by LayoutManager).

Definition

Useful for when you want options to exist for all instances created on a specific View.

Backbone.Layout.extend({
  // Put options here.
});

Instance

Lastly, you can specify options while creating a new instance, which can be very handy for on-the-fly Views.

new Backbone.Layout({ /* Put options here. */ });

Properties and methods

There are several predefined defaults that you may wish to change depending on your setup.

prefix

A string value that will be prefixed to the template property of all managed Views when fetch is called. You should always end with a trailing /.

Default:

prefix: ""

Example:

prefix: "app/templates/"

manage

A boolean value that determines if setupView should be called automatically for the Backbone.View. This is really useful to treat Views as Layouts.

Example:

manage: true

el

A boolean value that determines if the View's element should derive from the template or the View. If you set to false, the View's internal el will be set to the template.

Example:

el: false

Warning

It is not recommended nor suppported to use multiple top level elements. This means if your template looks something like:

<h1>My awesome template</h1>
<ul></ul>

You will receive a console.warn message along with a stack trace in your developer tools console. There are many inconsistencies and problems related to multiple top level elements and Backbone. If you know the risks and understand the pitfalls you can suppress this warning with Backbone.configure({ suppressWarnings: true });.

suppressWarnings

This property may be set to true or false. If you set this to true all console.warn's will be silenced.

Default:

suppressWarnings: false

deferred

Uses jQuery deferreds for internal operation and the return value for render.

Default:

deferred: function() {
  return $.Deferred();
}

Example:

deferred: function() {
  return _.Deferred();
}

fetch(path)

Uses jQuery to find a selector and returns its innerHTML content as a template function. This method may be asynchronous.

Default:

fetch: function(path) {
  return _.template($(path).html());
}

Example:

fetch: function(path) {
  // To put this method into async-mode, simply call `async` and store the
  // return value (callback function).
  var done = this.async();

  // Asynchronously fetch the path in `template` and compile the contents
  // into a template.
  $.get(path, function(contents) {
    // Call the asynchronous callback with the function.
    done(_.template(contents));
  }, "text");
}

partial($root, $el, rentManager, manager)

Uses jQuery to find the View's location and inserts the rendered element there. Use the manager object to determine if the View is in insert mode, and if so, the View should be inserted instead of replacing the parent's contents. Defaults to replace via innerHTML. The rentManager argument refers to the root's __manager__ object. You can detect if the View is being inserted into a View that's managing it's own element, in which case you'd want filter instead of find.

You should typically not need to override this method.

Default:

partial: function($root, $el, rentManager, manager) {
  // If selector is specified, attempt to find it.
  if (manager.selector) {
    $root = $root[rentManager.noel ? "filter" : "find"](manager.selector);
  }

  // Use the insert method if insert argument is true.
  if (manager.insert) {
    this.insert($root, $el);
  } else {
    this.html($root, $el);
  }
}

html($root, contents)

Override this with a custom HTML method, passed a root jQuery collection and an contents (may be a DOM Element or a String) to replace the innerHTML with.

Default:

html: function($root, contents) {
  $root.html(content);
}

insert($root, $el)

Very similar to HTML except this one will appendChild and only every receives jQuery collections.

Default:

insert: function($root, $el) {
  $root.append($el);
}

when(promises)

This function will trigger callbacks based on the success/failure of one or more deferred objects.

when: function(promises) {
  return $.when.apply(null, promises);
}

render(template, context)

Renders a template with the Function or String provided as the template variable. This method may be asynchronous.

Default:

render: function(template, context) {
  return template(context);
}

Example:

render: function(template, context) {
  // To put this method into async-mode, simply call `async` and store the
  // return value (callback function).
  var done = this.async();

  // Assuming the template function accepts the context object and a callback
  // function, this is how you would render the template.
  template(context, function(contents) {
    done(contents);
  });
}

contains(parent, child)

This method uses jQuery to determine if a child element exists in a parent element. This method will always received DOM Elements as arguments.

Default:

contains: function(parent, child) {
  return $.contains(parent, child);
}