Merge pull request #2532 from ahumphreys87/2.4.2

2.4.2

.travis.yml

@@ -1,6 +1,8 @@
 sudo: false
 language: node_js
 node_js:
+  - "0.12"
+  - "0.11"
   - "0.10"
 env:
   global: MAINRUN=true
@@ -12,6 +14,8 @@ env:
     - UNDERSCORE=1.6 BACKBONE=1.0
     - UNDERSCORE=1.4.4 BACKBONE=1.1.0
     - UNDERSCORE=1.5 BACKBONE=1.1
+    - UNDERSCORE=1.7 BACKBONE=1.2
+    - UNDERSCORE=1.8 BACKBONE=1.2
     - LODASH=2.4 BACKBONE=1.1
     - LODASH=3.0 BACKBONE=1.1
     - LODASH=3.1 BACKBONE=1.0

SpecRunner.html

@@ -119,6 +119,7 @@
     <script src="test/unit/item-view.spec.js"></script>
     <script src="test/unit/layout-view.dynamic-regions.spec.js"></script>
     <script src="test/unit/layout-view.spec.js"></script>
+    <script src="test/unit/merge-options.spec.js"></script>
     <script src="test/unit/mixin-underscore-collection.spec.js"></script>
     <script src="test/unit/module.spec.js"></script>
     <script src="test/unit/module.stop.spec.js"></script>

api/collection-view.yaml

@@ -324,6 +324,7 @@ functions:
       ...
       
       @api public
+      @param {Object} options
     
     examples:
 

bower.json

@@ -3,7 +3,7 @@
   "description": "Make your Backbone.js apps dance with a composite application architecture!",
   "homepage": "http://marionettejs.org",
   "main": "./lib/core/backbone.marionette.js",
