Merge pull request #861 from marionettejs/sjs/itemEvents

add itemEvents to collectionViews

docs/marionette.collectionview.md

@@ -36,6 +36,7 @@ will provide features such as `onShow` callbacks, etc. Please see
   * ["item:removed" event](#itemremoved-event)
   * ["itemview:\*" event bubbling from child views](#itemview-event-bubbling-from-child-views)
 * [CollectionView's `itemViewEventPrefix`](#collectionviews-itemvieweventprefix)
+* [CollectionView's `itemEvents`](#collectionviews-itemevents)
 * [CollectionView render](#collectionview-render)
 * [CollectionView: Automatic Rendering](#collectionview-automatic-rendering)
 * [CollectionView: Re-render Collection](#collectionview-re-render-collection)
@@ -453,6 +454,29 @@ Normally, you would have your item view listening to DOM
 events or model change events, and then triggering an event
 of its own based on that.
 
+## CollectionView's `itemEvents`
+You can specify an `itemEvents` hash or method which allows you to capture all bubbling itemEvents without having to manually set bindings.
+
+```js
+itemEvents: {
+  "render": function() {
+    console.log("an itemView has been rendered");
+  }
+}
+```
+
+You can also use a method for `itemEvents` that returns a hash.
+
+```js
+itemEvents: function() {
+  return {
+    "render": function() {
+      console.log("an itemView has been rendered");
+    }
+  }
+}
+```
+
 ## CollectionView's `itemViewEventPrefix`
 
 You can customize the event prefix for events that are forwarded

spec/javascripts/collectionView.spec.js

@@ -738,6 +738,61 @@ describe("collection view", function(){
     });
   });
 
+  describe("calling itemEvents via an itemEvents method", function() {
+    var renderCalled;
+
+    var CV = Marionette.CollectionView.extend({
+      itemView: ItemView,
+      itemEvents: function() {
+        return {
+          "render": function() {
+            renderCalled = true;
+          }
+        }
+      }
+    });
+
+    beforeEach(function() {
+      renderCalled = false;
+      var cv = new CV({
+        collection: (new Backbone.Collection([{}]))
+      });
+
+      cv.render();
+    });
+
+    it("should call the associated itemEvent when defined when itemEvents is a method", function() {
+      expect(renderCalled).toBe(true);
+    });
+  });
+
+  describe("calling itemEvents via the itemEvents hash", function(){
+    var renderCalled;
+
+    var CV = Marionette.CollectionView.extend({
+      itemView: ItemView,
+      itemEvents: {
+        "render": function() {
+          renderCalled = true;
+        }
+      }
+    });
+
+    beforeEach(function() {
+      renderCalled = false;
+
+      var cv = new CV({
+        collection: (new Backbone.Collection([{}]))
+      });
+
+      cv.render();
+    });
+
+    it("should call the associated itemEvent when defined", function() {
+      expect(renderCalled).toBe(true);
+    });
+  });
+
   describe("has a valid inheritance chain back to Marionette.View", function(){
 
     var constructor;

src/marionette.collectionview.js

@@ -203,13 +203,30 @@ Marionette.CollectionView = Marionette.View.extend({
     // prepending "itemview:" to the event name
     this.listenTo(view, "all", function(){
       var args = slice(arguments);
-      args[0] = prefix + ":" + args[0];
+      var rootEvent = args[0];
+      var itemEvents = this.getItemEvents();
+
+      args[0] = prefix + ":" + rootEvent;
       args.splice(1, 0, view);
 
+      // call collectionView itemEvent if defined
+      if (typeof itemEvents !== "undefined" && _.isFunction(itemEvents[rootEvent])) {
+        itemEvents[rootEvent].apply(this, args);
+      }
+
       Marionette.triggerMethod.apply(this, args);
     }, this);
   },
 
+  // returns the value of itemEvents depending on if a function
+  getItemEvents: function() {
+    if (_.isFunction(this.itemEvents)) {
+      return this.itemEvents.call(this);
+    }
+
+    return this.itemEvents;
+  },
+
   // render the item view
   renderItemView: function(view, index) {
     view.render();