< >

Upgrade Guide from v3 to v4

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.

Required changes

These are breaking changes that need to be handled when migrating from Marionette v3 to v4

CompositeView was removed

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 was renamed to CollectionView

childViewEventPrefix flag is set to false by default

Marionette global instance is not attached to Backbone global instance

noConflict was removed

AppRouter was removed

Renderer class was removed

TemplateCache render removed

Behavior Lookup was removed

attachElContent not called unless the View renderer returns a value

Support for vanilla Backbone.View has changed

triggerMethodOn was removed

Function isNodeAttached was removed

View's template: false now no-ops the render

View.showChildView and Application.showView now return the shown view

View data serialization no longer clones the data

View render is no longer bound to the view

Region no longer supports the selector property

Region preventDestroy option was removed from show and empty

Internally _.bind was replaced with Function.prototype.bind

Application, Behavior, and Region no longer extend MnObject

destroy functions only proxy a single argument

defaults was removed from Behavior

View definition options will not be passed to the view initialize.

Error utility was made private

DEV_MODE which shows deprecation warnings was made a feature flag.

Recommended changes (deprecations)

These changes are optional, although recommended to make future upgrades easy

The default export has been deprecated

// 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

   // 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({});
Improve this page