Regions

Regions provide consistent methods to manage, show and destroy views in your applications and layouts. You can use a jQuery selector to identify where your region must be displayed.

See the documentation for laying out views for an introduction in managing regions throughout your application.

A Region is a Marionette.Object and has all of its functionality.

Regions maintain the View's lifecycle while showing or emptying a view.

Documentation Index

• Defining the Application Region
• Defining Regions
  • String Selector
  • Additional Options
  • Specifying regions as a Function
  • Using a RegionClass
  • Referencing UI in regions
• Adding Regions
• Removing Regions
• Using Regions on a view
• Showing a View
  • Checking whether a region is showing a view
• Showing a Template
• Emptying a Region
  • Preserving Existing Views
  • Detaching Existing Views
• reset A Region
• Set How View's el Is Attached

Defining the Application Region

The Application defines a single region el using the region attribute. This can be accessed through getRegion() or have a view displayed directly with showView(). Below is a short example:

var Mn = require('backbone.marionette');
var SomeView = require('./view');

var App = Mn.Application.extend({
  region: '#main-content',

  onStart: function() {
    var main = this.getRegion();  // Has all the properties of a `Region`
    main.show(new SomeView());
  }
});

For more information, see the Application docs.

Defining Regions

Marionette supports multiple ways to define regions on your Application or View. This section will document the different types as applied to View, although they will work for Application as well - just replace regions with region in your definition.

String Selector

You can use a jQuery string selector to define regions.

var Mn = require('backbone.marionette');

var MyView = Mn.View.extend({
  regions: {
    mainRegion: '#main'
  }
});

Additional Options

You can define regions with an object literal. Object literal definitions expect an el property - the jQuery selector string to hook the region into. The object literal is the most common way to define whether showing the region overwrites the el or just overwrites the content (the default behavior).

To overwrite the parent el of the region with the rendered contents of the inner View, use replaceElement as so:

var Mn = require('backbone.marionette');

var OverWriteView = Mn.View.extend({
  className: '.new-class'
});

var MyView = Mn.View.extend({
  regions: {
    main: {
      el: '.overwrite-me',
      replaceElement: true
    }
  }
});
var view = new MyView();
view.render();

console.log(view.$('.overwrite-me').length); // 1
console.log(view.$('.new-class').length); // 0

view.showChildView('main', new OverWriteView());

console.log(view.$('.overwrite-me').length); // 0
console.log(view.$('.new-class').length); // 1

When the instance of MyView is rendered, the .overwrite-me element will be removed from the DOM and replaced with an element of .new-class - this lets us do things like rendering views inside table or select more easily - these elements are usually very strict on what content they will allow.

DEPRECATED: The selector option of a region is deprecated in favor of using el

var MyView = Mn.View.extend({
  regions: {
    deprecatedRegionDefinition: {
      selector: '.foo',
      replaceElement: true
    },
    regionDefinition: {
      el: '.bar',
      replaceElement: true
    }
  }
});

Specifying regions as a Function

The regions attribute on a view can be a function returning an object:

var Mn = require('backbone.marionette');

var MyView = Mn.View.extend({
  regions: function(){
    return {
      firstRegion: '#first-region'
    };
  }
});

Using a RegionClass

If you've created a custom region class, you can use it to define your region.

var Mn = require('backbone.marionette');

var MyRegion = Mn.Region.extend({
  onShow: function(){
    // Scroll to the middle
    this.$el.scrollTop(this.currentView.$el.height() / 2 - this.$el.height() / 2);
  }
});

var MyView = Mn.View.extend({
  regions: {
    firstRegion: {
      el: '#first-region',
      regionClass: MyRegion
    }
  }
});

Live example

Referencing UI in regions

The UI attribute can be useful when setting region selectors - simply use the @ui. prefix:

var Mn = require('backbone.marionette');

var MyView = Mn.View.extend({
  ui: {
    region: '#first-region'
  },
  regions: {
    firstRegion: '@ui.region'
  }
});

Live example

Adding Regions

To add regions to a view after it has been instantiated, simply use the addRegion method:

var MyView = require('./myview');

myView = new MyView();
myView.addRegion('thirdRegion', '#third-region');

Now we can access thirdRegion as we would the others.

You can also add multiple regions using addRegions.

var MyView = require('./myview');

myView = new MyView();
myView.addRegions({
  main: {
    el: '.overwrite-me',
    replaceElement: true
  },
  sidebar: '.sidebar'
});

Removing Regions

You can remove all of the regions from a view by calling removeRegions or you can remove a region by name using removeRegion. When a region is removed the region will be destroyed.

var Mn = require('backbone.marionette');

var MyView = Mn.View.extend({
  regions: {
    main: '.main',
    sidebar: '.sidebar',
    header: '.header'
  }
});

var myView = new MyView();

