Manage and create components for your Marionette.js application
Marionette.Component is a library for creating reusable components in Marionette.js. Marionette.Component offers an opinionated, standardized approach to creating components with your Marionette views. The library exposes an API for displaying components in Marionette regions and handles the entire view lifecycle inside the region.
$ npm install marionette.component
$ bower install marionette.component
So why a separate layer? Aren't views good enough? Yes, but typically applications take two approaches to creating reusable components. Either you create a reusable view that may contain extra business logic or you create a parent object/controller that manages the lifecycle of the view. To help enforce separation of concerns, Marionette.Component handles the former by being a wrapper object for business logic. It handles the latter by being a parent object that offers a standardized API and manages the lifecycle of the view automatically, eliminating repeated view management patterns in applications.
Creating components is very simple and at minimum requires only a component definition and view class.
var MyView = Marionette.ItemView.extend({
template: _.template('Hello World')
});
var MyComponent = Marionette.Component.extend({
viewClass: MyView
});
var component = new MyComponent();
To display a component inside a region, call showIn
with the region instance as the argument.
var MyApp = Marionette.Application.extend({
regions: {
mainRegion: '#main'
}
});
var app = new MyApp();
var region = app.getRegion('mainRegion');
var component = new MyComponent();
component.showIn(region);
component.view instanceof MyView; //=> true
component.region === region; //=> true
region.$el.text(); //=> 'Hello World'
Remember that components are reusable, so you can instantiate them multiple times and display them in different regions.
var MyApp = Marionette.Application.extend({
regions: {
sidebarRegion1: '#sidebar-1',
sidebarRegion2: '#sidebar-2',
sidebarRegion3: '#sidebar-3'
}
});
var component1 = new MyComponent();
var component2 = new MyComponent();
var component3 = new MyComponent();
var app = new MyApp();
var regions = app.getRegions();
component1.showIn(regions.sidebarRegion1);
component2.showIn(regions.sidebarRegion2);
component3.showIn(regions.sidebarRegion3);
Components also take a model and/or collection option that will be passed along to the view.
var Foo = Backbone.Model.extend();
var List = Backbone.Collection.extend();
var component = new MyComponent({
model: new Foo(),
collection: new List()
});
component.model instanceof Foo; //=> true
component.collection instanceof List; //=> true
component.model === component.view.model; //=> true
component.collection === component.view.collection; //=> true
Components can capture events triggered on the view and react to them.
var MyComponent = Marionette.Component.extend({
viewClass: MyView,
viewEvents: {
'foo': 'handleFoo',
'select:bar': function(arg) {
console.log('selected bar', arg);
}
},
handleFoo: function() {
console.log('handle foo');
}
});
var component = new Component();
component.showIn(region);
component.view.trigger('foo'); // 'handle foo'
component.view.trigger('select:bar', 42); // 'selected bar 42'
Show the component inside region
. It triggers the following events on the component: before:show
, before:show:view
, show:view
, show
. With each event, it also calls the appropriate on*
method, if available (thanks to triggerMethod
).
Destroy the component and view. It will empty the region, destroy the view, and remove references to any model and collection, as well as references to the view and region. It triggers two events, before:destroy
and destroy
, each with their respective on*
callback from triggerMethod
.
Marionette.Component inherits from Marionette.Object, so all of its methods are available too (of course, destroy
is overriden by Marionette.Component's own implementation).
The view class to be associated with the component. When calling showIn
, the component will create an instance of the view class and attach it as a view
property to the component. The component will also forward along any model
and/or collection
properties to the view.
Optional object literal of view events to method handlers on the component. Please NOTE: this refers to events triggered directly on the view, NOT DOM events that the view itself might handle.
Marionette.Component is a very young project with a lot of potential. If you have any ideas or feature requests, please feel free to open a pull request or issue. For PR's, please branch off dev
.