Region managers provide a consistent way to manage your views and show / close them in your application. They use a jQuery selector to show your views in the correct place. They also call extra methods on your views to facilitate additional functionality.
Regions can be added to the application by calling the addRegions
method on
your application instance. This method expects a single hash parameter, with
named regions and either jQuery selectors or Region
objects. You may
call this method as many times as you like, and it will continue adding regions
to the app.
MyApp.addRegions({
mainRegion: "#main-content",
navigationRegion: "#navigation"
});
As soon as you call addRegions
, your region managers are available on your
app object. In the above, example MyApp.mainRegion
and MyApp.navigationRegion
would be available for use immediately.
If you specify the same region name twice, the last one in wins.
You can specify an el
for the region manager to manage at the time
that the region manager is instantiated:
var mgr = new Backbone.Marionette.Region({
el: "#someElement"
});
Once a region manager has been defined, you can call the show
and close
methods on it to render and display a view, and then
to close that view:
var myView = new MyView();
// render and display the view
MyApp.mainRegion.show(myView);
// closes the current view
MyApp.mainRegion.close();
If you replace the current view with a new view by calling show
,
it will automatically close the previous view.
// show the first view
var myView = new MyView();
MyApp.mainRegion.show(myView);
// replace view with another. the
// `close` method is called for you
var anotherView = new AnotherView();
MyApp.mainRegion.show(anotherView);
A region can be reset
at any time. This will close any existing view
that is being displayed, and delete the cached el
. The next time the
region is used to show a view, the region's el
will be queried from
the DOM.
myRegion.reset();
This is useful for scenarios where a region is re-used across view instances, or in unit testing.
If you need to change how the view is attached to the DOM when
showing a view via a region, override the open
method of the
region. This method receives one parameter - the view to show.
The default implementation of open
is:
Marionette.Region.prototype.open = function(view){
this.$el.html(view.el);
}
This will replace the contents of the region with the view's
el
/ content. You can change to this be anything you wish,
though, facilitating transition effects and more.
Marionette.Region.prototype.open = function(view){
this.$el.hide();
this.$el.html(view.el);
this.$el.slideDown("fast");
}
This example will cause a view to slide down from the top of the region, instead of just appearing in place.
There are some scenarios where it's desirable to attach an existing view to a region manager, without rendering or showing the view, and without replacing the HTML content of the region. For example, SEO and accessibiliy often need HTML to be generated by the server, and progressive enhancement of the HTML.
There are two ways to accomplish this:
- set the
currentView
in the region manager's constructor - call
attachView
on the region manager instance
var myView = new MyView({
el: $("#existing-view-stuff")
});
var manager = new Backbone.Marionette.Region({
el: "#content",
currentView: myView
});
MyApp.addRegions({
someRegion: "#content"
});
var myView = new MyView({
el: $("#existing-view-stuff")
});
MyApp.someRegion.attachView(myView);
A region manager will raise a few events during it's showing and closing of views:
- "view:show" - when the view has been rendered and displayed
- "onShow" - called on the region when the view has been rendered
- "view:closed" - when the view has been closed
You can bind to these events and add code that needs to run with your region manager, opening and closing views.
MyApp.mainRegion.on("view:show", function(view){
// manipulate the `view` or do something extra
// with the region manager via `this`
});
MyApp.mainRegion.on("view:closed", function(view){
// manipulate the `view` or do something extra
// with the region manager via `this`
});
MyRegion = Backbone.Marionette.Region.extend({
// ...
onShow: function(view){
// the `view` has been shown
}
});
The region manager will call an onShow
method on the view
that was displayed. It will also trigger a "show" event
from the view:
MyView = Backbone.View.extend({
onShow: function(){
// the view has been shown
}
});
view = new MyView();
view.on("show", function(){
// the view has been shown.
});
MyApp.mainRegion.show(view);
You can define a custom region manager by extending from
Region
. This allows you to create new functionality,
or provide a base set of functionality for your app.
Once you define a region manager type, you can still call the
addRegions
method. Specify the region manager type as the
value - not an instance of it, but the actual constructor
function.
var FooterRegion = Backbone.Marionette.Region.extend({
el: "#footer"
});
MyApp.addRegions({footerRegion: FooterRegion});
Note that if you define your own Region
object, you must provide an
el
for it. If you don't, you will receive an runtime exception saying that
an el
is required.
There may be times when you want to add a region manager to your
application after your app is up and running. To do this, you'll
need to extend from Region
as shown above and then use
that constructor function on your own:
var SomeRegion = Backbone.Marionette.Region.extend({
el: "#some-div",
initialize: function(options){
// your init code, here
}
});
MyApp.someRegion = new SomeRegion();
MyApp.someRegion.show(someView);
You can optionally add an initialize
function to your Region
definition as shown in this example. It receives the options
that were passed to the constructor of the Region, similar to
a Backbone.View.