-  "version": "2.4.1",
+  "version": "2.4.2",
   "keywords": [
     "backbone",
     "framework",
@@ -35,8 +35,8 @@
     "upgradeGuide.md"
   ],
   "dependencies": {
-    "backbone": "1.0.0 - 1.1.2",
-    "underscore": "1.4.4 - 1.6.0",
+    "backbone": "1.0.0 - 1.2.1",
+    "underscore": "1.4.4 - 1.8.3",
     "backbone.babysitter": "^0.1.0",
     "backbone.wreqr": "^1.0.0",
     "jquery": "^1.8.0 || ^2.0.0"

changelog.md

@@ -1,3 +1,25 @@
+### 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

component.json

@@ -1,7 +1,7 @@
 {
   "name": "backbone.marionette",
   "description": "Make your Backbone.js apps dance!",
-  "version": "2.4.1",
+  "version": "2.4.2",
   "repo": "marionettejs/backbone.marionette",
   "main": "lib/core/backbone.marionette.js",
   "keywords": [
@@ -16,7 +16,7 @@
     "client",
     "browser"
   ],
-  "license":  "MIT",
+  "license": "MIT",
   "licenses": [
     {
       "type": "MIT",
@@ -31,8 +31,8 @@
   "dependencies": {
     "marionettejs/backbone.babysitter": "*",
     "marionettejs/backbone.wreqr": "*",
-    "jashkenas/backbone": "*",
-    "jashkenas/underscore": "*"
+    "jashkenas/backbone": "1.0.0 - 1.2.1",
+    "jashkenas/underscore": "1.4.4 - 1.8.3"
   },
   "scripts": [
     "lib/core/backbone.marionette.js"

docs/marionette.collectionview.md

@@ -30,6 +30,7 @@ will provide features such as `onShow` callbacks, etc. Please see
   * [CollectionView's `getEmptyView`](#collectionviews-getemptyview)
   * [CollectionView's `isEmpty`](#collectionviews-isempty)
   * [CollectionView's `emptyViewOptions`](#collectionviews-emptyviewoptions)
+  * [CollectionView's `destroyChildren`](#collectionviews-destroychildren)
 * [Callback Methods](#callback-methods)
   * [onBeforeRender callback](#onbeforerender-callback)
   * [onRender callback](#onrender-callback)
@@ -377,6 +378,16 @@ var CollectionView = Marionette.CollectionView({
 });
 ```
 
+### CollectionView's `destroyChildren`
+
+`CollectionView` provides a `destroyChildren` method that will only destroy it's childViews. This can be useful when you would like to empty your view but keep the data in the `collection`. This method takes an optional `checkEmpty` parameter, by default it is set to `true`, if `false` it will disable the call to `checkEmpty` and `destroyChildren` will not show the `emptyView`.
+
+```js
+myView.destroyChildren(); // will show emptyView
+myView.destroyChildren({checkEmpty: false}); // will not show emptyView
+
+```
+
 ## Callback Methods
 
 There are several callback methods that can be provided on a
@@ -747,7 +758,7 @@ new MyCollectionView().render();
 
 ## CollectionView: Automatic Rendering
 
-The collection view binds to the "add", "remove" and "reset" events of the
+After the initial render the collection view binds to the "add", "remove" and "reset" events of the
 collection that is specified.
 
 When the collection for the view is "reset", the view will call `render` on
@@ -759,6 +770,32 @@ one model in to the collection of child views.
 When a model is removed from a collection (or destroyed / deleted), the collection
 view will destroy and remove that model's child view.
 
+When the collection for the view is sorted, the view will automatically re-sort its child views.
+if the `reorderOnSort` option is set it will attempt to reorder the DOM and do this without a full re-render, otherwise it will re-render if the order has changed. Please Note that if you apply a filter to the collection view and the filtered views change during a sort then it will always re-render.
+
+```js
+var collection = new Backbone.Collection();
+
+var myChildView = Marionette.View.extend({
+  template: false
+});
+
+var MyCollectionView = Marionette.CollectionView.extend({
+  childView: myChildView,
+  collection: collection,
+});
+
+var myCollectionView = new MyCollectionView();
+
+// Collection view will not re-render as it has not been rendered
+collection.reset([{foo: 'foo'}]);
+
+myCollectionView.render();
+
+// Collection view will re-render displaying the new model
+collection.reset([{foo: 'bar'}]);
+```
+
 ## CollectionView: Re-render Collection
 
 If you need to re-render the entire collection, you can call the

docs/marionette.compositeview.md

@@ -219,6 +219,8 @@ As with item view instances, the composite view instance is passed as the
 third argument to the `Renderer` object's `render` method, which is
 useful in custom `Renderer` implementations.
 
+As with CollectionView, CompositeView will maintain the sort order of its child views from the collection. It should be noted that the full view will re-render and not just the children, this is to cater for the use case where no `childViewContainer` is used.
+
 ## Events And Callbacks
 
 During the course of rendering a composite, several events will

docs/marionette.region.md

@@ -290,7 +290,7 @@ of the views that are about to be attached – even the nested ones. This can c
 rendering hundreds or thousands of views at once.
 
 If you think these events might be causing some lag in your app, you can selectively turn them off
-with the `triggerBeforeAttach` and `triggerAttach` properties.
+with the `triggerBeforeAttach` and `triggerAttach` properties or `show()` options.
 
 ```js
 // No longer trigger attach
@@ -307,6 +307,13 @@ myRegion.triggerBeforeAttach = false;
 myRegion.show(myView, {triggerBeforeAttach: true});
 ```
 
+Or you can leave the events on by default but disable them for a single show.
+
+```js
+// This region will trigger attach events by default but not for this particular show.
+myRegion.show(myView, {triggerBeforeAttach: false, triggerAttach: false});
+```
+
 ### Checking whether a region is showing a view
 
 If you wish to check whether a region has a view, you can use the `hasView`

docs/marionette.view.md

@@ -33,6 +33,7 @@ behaviors that are shared across all views.
   * [Accessing Data Within The Helpers](#accessing-data-within-the-helpers)
   * [Object Or Function As `templateHelpers`](#object-or-function-as-templatehelpers)
 * [Change Which Template Is Rendered For A View](#change-which-template-is-rendered-for-a-view)
+* [UI Interpolation](#ui-interpolation)
 
 ## Binding To View Events
 
@@ -568,3 +569,35 @@ var MyView = Marionette.ItemView.extend({
 ```
 
 This applies to all view classes.
+
+## UI Interpolation
+
+Marionette UI offers a convenient way to reference jQuery elements.
+UI elements can also be interpolated into event and region selectors.
+
+In this example, the buy button is referenced in a DOM event and the checkout section is referenced in the region selector.
+
+
+```js
+var MyView = Marionette.ItemView.extend({
+
+  ui: {
+    buyButton: '.buy-button',
+    checkoutSection: '.checkout-section'
+  },
+
+  events: {
+    'click @ui.buyButton': 'onClickBuyButton'
+  },
+
+  regions: {
+    checkoutSection: '@ui.checkoutSection'
+  },
+
+  onShow: function() {
+    this.getRegion('checkoutSection').show(new CheckoutSection({
+      model: this.checkoutModel
+    }));
+  }
+});
+```