Marionette 3 introduces a number of breaking changes. This upgrade guide will go through the major changes and describe how to change your application to accommodate them.
Where possible, we will document how to make the changes in Marionette 2.4.5 so that your applications can continue to work and to ease the burden of upgrading to Marionette 3.
The most noticeable change to Marionette 3 is the consolidation of ItemView
and LayoutView
into View
. In addition, CompositeView
has been removed and
its functionality merged into CollectionView
and View
.
LayoutView
and ItemView
Using separate View
LayoutView
and ItemView
was complicating the API for
Marionette needlessly. The new View
replaces all of this and sets a clear
recommendation for building layout trees.
For updating in Marionette 2.4.5, it is recommended you change all instances of
ItemView
to LayoutView
.
Change all instances of LayoutView
and ItemView
to View
. Any views that
previously extended View
with a custom render
should work relatively
unchanged.
CompositeView
The CompositeView
was deprecated in favor of using View
and
CollectionView
. The CompositeView
will be completely removed in Marionette
4.
See CollectionView
for detail on upgrading to Marionette 3. This technique works in both Marionette
2.4.5 and Marionette 3.
The childEvents
attribute was renamed to childViewEvents
.
Child event bubbling above one level is now removed in most instances and
deprecated pending removal everywhere else. This can no longer be relied upon.
To pass events further up the chain, you must explicitly using
childViewTriggers
to convert the event from the child into an event on the
parent. These can be chained all the way up to the level you require them to be.
Bubbled child events no longer pass the childView
implicitly and only pass the
arguments passed as part of triggerMethod
. This means that the arguments
passed to onEvent
and onChildviewEvent
are now identical.
In Marionette 2, childEvents
where bound on every event. In Marionette 3,
childViewEvents
are bound once and cached. This means that you cannot add new
events after the view has been created.
triggers
The view triggers
attribute no longer passes an options
attribute to event
handlers, instead passing the view instance that triggered the event.
A number of lifecycle events were changed or removed from Marionette 3. Information on which ones were removed, changed, or added will be found here with recommendations on how to update your code.
show
and before:show
The show
events were removed completely as they were redundant and were being
used incorrectly to show child regions. The show
event was fired after the
view had been attached, meaning the DOM was being constantly updated, leading to
deteriorated performance.
Replace all instances of onShow
, on('show')
, onBeforeShow
and
on('before:show')
to use the render
and before:render
events. This is the
recommendation for Marionette 3 and ensures the DOM tree is built in-memory
before modifying the DOM.
Replace all instances of show
and before:show
with render
and
before:render
. If you want the view to be visible in the DOM, then listen to
the dom:refresh
event.
The biggest change to templates is renaming templateHelpers
to
templateContext
- the aim is to be more in-line with terminology from other
frameworks.
Simply replace all instances of templateHelpers
with templateContext
There are a number of changes to how regions behave - the biggest change being the removal of the ability to access regions as attributes
view.region
The view.<region_name>
syntax has been removed in favor of view.getRegion()
,
view.getChildView()
and view.showChildView()
.
Change all references to view.region
to view.getRegion('region')
. For
example, in Mn 2.4 and below:
var AnotherView = require('./anotherview');
var MyView = Mn.LayoutView.extend({
regions: {
myregion: '.regionname'
},
onRender: function() {
this.myregion.show(new AnotherView());
}
});
This does not work in Mn 3 - instead do:
var AnotherView = require('./anotherview');
/* In Mn 2.4 we can just use LayoutView */
var MyView = Mn.View.extend({
regions: {
myregion: '.regionname'
},
onRender: function() {
this.showChildView('myregion', new AnotherView());
}
});
See the documentation for views to learn more about how to manage regions in Marionette 3.
Marionette Modules have been completely removed in favor of using the more standard JavaScript module loaders e.g. Webpack or Browserify. See the installation documentation for a list of potential options.