backbone.marionette/changelog.md

The Backbone Framework

### v4.1.3 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v4.1.2...v4.1.3)

#### Fixes
* unbindRequests now passes context.

### v4.1.2 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v4.1.1...v4.1.2)

#### Fixes
* Error in the build's version number.

### v4.1.1 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v4.1.0...v4.1.1)

#### Fixes
* Error in the build

### v4.1.0 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v4.0.0...v4.1.0)

#### Features
* `CollectionView#addChildView` now accepts a `preventRender` option.
* Marionette now uses `el.ownerDocument.documentElement;` by default instead of `document.documentElement` for querying, customizable via `DomApi.getDocumentEl`.
* The UMD build now reinstates `noConflict` for using multiple versions on the global scope.

#### Fixes
* Fixed a case where a child view could potentially get multiple `destroy` events.
* Pre-rendered views from outside of a region will now correctly empty an current view in a region if shown.
* `CollectionView`'s `emptyView` will now respect the `childViewContainer` for attachment.

#### Misc
* Updated backbone dependency to allow for 1.4 without a warning.
* Tooling and testing was updated and improved removing gulp.
* `Region._setElement` was added for internal use, but may be made public in a future release.

### v4.0.0 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v3.5.1...v4.0.0)

#### Breaking Changes
The breaking changes are documented in the [upgrade guide](https://marionettejs.com/docs/v4.0.0/upgrade-v3-v4.html).

#### Features
* `CollectionView` can now render a template in the same fashion of the removed `CompositeView`.
* `View#triggers` now passes the originating DOM event object as the final argument of the triggered Mn event.
* View classes now have the `bindRequests` and `unbindRequests` API.
* The ES6 package was exposed in `package.json` on `jsnext:main`
* The underscore dependency was updated to include 1.8.3 - 1.9.x.

#### Documentation
The documentation structure was overhauled to provide a flow to reading through the docs.

### v3.5.1 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v3.5.0...v3.5.1)

#### Fixes
* `View` entity events set in `initialize` were being undelegated if `modelEvents` or `collectionEvents` were undefined.

### v3.5.0 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v3.4.4...v3.5.0)

#### Features
* `NextCollectionView`'s `filter` event now returns the attaching and detached views.
* `unbindEvents` and `unbindRequests` can now be called without handlers to remove all handlers from an entity.

#### Fixes
* If an event handler on a behavior was undefined it would remove any prior defined handler.
* When a behavior is destroyed it will now undelegate the behavior events and triggers.
* When a view was added a performance check on `NextCollectionView` would sometimes prevent existing views from sorting correctly.
* `NextCollectionView` `viewFilter` will now be called with the same arguments with underscore or lodash.

#### Deprecations
* Multiple handlers for a single event. If needed, use a single handler to call multiple methods.

### v3.4.4 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v3.4.3...v3.4.4)

#### Fixes
* Prevent exception when a view is instantiated with a non-existing selector `el`.
* When a collection defines the `NextCollectionView` sort order, the add at end performance improvement was removed to prevent edge case errors.
* `NextCollectionView` no longer sorts according to the collection if `sortWithCollection` is set to false.
* When views added to `NextCollectionView` from a collection don't have a matching model, removing the model no longer throws an error.

#### Misc
* `NextCollectionView` now uses backbone update flags instead of calculating changes for sorting

### v3.4.3 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v3.4.2...v3.4.3)

#### Fixes
* `NextCollectionView` collection single model remove no longer incorrectly removes all children
* `EmptyView` will correctly display if a `NextCollectionView` is rendered in `initialize`

### v3.4.2 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v3.4.1...v3.4.2)

#### Fixes
* Regions will now ensure there is only one node in its `$el`
* Regions will not query outside of the parent view if the selector is not found in its context
* The `setDomApi` and `setRenderer` class methods now correctly return the prototype when called

### v3.4.1 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v3.4.0...v3.4.1)

#### Fixes
* Options passed to a behavior are now correctly passed to the behavior
* The ES6 module is no longer exposed in `package.json` as this was breaking for some builds
* The `detachContents` will now correctly detach when using `monitorViewEvents: false` on a `NextCollectionView`

### v3.4.0 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v3.3.1...v3.4.0)

#### Features
* A new build of Marionette supporting ES6 modules was added
* Added DOM API to encapsulate DOM interactions in the views and region
* `monitorViewEvents` was added as an option to all Views to disable DOM lifecycle events
* Added `swapChildViews` to `NextCollectionView`
* Added `viewComparator: false` option to `NextCollectionView` for disabling the default sort

#### Experimental API Breaking Changes
* DOM Mixin was removed (replaced with DOM API)
* `NextCollectionView` `attachHtml` no longer receives the view as the first argument

#### Fixes
* A region's currentView will now be set during that view's initial `dom:refresh` event
* A view will now be considered rendered if its `el` has contents and not only if it has an `el`

#### Misc
* While `Backbone.Radio` is still a dependency, it will no longer cause Marionette to error if nonexistent
* Various performance improvements

### v3.3.1 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v3.3.0...v3.3.1)

#### Fixes
* Behavior `defaults` deprecation notice was always triggering
* Regions threw an error if a childview destroy resulted in a parent view destroy

### v3.3.0 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v3.2.0...v3.3.0)

#### Features
* Added `removeView` and `isSwapping` to `Region` to better support animation
* `NextCollectionView` added as a potential replacement for `CollectionView` in v4
* Added view `initialize` event to behaviors
* `getRegion` will now render the region's view if it is currently not rendered
* If a `behavior` or a `region` is destroyed it will now be removed from the view
* Added `onDomRemove` event for better clean up of things added in `onDomRefresh`
* `childViewEventPrefix` feature flag to allow for `false` by default
* Support custom renderers per view prototype

#### Fixes
* Trigger `detach` events when restoring el

#### Deprecations
* `template: false` deprecated in favor of `template: _.noop`
* Behavior `defaults` deprecated in favor of setting `options` on the Behavior definition
* `Marionette.Renderer` in favor of new custom view renderer.

#### Misc
* Update babel and build tools
* Fix tests runner for IE11

### v3.2.0 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v3.1.0...v3.2.0)

#### Features
* Separate Mn DOM interaction into a mixin for DOM plugin ease
* `View.childViewEvents` should support `trigger`
* Allow showing a template or static string in a region
* Feature/trigger method event args

#### Fixes
* Custom `CollectionView.viewComparator` no longer sorts `collection.models`
* `CollectionView` re-indexes correctly when removing views.
* `CollectionView.filter` can filter by `View` child index
* `Region` will no longer detach pre-existing HTML when `View`'s el is already in the region
* Fix `Region` clean up when `View` is `destroy`ed
* Destroy `CollectionView.children` by `View` and not `Model`

#### Misc
* Remove `MarionetteError` "ViewDestroyError" from `View`'s

### v3.1.0 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v3.0.0...v3.1.0)

#### General
* Performance optimizations for `triggerMethod`, `mergeOptions` and other internal event handlers
* Significant render and removal optimizations for CollectionView utilizing Backbone's `update` event

#### Features
* `Region.detachView` and `View.detachChildView` were added for removing a view from a region without destroying it. This is preferred to the now deprecated `preventDestroy` region show/empty option
* `childViewEventPrefix: false` will disable auto-proxying of child events to the parent view
* `Application` will now accept a region definition object literal as an instantiation option
* Regions are now destroyed when removed from a View

#### Fixes
* Fixed an issue with Lodash 4 compatibility related to behavior events

#### Deprecations
* Region `empty`'s `preventDestroy` option was deprecated in favor of `detachView`
* A region definition object literal's `selector` key was deprecated due to redundacy in favor of the existing key `el`

#### Misc
* Many documentation fixes for v3
* Removed shouldReplace logic from `attachHtml` so overriding no longer breaks `replaceElement` functionality
* Exposed `View.normalizeUIString` for external libraries
* Improvements were made for Views initialized with existing DOM elements

### v3.0.0

Version 3.0.0 of Marionette has arrived and contains many improvements over version
2.x but also some API Changes. Below is a list of the changes made to each component.

To help the community transition over we have released a v2 patch tool to assist
the upgrade. [Marionette Patch Tool] (https://github.com/marionettejs/marionette-v3-compat)

#### View
* `LayoutView` + `ItemView` merge and rename to `View`.
* `Marionette.View` -> `ViewMixin`
* Added `LayoutView` shortcut methods such as `showChildView`.
* `isDestroyed` and `isRendered` made private with a public accessor method.
* Now set `_isDestroyed` to false by default
* Call `Backbone.View` with result of options (163188eeb8)
* `CompositeView`'s `renderChildren` is now public.
* Renamed `childEvents` to `childViewEvents`.
* Removed passing view options as a function
* Renamed `templateHelpers` to `templateContext`
* Made sure `before:render` is triggered before emptying regions.
* Regions are not attached directly to the layout. Use `getRegion` to access the region or `showChildView` to show a `View` within it.
* Allowed `CompositeView` to attach to existing HTML with `template:false`
* Added `hasRegion` for layouts
* Enabled passing `preventDestroy` to `region.empty`.
* `View` now removes its element before destroying child regions. There was an option to turn it on, but now it’s available by default. This helps remove all of the synchronous paints going up the tree.

#### CollectionView
* The `childView` attribute now accepts a function
* `getChildView` was removed
* `emptyView` now accepts a function as an arg.
* Proxied events do not append “this” as an argument
* Removed the `apply:filter` event from `CollectionView`.
* `removeChildView` now returns the removed view.

#### Regions
* Fixed inconsistency in `addRegion`, it now behaves like `addRegions` and adds the region to internal this.regions.
* `View` can replace regions's el.
* Replaced region manager with `region-mixin`.
* Removed static `buildRegion`
* Removed `swap` events.

#### Application
* Introduced region to `Application` (`rootRegion`)
* Removed regions
* Removed Initializers and Finalizers Callbacks
* Removed Application `vent`, `commands`, `requests`

#### Object
* Added support for `Object.isDestroyed`

#### ES6
* Added Rest & Spread ES6 syntax
* using ES6 Modules
* Replaced `var` and `let` with `const`.

#### General Enhancements
* Added `DEV_MODE`
* Changed `_.rest` multiple arg usage to drop for lodash 3 support.
* Behavior, View Mixins.
* Added `cid` field to object, application, behavior, and region
* Added `TemplateCache` options.
* Allow a user to define trigger handlers in options.
* Increased Lodash compatibility, (now supports upto lodash 4)
* Added first class support for Backbone.Radio in Mn.Object
* Updated BB and _ deps to modern versions
* Updated Radio from 0.9 to 2.0
* `delegateEntityEvents`. Delegate Events used to set delegate entity events, it was extracted because now backbone calls delegateEvent everytime the element is set.
* Added `Backbone.Babysitter` to `Mn` and removed the Babysitter dependency.

#### Deprecations
* Deprecated `CompositeView`
* Deprecated `Behavior` Lookups.

#### Removed
* Removed `Marionette.Module` - there’s a shim that you can pull in to get Module and Deferred
* Removed `Marionette.Deferred`
* Removed `component.json`
* Removed `Controller`
* Removed `Callbacks`
* Removed `Wreqr` (replaced with `Radio`)
* Removed `actAsCollection`
* Removed `_getValue`.

#### API Renames
* Renamed `render:collection` => `render:children`
* Renamed `bindEntityEvents` => `bindEvents`.

### v3.0.0-pre5

#### Documentation

* Improved installation docs.
* Updated `CollectionView` docs to reflect API changes.
* Improved `Behavior` docs.
* Improved functions docs.
* Improved update guide.
* Added "basics" docs.

#### API Changes

* `emptyView` now accepts a function as an arg.
* Removed the `apply:filter` event from `CollectionView`.
* `removeChildView` now returns the removed view.
* `bindEntityEvents` renamed `bindEvents`.
* Deprecated Behavior Lookups.
* Added Backbone.Babysitter to Mn and removed the Babysitter dependency.

#### Bug fixes

* `CollectionView` now only triggers `destroy:children` if it has been rendered.
* Parent views will now successfully listen for `destroy` in `childViewEvents`.

#### Misc

* Replaced `var` and `let` with `const`.
* Added consistent function declarations and added rules to eslint.
* Tweaked peerDependencies to only allow patch versions.
* Directory structure changes and file naming consistency.
* Improved test coverage.
* Removed bundled build.

### v3.0.0-pre4

#### Documentation

* Improved `View` documentation.
* Added `Backbone.Radio` integration documentation.
* Fixed broken links in `CollectionView` documentation.
* Removed `Marionette.Module` documentation.
* Add installation documentation.
* Removed outdated API documentation.
* Added Upgrade Guide.

#### API Changes

* return `this` from all functions that do not return anything, useful for chaining.
* Removed `getValue` and internal `getOption`.

#### Bug fixes

* CollectionView#reorder will no longer remove an already displayed emptyView.
* Calling `Backbone.View` constructor with arguments consistently across all views.
* Monitor for child already attached.
* When a view is attached to an existing element, `isRendered()` should reflect `true`.
* Region empty edge-case fix that prevents view destroy handlers calling `empty`.
* Region now detaches previous html if there is no view.

#### Misc

* Build browser tests with rollup.
* Fix bundled build.
* Linter fixes.

Also, [please help us finish v3](https://github.com/marionettejs/backbone.marionette/milestones/v3.0.0)!

### v3.0.0-pre3

#### Dependency Updates

* Backbone and Underscore moved to peerDependencies to solve dependency conflicts for browserify and webpack users.
* Added support for Lodash 4.

#### Documentation

* Application documentation updates.

#### API Changes

* Removed unused `collection` parameter from `CollectionView.isEmpty`.

#### Bug fixes

* `replaceElement` and `allowMissingEl` are now able to be overridden in `Region.show`.

#### Misc

* Gulp test-browser task fixed.
* es-lint fixes.
* Added more es6 syntax.
* Fixed the UMD exported build.

Also, [please help us finish v3](https://github.com/marionettejs/backbone.marionette/milestones/v3.0.0)!

### v3.0.0-pre2

Extra release to remove public release of v3.0.0-pre.1, this release is available via the `prerelease` tag on npm.

### v3.0.0-pre.1

This is a "family and friends" release. The documentation is still mostly for 2.4.4.
Please let us know if you run into any issues. Also, [please help us finish v3](https://github.com/marionettejs/backbone.marionette/milestones/v3.0.0)!

### v2.4.7 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v2.4.6...v2.4.7)

#### Fixes

* CollectionView#reorder will no longer remove an already displayed emptyView.
* Fixed build of sourcemap files.

### v2.4.6 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v2.4.5...v2.4.6)

#### Misc

* Updated Backbone dependency to 1.3.x.

### v2.4.5 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v2.4.4...v2.4.5)

#### Fixes

* `Marionette.View#ui` will now bind events when names are hyphenated.
* Nonexistent event handlers now fail silently.

#### Misc

* Updated Backbone dependency to 1.3.3.
* devDependencies updated.
* Updated uglify to fix deprecated sourcemap pragma //@ replaced with //#.

### v2.4.4 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v2.4.3...v2.4.4)

#### Fixes

* `Region#empty` will return the region instance whether or not it has a current view.
* `CollectionView#reorder` will now correctly respect any set filter.
* Fixed `childEvents` failing to trigger during showing a view in a region.
* Stop deleting the `currentView._parent` if showing the same view in a region.

#### Misc

* `LayoutView#showChildView` new `options` argument passed to underlying `Region#show` to enable full `show` functionality.
* Added support for passing down arguments to `Object#destroy`.

### v2.4.3 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v2.4.2...v2.4.3)

#### Fixes

* `TemplateCache#loadTemplate` accepts empty script-tag templates.
* Parent LayoutView's `childEvents` continue working with views attached manually using `Region#attachView`.
* When an array of items (length > 1) are added to a collection backing a CollectionView using the `at` option, the child views are appended to the DOM in the proper order.
* When models are added to a collection backing a CollectionView with the `at` option, the child views are rendered in the proper order even when the CollectionView has a filter.
* `CollectionView#isEmpty` respects a `false` return value even when there are no child views.
* `Region#empty` reliably destroys views when called with options.
* CollectionView child views can, in turn, render children within `onBeforeShow` as documented.
* CollectionView `childView` and `emptyView` can be pure `Backbone.View` classes.

#### Docs

* Better documentation around view `childEvents` that reinforces the distinction between child view `triggers` and `events`.
* Guidance on achieving full event lifecycle while using `Backbone.View` as the child view within CollectionViews or LayoutViews/Regions.

#### Misc

* Allow `Application` to be initialized with multiple arguments for consistency with earlier releases.
* More comprehensive support for Backbone child views, including a more rigorous test suite and support for `render`, `destroy`, and `dom:refresh` lifecycle events when shown by CollectionViews or LayoutViews/Regions.
* Bumped Backbone dependency to 1.2.3

### v2.4.2 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v2.4.1...v2.4.2)

#### Fixes

* Fixed a bug where `reorderOnSort` would not reorder back to the original order.
* Stop deleting `$childViewContainer` so that it can be accessed in behaviors.
* Ensure `before:show` and `show` events are triggered on `CollectionView` children.
* Ensure `onBeforeAttach` and `onAttach` are called for `CollectionView` children.
* Allow for disabling of `triggerBeforeAttach` and `triggerAttach` via `show()` options.
* Added the documented `buffer` argument to `attachBuffer` and changed implementation so this was used rather than `_createBuffer`.
* Fixed potential memory leak when destroying children on `CollectionView` by making the `checkEmpty` call optional.

#### Docs

* Improve documentation around the requirement for an initial render to bind events in `CollectionView`.
* Add documentation around UI interpolation usage.
* Add documentation to warn about the full re-render of a `CollectionView` or `CompositeView` if `reorderOnSort` is not set.

#### Misc

* Bumped Underscore and Backbone dependencies to 1.8.3 and 1.2.1 respectively.

### v2.4.1 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v2.4.0...v2.4.1)

#### Fixes

* Fixed a nasty bug where `reorderOnSort` when used on a `CompositeView` would not respect the `childViewContainer`.

#### General

* Add JSCS for style linting and consistency.

#### Docs

* Improve internal linking across docs, to make it easier for people to understand how pieces relate to each other.

### v2.4.0 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v2.3.2...v2.4.0)

#### 2.4 In Overview

The Marionette 2.4 release is primarily focused around adding power and performance to `Marionette.CollectionView’s` and `CompositeViews`. It is now possible for users to declaratively sort, filter, and reorder in a performant and clear way on the view layer. Prior to this work it was difficult and required significant workarounds.

As well as working on the `CollectionView` layer we have added full support for lodash and multiple builds of backbone, underscore and lodash. Allowing the user to pick whatever tools they wish.

The other powerful feature that we introduced in this release is the concept of `childEvents` for `LayoutView` and their subviews. Prior to this release there was never a great way to listen or react to events that were triggered on subviews, like when something was rendered or destroyed. Now we have brought over the declarative `childEvents` hash from `CollectionView` into the `LayoutView`.

As always come and join us in [chat](https://gitter.im/marionettejs/backbone.marionette/)

#### Features

* CollectionView
  * You can now set a filter method on a `CollectionView` or `CompositeView` to filter what views are show. This is useful for when you are displaying a list that a user can filter.
  * Add the `reorderOnSort` option to `CollectionView` and `CompositeView` to use jQuery to move child nodes around without having to re-render the entire tree. This is a massive perf boost and is an easy win if you are sorting your collections.
  * The `CollectionView` now has a `viewComparator`, to enable custom sorting on a per view basis regardless of what how your backing collection is sorted.
  * Refactor sort param lookup to use `Marionette.getOption`.
  * **Fix** childViews now fire a `before:show` event even if the childView is inserted after the parent `CollectionView` or `CompositeView` has been shown.

* Regions
  * The `empty` method now takes an optional `preventDestroy` flag to prevent the destruction of the view shown within.
  * `this.myRegion.empty({preventDestroy: true})`

* TemplateCache
  * The templateCache `get` method now takes a second param of options to enable passing options to the loading of templates.

* LayoutView
  * Add a new helper method for easier showing of child nodes `showChildView`
  *  `this.showChildView('sidebar', new SidebarView());`
  *  Add a new helper method of easier retrieving of child nodes `getChildView`
  *  `this.getChildView(‘sidebar’)`
  *  Add a `destroyImmediate` option to the `LayoutView`, to destroy the layout view element and then remove the child nodes. This is a perf optimization that you can now opt into.
  *  `@ui` interpolation is now supported within region definitions on a `LayoutView`
  *  `regionEvent` support was added
  *  you can access this functionality via `onChildViewX` or via the declarative `childEvents` hash

* ItemViews
  * the `isRendered` property is now set to `true` after render, even if no template is set.
  * Views
  * The `destroy` method now returns this instance that was destroyed to enable easier chaining of view actions.
  * If you define the options hash on your `Marionette.View` or if you pass options as a function to your `Marionette.View`, pass the result of options down to the backbone view constructor.
  * All views now have a `isRendered` property, that is updated after `render` and `destroy`.

* Object
  * The `destroy` method now returns this instance that was destroyed to enable easier chaining of object actions.

* Behavior
  * The `destroy` method now returns this instance that was destroyed to enable easier chaining of behavior actions.
  * Expose the `UI` hash to a behavior instance. The behavior `UI` hash is a composite of the view hash and the behavior hash merged with the behavior hash tasking precedence.

#### Util

* `Marionette._getValue` will now use `call` under the hood if no arguments are passed (micro optimization).
* Add `Marionette.mergeOptions` to `Marionette.View*` classes, `Marionette.Object`. `Marionette.AppRouter`, `Marionette.Controller`
* `mergeOptions` is a handy function to pluck certain `options` and attach them directly to an instance.

#### Docs

* Minor documentation cleanups and fixes

#### Deprecation Notices

* Deprecate `Marionette.Controller`, Use `Marionette.Object` instead.

#### Misc

* YAML api documentation is now linted on each PR.
* Add `Marionette.FEATURES` flag.
* Refactor several methods to enable 100% compatibility with lodash.

### v2.3.2 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v2.3.1...v2.3.2)

#### 2.3.2 in overview:

##### Bug Fixes

* Fix IE8 regression in `Marionette._getValue` to always call `apply` with either an array of params or an empty array.

### v2.3.1 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v2.3.0...v2.3.1)

#### 2.3.1 in overview:

##### Features

* Regions can set a `parentEl` as a way of specifying the DOM tree (default `body`) that they are scoped with. (useful for instance in `LayoutView`).

```js
  var region = new Region({parentEl: $(“#sub-tree”)})
```

##### Bug Fixes

* Layout region lookups are now scoped to the layout and not to the entire DOM.

* Calling `delegateEvents` after the `ui` hash has been modified now works.

* Prevent unsetting event listeners on region swap when a view is swapped out from a region, but not destroyed, its DOM events will not be removed.

* A view's `isDestroyed` state is now explicitly set to `false` when the view is created.

##### Refactors

* Added `Marionette._getValue`. This method is similar to `_.result`. If a function is provided we call it with context otherwise just return the value. If the value is undefined return a default value. This method is private and should not be used directly in your code.

* Various other code refactors.

### v2.3.0 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v2.2.2...v2.3.0)

#### 2.3.0 in overview:

This release of Marionette contains a significant amount of code optimizations and refactors. These changes will not be visible to you as end user however as they improve the underlying base of Marionette and speed up your app to improve consistency across the base classes. Such speed ups are most visible in the great work @megawac has been doing in both [serializeData](https://github.com/marionettejs/backbone.marionette/commit/62f15dc7ec880631a0bb79b18470c94b0a0ad086) and [triggerMethod](https://github.com/marionettejs/backbone.marionette/commit/e5957dde9a9a48eeb8097a0ce2f628d795668e64)

As always you can come chat with us in the main chatroom at https://gitter.im/marionettejs/backbone.marionette/

Work has been continuing on improving the documentation of Marionette, via an external custom JSDOC tool that @ChetHarrison has been spear heading via https://github.com/ChetHarrison/jsdoccer

If you have not already checked out Marionette Inspector, it is a great tool that Jason Laster has been working on to make debugging and working with marionette much easier. https://github.com/MarionetteLabs/marionette.inspector

##### Features

* Marionette.isNodeAttached
  * Determines whether the passed-in node is a child of the `document` or not.
* View "attach" / onAttach event
  * Triggered anytime that showing the view in a Region causes it to be attached to the `document`. Like other Marionette events, it also executes a callback method, `onAttach`, if you've specified one.
* View "before:attach" / onBeforeAttach
  * This is just like the "attach" event described above, but it's triggered right before the view is attached to the `document`.
* AppRouter Enhancements
  * `triggerMethod`, `bindEntityEvents`, and `unbindEntityEvents` are now available on AppRouter
* Marionette.Application is now a subclass of Marionette.Object
* Marionette.Behavior is now a subclass of Marionette.Object
* Marionette.Region is now a subclass of Marionette.Object
* CompositeView’s `getChildViewContainer` now receives `childView` as a second argument.
* Region Triggers now pass the view, region instance, and trigger options to all handler methods
* CollectionView `emptyViewOption` method now receives the model and index as options.
* Allow non-DOM-backed regions with `allowMissingEl`
  * `allowMissingEl` option is respected by `_ensureElement`
  * `_ensureElement` returns a boolean, indicating whether or not element is available
  * Region#show early-terminates on missing element
* Regions now ensure the view being shown is valid
  * Allowing you to handle the error of a region.show without the region killing the currentView and breaking without recourse.
  * Appending isDestroyed to a Backbone.View on region empty now adds the same safety for not re-showing a removed Backbone view.
* Marionette is now aliased as Mn on the `window`.
* Collection/Composite Views now support passing in 'sort' as both a class property and as an option.
* RegionManager will now auto instantiate regions that are attached to the regionManager instance.

```js
new Marionette.RegionManager({
  regions: {
    "aRegion": "#bar"
  }
});
```

##### Fixes

* Region now uses `$.el.html(‘’)` instead of `.innerHTML` to clear contents.
  * We can not use `.innerHTML` due to the fact that IE will not let us clear the html of tables and selects. We also do not want to use the more declarative `empty` method that jquery exposes since `.empty` loops over all of the children DOM nodes and unsets the listeners on each node. While this seems like a desirable thing, it comes at quite a high performance cost. For that reason we are simply clearing the html contents of the node.
* Destroying an old view kept alive by `{preventDestroy: true}` no longer empties its former region.
  * Now the destroy listener from previous view is removed on region show
* AppRouter `this.options` now assigned prior to `initialize` being called.


##### Deprecation Warnings

* Marionette.Application.addInitializer
* Marionette.Application Channel
* Marionette.Application Regions
* Marionette.Callbacks
* Marionette.Deferred
* Marionette.Module.addInitializer
* Marionette.Module.addFinalizer


### v2.2.2 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v2.2.1...v2.2.2)

* Fixes

  * Remove duplicate call to region.empty on view destroy.
  * Fix call time of `swapOut`.
  * Fix broken link in Marionette Error messages

### v2.2.1 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v2.2.0...v2.2.1)

* Fixes

  * Revert collection type checking for `collectionView`.

### v2.2.0 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v2.1.0...v2.2.0)

* Features

  * Normalize region selectors hash to allow a user to use the `@ui.` syntax
  * `Marionette.triggerMethodOn`
    * `triggerMethodOn` invokes `triggerMethod` on a specific context
  * Marionette.Error
    * `captureStackTrace` cleans up stack traces
  * add view _behaviors reference to associated behaviors
    * enabling you to easily test and spy on your behaviors
  * CollectionViews now receive events from emptyViews in the childEvents hash
  * Regions now receive `swapOut` and `beforeSwapOut` events.
  * Application has `this.options`
  * Application has `initialize` method
  * Behaviors no longer wrap view methods

* Bug Fixes

  * LayoutView’s regions are scoped inside its `el`
  * Fix inconsistent Marionette.Object constructor implementation.
  * emptyView instances now proxy their events up to the collection / compositeView
  * collection / compositeView does not listen to collection add/remove/reset events until after render.
  * Marionette.normalizeUIKeys no longer mutates UI hash

* Better Errors

  * View destroyed error now includes the view cid in the error message.
  * Throw an error when Marionette.bindEntityEvents is not an object or function
  * Throw a descriptive error for `collectionViews`
    * If you do not pass a valid `collectionView` instance you are now given a logical error.

* Documentation Improvements

  * New API docs are in progress
  * Examples have been cleaned up

### v2.2.0-pre.2 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v2.1.0...v2.2.0-pre.2)

### v2.2.0-pre [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v2.1.0...v2.2.0-pre)

### v2.1.0 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v2.0.3...v2.1.0)

* Features

  * Marionette.Object
    * A base class which other classes can extend from. Marionette.Object incorporates many Backbone conventions and utilities like `initialize` and `Backbone.Events`. It is a user friendly class to base your classes on to get Backbone conventions on any generic class.

  * Add a `el` reference to the views `el` from within a `behavior` instance.

  * `ItemView`s can now have no template by setting `template: false`

  * Application objects can now configure their default message channel.
    * This will allow you to configure multiple applications to exist at the same time within an app without their event bus colliding.

  * Application objects now have the `getOption` method.

  * Regions now have a `hasView` method to determine if there is a view within a given region.

  * Views no longer use toJSON directly on models. Instead they call into the new overridable methods `serializeModel` and `serializeCollection` via `serializeData`

  * Return chainable objects from more methods to be consistent

    * Application: emptyRegions
    * Application: removeRegion
    * CollectionView renderChildView

    * Controller new
    * LayoutView destroy

    * Region reset
    * Region attachView
    * Region empty

    * RegionManager destroy
    * RegionManager emptyRegions (now returns regions)
    * RegionManager removeRegions (now returns regions)
    * RegionManager removeRegion (now returns region)
    * View destroy
    * View undelegateEvents
    * View delegateEvents

  * RegionManager `addRegions` now accepts a function that returns a region definition in addition to a region definition object
    * This extends to Marionette.Application’s and CompositeView’s `regions` properties

  * Added CollectionView `resortView`
    * Override this method on a subclass of CollectionView to provide custom logic for rendering after sorting the collection.

  * View instance is now passed as a third argument to `Marionette.Renderer.render`

  * Add `getRegionManager` to Application

* Fixes

  * CollectionView now maintains proper order when adding a mode
  * Fix component.js path
  * Prevent AppRouter from erroring when appRoutes are passed into the router constructor as an option.
  * UI hash keys now only allow documented syntax, enforcing `@ui.stuff` instead of `@ui<ANY_CHAR>stuff`

### v2.1.0-pre [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v2.0.3...v2.1.0-pre)

### v2.0.3 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v2.0.2...v2.0.3)

  * Bug Fixes

    * Fixed an issue where `before:show` was not triggered on a view's behavior when shown within a region.

    * Destroying a view outside of its region will now cause the region to remove its reference to that view.

### v2.0.2 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v2.0.1...v2.0.2)

  * Bug Fixes
    * Fixed issue where `render:collection` called before the entire collection and children had been rendered.

  * General
    * Remove bundled main entry point for bower.

### v2.0.1 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v2.0.0...v2.0.1)
  * Fix missing Wreqr and Babysitter in Core AMD definition.

### v2.0.0 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v1.8.8...v2.0.0)
  * This is a breaking release and contains many API updates and changes, thus changelog is quite large for this release, please refer to the [google doc](https://docs.google.com/document/d/1fuXb9N5LwmdPn-teMwAo3c8JTx6ifUowbqFY1NNSdp8/edit#) for the full details of what is new and what has changed.

### v2.0.0-pre.2 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v2.0.0-pre.1...v2.0.0-pre.2)
  * The changelog is quite large for this release, please refer to the [google doc](https://docs.google.com/document/d/1fuXb9N5LwmdPn-teMwAo3c8JTx6ifUowbqFY1NNSdp8/edit#)

### v2.0.0-pre.1 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v1.8.5...v2.0.0-pre.1)
  * The changelog is quite large for this release, please refer to the [google doc](https://docs.google.com/document/d/1fuXb9N5LwmdPn-teMwAo3c8JTx6ifUowbqFY1NNSdp8/edit#)

### v1.8.8 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v1.8.7...v1.8.8)

  * Fixes
    * Fixed the case where `onShow` was not called on child view behaviors when inside a `Collection` or `Composite` view.

### v1.8.7 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v1.8.6...v1.8.7)

  * Fixes
    * Fixed nasty ui interpolation bug with behaviors.

  * General
    * Minor Doc cleanup

### v1.8.6 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v1.8.5...v1.8.6)

  * Regions
    * `Region.show` now returns the region instance to allow for region operation chaining.
    * `Region.show` triggers the view's native `triggerMethod` if it exists. This is to handle the case that triggerMethod is wrapped by a `Marionette.Behavior`.

  * General
    * Update jquery 2.x upper bound dependency restrictions.
    * The grunt test command will now complain if you do not have bower components installed.
    * Readme cleanups.

### v1.8.5 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v1.8.4...v1.8.5)

  * Fixes
    * Update the UMD build to be inline with the 2.x branch UMD implementation.

### v1.8.4 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v1.8.3...v1.8.4)

  * General
    * Update bundled build to use the latest version of babysitter and wreqr.

### v1.8.3 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v1.8.2...v1.8.3)

  * Fixes
    * Behaviors now have access to the views options and events during their initialize.

### v1.8.2 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v1.8.0...v1.8.2)

  * Fixes
    * Behaviors now calls `stopListening` on close.
    * Behaviors now undelegate `modelEvents` and `collectionEvents` when the parent view calls `undelegateEvents`.

### v1.8.0 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v1.7.4...v1.8.0)

  * General
    * Update Gruntfile.
    * The default task (`grunt`) now runs tests.
    * `$ grunt dev` watch for watching.
    * `$ grunt build` runs the tests and compiles.
    * Add better inline documentation for module implementation.
    * Add better inline behavior documentation.

  * Fixes
    * Behaviors now correctly lookup methods for `modelEvents` and `collectionEvents`.
    * The `CollectionView` now triggers close on its children in the correct order.

  * Features
    * Add `onRoute` to the `appRouter`.
    ```js
      Marionette.AppRouter.extend({
        onRoute: function(route, params) {
        }
      })
    ```
    * `Region.show` now takes an option to prevent closing the previous view in the region. By default a region will automatically close the previous view, however you can prevent this behavior by passing `{preventDestroy: true}` in the options parameter.
    ```js
    myRegion.show(view2, { preventDestroy: true })
    ```
    * Add a `getRegion` method to `Layout`. This is in line with the eventual goal of not attaching regions to the root layout object.
    * Behavior instances now extend from Backbone.Events, allowing you to use `.listenTo` and `.on`.

    * Allow Behaviors to have a functional hash lookup.
    ```js
      Marionette.ItemView.extend({
        behaviors: function() {
          // “this” will refer to the view instance
          return : {
            BehaviorA: {}
          }
        }
      })
    ```
    * RegionManagers now calls `stopListening` on a regions on removal.

  * Refactors
    * Abstract underscore collection method mixin into a generic helper.
    * Use built in marionette extend for behaviors.

  * Tests
    * Add a whitespace linter to the text coverage. Trailing whitespace now causes travis.ci to fail.
    * Add test coverage for `bindEntitiyEvents` and `unbindEntityEvents`.
    * Test public API for the `regionManager`.
    * Improve view trigger tests for better control when testing.

### v1.7.4 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v1.7.3...v1.7.4)

* General
  * Update bower dependencies to take advantage of the fact that marionette repos follow semver.

* Fixes
  * Behaviors events no longer collide with each other.
  * Revert `stopListening` call on `stop` for modules. While this was a "fix", the docs were quite vague leading to breaking changes for many people.
  * `startWithParent` is now respected when using a `moduleClass` property.

### v1.7.3 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v1.7.2...v1.7.3)

* Behaviors
  * Adds the ability to use `@ui` interpolation within the events hash on a behavior.

* Fixes
  * Corrects broken view $el proxy in behaviors.

### v1.7.2 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v1.7.1...v1.7.2)

* Fixes
  * Binds behavior events to the behavior instance, as compared to the view.

### v1.7.1 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v1.7...v1.7.1)

* Fixes
  * Enables the use of string based behavior event methods.

### v1.7.0 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v1.6.4...v1.7)

Version 1.7 represents a significant step in formalizing the ways to improve your `view` code though reusable `behaviors`. Say goodbye to custom mixin strategies and welcome `behaviors` into town.

* Behaviors

    A `Behavior` is an isolated set of DOM / user interactions that can be mixed into any `View`. `Behaviors` allow you to blackbox `View` specific interactions into portable logical chunks, keeping your `views` simple and your code DRY. **[Read the docs here.](https://github.com/marionettejs/backbone.marionette/blob/master/docs/marionette.behavior.md)**

* Modules
    * Call stop listening on module stop.

* Events
    * add a before:show event for views and regions

* Docs
    * Entire refactor of application docs.

* Tests
    * Rework the module tests to improve readability and consistency.

* General
    * switch from `~` to `^` for *trusted* dependencies.

### v1.6.4 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v1.6.3...v1.6.4)
  * Fixes
    * Patches a bug that would cause modules to be initialized twice when a custom module class is passed

### v1.6.3 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v1.6.2...v1.6.3)
  * Improvements
    * Enable more direct module instantiation on `Marionette.App`.
      ```js
        var ItemModule = Marionette.Module.extend({
          startWithParent: false,
          initialize: function(options) {},
          onStart: function() {}
        });

        // ...

        this.app.module('Items', ItemModule);
      ```
    * `ui` hash interpolation now supports a functional `ui` hash.

      ```js
        ui: function() {
          return {
            "foo": ".foo"
          }
        }
      ```
  * Fixes
    * Fix `@ui` interpolation for handling complex selectors.

      ```js
        {
          "click div:not(@ui.bar)": "tapper"
        }
      ```
    * Bump `backbone.babysitter` and `backbone.wreqr` versions.
  * General
    * Improve readme docs for `CollectionView`, `AppRouter` and `ItemView`.
    * Handle THE [npm self sign cert problem](http://blog.npmjs.org/post/78085451721/npms-self-signed-certificate-is-no-more)
    * Replace unneeded argument slicing.
    * Normalize error throwing to use internal `throwError` helper method.
    * Use `_` type checks for non performant code to improve readability and consistency.

### v1.6.2 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v1.6.1...v1.6.2)
  * CollectionView/CompositeView
    * allow `itemEvents` to use string based method names [PR 875](https://github.com/marionettejs/backbone.marionette/pull/875)
  * Modules
	* update module initialize to include moduleName and app [PR 898](https://github.com/marionettejs/backbone.marionette/pull/898)
  * General
  	* significantly improve module documentation [PR 897](https://github.com/marionettejs/backbone.marionette/pull/897)

### v1.6.1 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v1.6.0...v1.6.1)
  * Modules
    * Fix a bug where a module would not start by default when defined as an object literal

### v1.6.0 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v1.5.1...v1.6.0)
  * CompositeView
    * add a `composite:collection:before:render` event

  * CollectionView
    * `checkEmpty` can now be overridden

  * Modules
    * `Modules` can now be created using the extend method, and then attached to an [Application](https://github.com/marionettejs/backbone.marionette/blob/master/docs/marionette.application.module.md#extending-modules).

  * General
    * add a component.json file
    * update bower.json
    * add AMD build in bower.json

  * Tests
    * general clean up
    * add sinon.js for test spys

### v1.5.1 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v1.5.0...v1.5.1)
  * CollectionView/CompositeView
    * Fix bug where `show` and `onDomRefresh` was not called on `itemViews` in certain [conditions](https://github.com/marionettejs/backbone.marionette/pull/866)

### v1.5.0 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v1.4.1...v1.5.0)
  * Views
    * View `options` can now be a [function](https://github.com/marionettejs/backbone.marionette/pull/819)
    * `onDomRefresh` is now only called when said `view` is in the [DOM](https://github.com/marionettejs/backbone.marionette/pull/855)

  * CollectionView/CompositeView
    * `itemViewContainer` is now called with the correct [context](https://github.com/marionettejs/backbone.marionette/pull/841)
    * Fix bug where reseting a `collection` within a `collectionView` would cause `onShow` and `onDomRefresh` to be called [incorrectly](https://github.com/marionettejs/backbone.marionette/pull/849) on the itemViews.
    * `addItemView` now returns the `view` that was [added](https://github.com/marionettejs/backbone.marionette/pull/851)
    * You can now specify an `itemEvents` hash or method which allows you to capture all bubbling itemEvents without having to [manually set bindings](https://github.com/marionettejs/backbone.marionette/pull/861).

    ```js
    itemEvents: {
      "render": function() {
        console.log("an itemView has been rendered");
      }
    }
    ```

  * Regions
    * Region `close` event now passes the `view` being closed with the [event](https://github.com/marionettejs/backbone.marionette/pull/834).

  * General
    * Updated bower ignore folder
    * Added an editor config file

### v1.4.1 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v1.4.0...v1.4.1)
* Views
  * fix for inital view class options. Now retains set options at class instantiation

### v1.4.0 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v1.3.0...v1.4.0)
* Views
  * adds the ability to use the new ```@ui.``` syntax within the events and triggers hash to prevent selector duplication

### v1.3.0 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v1.2.3...v1.3.0)
* CompositeView / CollectionView
  * Massive perf boost in rendering collection and composite views by using document fragments [jsPerf](http://jsperf.com/marionette-documentfragment-collectionview/5)

### v1.2.3 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v1.2.2...v1.2.3)
* CompositeView
  * Fixed bug where ```child views``` were being added before the initial render, thus raising errors.

### v1.2.2 [view commit logs](https://github.com/marionettejs/backbone.marionette/compare/v1.2.1...v1.2.2)
* Views
	* Move the instantiation of ```view``` options above the ```constructor``` This allows for view options to be accessed from within the ```initialize``` method for a given ```view```
This is