Marionette 4 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.
These are breaking changes that need to be handled when migrating from Marionette v3 to v4
CompositeView class was providedCompositeView does not existsCollectionView instead. Most features of CompositeView were added to CollectionView and in common cases a class rename is enough. The old CompositeView was abstracted to a separate library.One of the required changes is to explicitly define the childView when implementing a recursive (tree) view
// with compositeview
const TreeView = CompositeView.extend({
template: 'node-template'
})
// with collectionview
const TreeView = CollectionView.extend({
template: 'node-template',
childView () {
return TreeView
}
})
NextCollectionView and CollectionView were providedCollectionView, based on NextCollectionView is provided. The old CollectionView implementation was removedCollectionView instead. The old CollectionView was abstracted to a separate library.childViewEventPrefix flag is set to false by defaultchildViewEventPrefix flag was set to truechildViewEventPrefix flag was set to falsechildViewEventPrefix per view that needs it. Even better explictly define the proxies via childViewEvents and childViewTriggers.Backbone.Marionette
Backbone global instancenoConflict was removednoConflict allowed for multiple installs of Marionette to be installedRenderer.render
Renderer does not existsMarionette.setRenderer which accepts a function with same signature as expected by Renderer.render
TemplateCache render removedTemplateCache
template(data);
Remedy: Attach behaviors to view definitions. In v3
const MyBehavior = Marionette.Behavior.extend({...});
Marionette.Behaviors.behaviorsLookup = function() {
return {
FooBehavior: MyBehavior
};
};
const V3View = Marionette.View.extend({
behaviors: {
FooBehavior: {}
}
});
In v4
const MyBehavior = Behavior.extend({...});
const V3View = View.extend({
behaviors: {
FooBehavior: MyBehavior
}
});
attachElContent not called unless the View renderer returns a valueattachElContent was always calledattachElContent not called if the render doesn't return a value.attachElContent calledBackbone.View instances were supported as isBackbone.View is necessary to apply Marionette.Events mixinBackbone.View is not used there's no required change, otherwise, apply the Marionette.Events mixinto the
prototype of the view class intended to be used withMarionette`. Example:// once, in the application start
import _ from 'underscore';
import {Events} from 'backbone.marionette';
_.extend(Backbone.View.prototype, Events);
triggerMethodOn was removedtriggerMethod on an object that did not have the methodMarionette.Events
isNodeAttached was providedisNodeAttached does not existsdocument.documentElement.contains(el)
template: false now no-ops the renderrender
template: false was often used to generate render events when no render was performed. Use other hooks or methods when no template will be rendered.getRegion if the region is needed after this methodtemplateContext is defined templates can modify the actual model data if not careful. Clone if necessary.render is no longer bound to the viewcall or apply.selector propertyselector or el property could be used to set the region el.el property can be used to set the el.selector used with Region to el.preventDestroy option was removed from show and empty
detachView first if you need to remove a shown view without destroying._.bind was replaced with Function.prototype.bind
_.bind was usedFunction.prototype.bind is usedApplication, Behavior, and Region no longer extend MnObject
Mn.Object.Object prototype you may need to modify the others too.destroy functions only proxy a single argumentdestroy functions were passed along to events.destroy use an object.defaults was removed from Behavioroptions and defaults defined on Behavior are default options.options define the Behavior's default optionsdefaults to options.initialize.options defined on the view definition were merged into options and passed to the Backbone.View constructoroptions passed in at construction will be passed to the Backbone.View constructor.options on the definition.Error utility was made privateDEV_MODE which shows deprecation warnings was made a feature flag.DEV_MODE was set on the global Marionette object.setEnabled to set the DEV_MODE feature flag.Marionette object.These changes are optional, although recommended to make future upgrades easy
Remedy: Import each Marionette classses / functions separatedly or with * keyword Examples: ```javascript // using ES module syntax // old behavior import Mn from 'backbone.marionette'; const MyView = Mn.View.extend({});
// new behaviors // import only needed class/function import {View} from 'backbone.marionette'; const MyView = View.extend({});
// or import all (kills any chance of tree shaking) import * as Mn from 'backbone.marionette'; const MyView = Mn.View.extend({});
// or create a module that default exports all functions/classes // mymarionette.js -> can be configured as an alias for marionette or any other module name with webpack import * as Mn from 'backbone.marionette'; export default Mn;
// myview.js import Mn from './mymarionette'; const MyView = Mn.View.extend({});
// using CommonJS syntax
// old behavior const Mn = require('backbone.marionette'); const MyView = Mn.View.extend({});
// new behavior const {View} = require('backbone.marionette'); const MyView = View.extend({});
#### `Marionette.Object` was renamed to `Marionette.MnObject`
* **Old behavior:** The Marionette Object class was exported as `Marionette.Object`
* **New behavior:** The Marionette Object class is exported as `MnObject`
* **Reason:** Avoid collision with native `Object` class when using with ES imports
* **Remedy:** Rename `Marionette.Object` to `MnObject`. To easy transition the Object will still be available on default Marionette export
```javascript
// using ES module syntax
// old behavior
import Mn from 'backbone.marionette';
const MyObj = Mn.Object.extend({});
// new behaviors
// import only needed class/function
import {MnObject} from 'backbone.marionette';
const MyView = MnObject.extend({});
© 2017 Muted Solutions, LLC
Licensed under the MIT License.
https://marionettejs.com/docs/v4.0.0/upgrade-v3-v4.html