[#67] fix filtered listener interaction problem and updated api doc

Author: NickQiZhu

dc.js

@@ -652,17 +652,14 @@ dc.baseChart = function(_chart) {
         return result;
     };
 
-    _chart.filter = function(f) {
-        var result = _chart.doFilter(f);
-
-        if(arguments.length) _listeners.filtered(_chart, f);
-
-        return result;
+    _chart.invokeFilteredListener = function(chart, f) {
+        if(f !== undefined) _listeners.filtered(_chart, f);
     };
 
     // abstract function stub
-    _chart.doFilter = function(f) {
+    _chart.filter = function(f) {
         // do nothing in base, should be overridden by sub-function
+        _chart.invokeFilteredListener(_chart, f);
         return _chart;
     };
 
@@ -1108,6 +1105,8 @@ dc.coordinateGridChart = function (_chart) {
             _chart.turnOffControls();
         }
 
+        _chart.invokeFilteredListener(_chart, _);
+
         return _chart;
     };
 
@@ -1404,6 +1403,8 @@ dc.singleSelectionChart = function(_chart) {
             _chart.turnOffControls();
         }
 
+        _chart.invokeFilteredListener(_chart, _);
+
         return _chart;
     };
 

dc.min.js

@@ -185,17 +185,14 @@ dc.baseChart = function(_chart) {
         return result;
     };
 
-    _chart.filter = function(f) {
-        var result = _chart.doFilter(f);
-
-        if(arguments.length) _listeners.filtered(_chart, f);
-
-        return result;
+    _chart.invokeFilteredListener = function(chart, f) {
+        if(f !== undefined) _listeners.filtered(_chart, f);
     };
 
     // abstract function stub
-    _chart.doFilter = function(f) {
+    _chart.filter = function(f) {
         // do nothing in base, should be overridden by sub-function
+        _chart.invokeFilteredListener(_chart, f);
         return _chart;
     };
 

src/base-chart.js

@@ -368,6 +368,8 @@ dc.coordinateGridChart = function (_chart) {
             _chart.turnOffControls();
         }
 
+        _chart.invokeFilteredListener(_chart, _);
+
         return _chart;
     };
 

src/coordinate-grid-chart.js

@@ -19,6 +19,8 @@ dc.singleSelectionChart = function(_chart) {
             _chart.turnOffControls();
         }
 
+        _chart.invokeFilteredListener(_chart, _);
+
         return _chart;
     };
 

src/single-selection-chart.js

@@ -15,6 +15,7 @@ The entire dc.js library is scoped under **dc** name space. It does not introduc
 * [Geo Choropleth Chart [concrete] < Single Selection Chart < Color Chart < Base Chart](#geo-choropleth-chart)
 * [Data Count Widget [concrete] < Base Chart](#data-count)
 * [Data Table Widget [concrete] < Base Chart](#data-table)
+* [Listeners](#listeners)
 * [Utilities](#utilities)
 
 ### Function Chain
@@ -793,6 +794,25 @@ Get or set sort order. Default value: ``` d3.ascending ```
     chart.order(d3.descending);
 ```
 
+## <a name="listeners" href="#listeners">#</a> Listeners
+All dc chart instance supports the following listeners.
+
+### .on("preRender", function(chart){...})
+This listener function will be invoked before chart rendering.
+
+### .on("postRender", function(chart){...})
+This listener function will be invoked after chart finish rendering including all renderlets' logic.
+
+### .on("preRedraw", function(chart){...})
+This listener function will be invoked before chart redrawing.
+
+### .on("postRedraw", function(chart){...})
+This listener function will be invoked after chart finish redrawing including all renderlets' logic.
+
+### .on("filtered", function(chart, filter){...})
+This listener function will be invoked after a filter is applied.
+
+
 ## <a name="utilities" href="#utilities">#</a> Utilities
 
 ### dc.renderAll([chartGroup])