[#131] introduce filter handler

Author: NickQiZhu

dc.js

@@ -1413,6 +1413,10 @@ dc.colorChart = function(_chart) {
 };
 dc.singleSelectionChart = function(_chart) {
     var _filter;
+    var _filterHandler = function(dimension, filter){
+        dimension.filter(filter);
+        return filter;
+    };
 
     _chart.hasFilter = function() {
         return _filter != null;
@@ -1423,8 +1427,10 @@ dc.singleSelectionChart = function(_chart) {
 
         _filter = _;
 
-        if (_chart.dataSet() && _chart.dimension().filter != undefined)
-            _chart.dimension().filter(_filter);
+        if (_chart.dataSet() && _chart.dimension().filter != undefined){
+            var f = _filterHandler(_chart.dimension(), _filter);
+            _filter = f?f:_filter;
+        }
 
         if (_) {
             _chart.turnOnControls();
@@ -1464,6 +1470,12 @@ dc.singleSelectionChart = function(_chart) {
         dc.redrawAll(_chart.chartGroup());
     };
 
+    _chart.filterHandler = function(_){
+        if(!arguments.length) return _filterHandler;
+        _filterHandler = _;
+        return _chart;
+    };
+
     return _chart;
 };
 dc.stackableChart = function (_chart) {

dc.min.js

@@ -1,5 +1,9 @@
 dc.singleSelectionChart = function(_chart) {
     var _filter;
+    var _filterHandler = function(dimension, filter){
+        dimension.filter(filter);
+        return filter;
+    };
 
     _chart.hasFilter = function() {
         return _filter != null;
@@ -10,8 +14,10 @@ dc.singleSelectionChart = function(_chart) {
 
         _filter = _;
 
-        if (_chart.dataSet() && _chart.dimension().filter != undefined)
-            _chart.dimension().filter(_filter);
+        if (_chart.dataSet() && _chart.dimension().filter != undefined){
+            var f = _filterHandler(_chart.dimension(), _filter);
+            _filter = f?f:_filter;
+        }
 
         if (_) {
             _chart.turnOnControls();
@@ -51,5 +57,11 @@ dc.singleSelectionChart = function(_chart) {
         dc.redrawAll(_chart.chartGroup());
     };
 
+    _chart.filterHandler = function(_){
+        if(!arguments.length) return _filterHandler;
+        _filterHandler = _;
+        return _chart;
+    };
+
     return _chart;
 };

src/single-selection-chart.js

@@ -377,6 +377,28 @@ suite.addBatch({
     }
 });
 
+suite.addBatch({
+    'custom filter handler': {
+        topic: function () {
+            var chart = buildChart("pie-chart-filter-handler");
+            chart.filterHandler(function(dimension, filter){
+                var newFilter = filter + 6;
+                dimension.filter(newFilter);
+                return newFilter;
+            });
+            return chart;
+        },
+        'default function should be used to dynamically generate label': function (chart) {
+            chart.filter(60);
+            assert.equal(chart.filter(), 66);
+        },
+        teardown: function (chart) {
+            resetAllFilters();
+            resetBody();
+        }
+    }
+});
+
 
 suite.export(module);
 

test/pie-chart-test.js

@@ -235,6 +235,25 @@ chart.filter(18);
 #### .hasFilter()
 Check whether is an active filter associated with particular chart instance. This function is **not chainable**.
 
+#### .filterHandler([function])
+Set or get filter handler. Filter handler is a function that performs the filter action on a specific dimension. Using
+custom filter handler give you the flexibility to perform additional logic before or after filtering.
+
+```js
+// default filter handler
+function(dimension, filter){
+    dimension.filter(filter); // perform filtering
+    return filter; // return the actual filter value
+}
+
+// custom filter handler
+chart.filterHandler(function(dimension, filter){
+    var newFilter = filter + 10;
+    dimension.filter(newFilter);
+    return newFilter; // set the actual filter value to the new value
+});
+```
+
 ## <a name="stackable-chart" href="#stackable-chart">#</a> Stackable Chart [Abstract]
 Stackable chart is an abstract chart introduced to provide cross-chart support of stackability. Concrete implementation of
 charts can then selectively mix-in this capability.