Backbone Boilerplate Layout Manager

Question

Can someone help explain / provide an example on how to use the LayoutManager within the Backbone Bolierplate?

Within app.js I can see a useLayout function that extends the main app object. Within here it appears to be setting a base layout element:

// Helper for using layouts.
    useLayout: function(name, options) {
      // Enable variable arity by allowing the first argument to be the options
      // object and omitting the name argument.
      if (_.isObject(name)) {
        options = name;
      }

      // Ensure options is an object.
      options = options || {};

      // If a name property was specified use that as the template.
      if (_.isString(name)) {
        options.template = name;
      }

      // Create a new Layout with options.
      var layout = new Backbone.Layout(_.extend({
        el: "#main"
      }, options));

      // Cache the refererence.
      return this.layout = layout;
    }

Is that correct? If so, do I somehow the use the 'UseLayout' function with the applications Router? ...to add different UI elements/nested views to the main view?

Thanks.

Answer 1

I will usually have an "app" object that stores all my settings needed throughout the application. This object then extends some useful functions like the one you listed above. For example:

var app = {
  // The root path to run the application.
  root: "/",
  anotherGlobalValue: "something",
  apiUrl: "http://some.url"
};

// Mix Backbone.Events, modules, and layout management into the app object.
return _.extend(app, {
    // Create a custom object with a nested Views object.
    module: function(additionalProps) {
      return _.extend({ Views: {} }, additionalProps);
    },

    // Helper for using layouts.
    useLayout: function(options) {
      // Create a new Layout with options.
      var layout = new Backbone.Layout(_.extend({
        el: "#main"
      }, options));

      return this.layout = layout;
    },

    // Helper for using form layouts.
    anotherUsefulFunction: function(options) {
      // Something useful
    }

  }, Backbone.Events);

});

Now in my router I would do something like:

app.useLayout({ template: "layout/home" })
  .setViews({
    ".promotional-items": new Promotions.Views.PromotionNavigation(),
    ".featured-container": new Media.Views.FeaturedSlider({
      vehicles: app.vehicles,
      collection: featuredCollection
    })
}).render().then(function() {
  //Do something once the layout has rendered.
});

I have just taken a sample from one of my applications, but I am sure you can get the idea. My main layout is basically just a layout template file which holds the elements so the views can be injected into their respective holders.

Answer 2

You would use it as if you're using a regular Backbone View. Instead of building the View directly, you can use this to create a new instance. The code you posted is a wrapper object on top of the Backbone Layout Manager extension with el: #main set as the default View element which is overridable.

var layout = new useLayout({ template: "#viewElement", ... });