// remove only the main region
var mainRegion = myView.removeRegion('main');

mainRegion.isDestroyed(); // -> true

// remove all regions
myView.removeRegions();

Using Regions on a view

In addition to adding and removing regions there are a few methods to help utilize regions.

• getRegion(name) - Request a region from a view by name.
• getRegions() - Returns an object literal of all regions on the view organized by name.
• hasRegion(name) - Check if a view has a region.
• emptyRegions() - Empty all of the regions on a view.

Showing a View

Once a region is defined, you can call its show method to display the view:

var myView = new MyView();
var childView = new MyChildView();
var mainRegion = myView.getRegion('main');

// render and display the view
mainRegion.show(childView);

This is equivalent to a view's showChildView which can be used as:

var myView = new MyView();
var childView = new MyChildView();

// render and display the view
myView.showChildView('main', childView);

Both forms take an options object that will be passed to the events fired during show.

For more information on showChildView and getChildView, see the Documentation for Views

Checking whether a region is showing a view

If you wish to check whether a region has a view, you can use the hasView function. This will return a boolean value depending whether or not the region is showing a view.

var myView = new MyView();
var mainRegion = myView.getRegion('main');

mainRegion.hasView() // false
mainRegion.show(new OtherView());
mainRegion.hasView() // true

If you show a view in a region with an existing view, Marionette will remove the existing View before showing the new one.

Showing a Template

You can show a template or a string directly into a region. Additionally you can pass an object literal containing a template and any other view options. Under the hood a Marionette.View is instantiated using the template.

var myView = new MyView();

var template = _.template('This is the <%- section %> page');
var templateContext = templateContext: { section: 'main' };

myView.showChildView('main', {
  template: template,
  templateContext: templateContext
});

myView.showChildView('header', _.template('Welcome to the site'));

myView.getRegion('other').show('This text is in another region');

Emptying a Region

You can remove a view from a region (effectively "unshowing" it) with region.empty() on a region:

var myView = new MyView();

myView.showChildView('main', new OtherView());
var mainRegion = myView.getRegion('main');
mainRegion.empty();

This will destroy the view, clean up any event handlers and remove it from the DOM. When a region is emptied empty events are triggered.

Note: If the region does not currently contain a View it will detach any HTML inside the region when emptying. If the region does contain a View any HTML that doesn't belong to the View will remain.

Preserving Existing Views

DEPRECATED: preventDestroy is deprecated. See Detaching Existing Views for how to preserve a shown view

If you replace the current view with a new view by calling show, by default it will automatically destroy the previous view. You can prevent this behavior by passing {preventDestroy: true} in the options parameter. Several events will also be triggered on the views.

// Show the first view.
var myView = new MyView();
var childView = new MyChildView();

var mainRegion = myView.getRegion('main');

mainRegion.show(childView);

// Replace the view with another. The
// `destroy` method is called for you
var anotherView = new AnotherView();
mainRegion.show(anotherView);

// Replace the view with another.
// Prevent `destroy` from being called
var anotherView2 = new AnotherView();
mainRegion.show(anotherView2, {preventDestroy: true});
mainRegion.empty({preventDestroy: true});

NOTE When using preventDestroy: true you must be careful to cleanup your old views manually to prevent memory leaks.

Detaching Existing Views

If you want to detach an existing view from a region, use detachView.

var myView = new MyView();

var myOtherView = new MyView();

var childView = new MyChildView();

// render and display the view
myView.showChildView('main', childView);

// ... somewhere down the line
myOtherView.showChildView('main', myView.getRegion('main').detachView());

reset A Region

A region can be reset at any time. This destroys any existing view being displayed, and deletes the cached el. The next time the region shows a view, the region's el is queried from the DOM.

var myView = new MyView();
myView.showChildView('main', new OtherView());
var mainRegion = myView.getRegion('main');
myRegion.reset();

This can be useful in unit testing your views.

Set How View's el Is Attached

Override the region's attachHtml method to change how the view is attached to the DOM. This method receives one parameter - the view to show.

The default implementation of attachHtml is essentially:

var Mn = require('backbone.marionette');

Mn.Region.prototype.attachHtml = function(view){
  this.el.appendChild(view.el);
}

It is also possible to define a custom attach method for a single region by extending from the Region class and including a custom attachHtml method.

This example will make a view slide down from the top of the screen instead of just appearing in place:

var Mn = require('backbone.marionette');

var ModalRegion = Mn.Region.extend({
  attachHtml: function(view){
    // Some effect to show the view:
    this.$el.empty().append(view.el);
    this.$el.hide().slideDown('fast');
  }
});

var MyView = Mn.View.extend({
  regions: {
    mainRegion: '#main-region',
    modalRegion: {
      regionClass: ModalRegion,
      el: '#modal-region'
    }
  }
});