ZingChart: jsRules

jsRules is an attribute in ZingChart and allows us to pass functions to the JSON to accomplish customizable goals. The function that is passed in gets evaluated by ZingChart during the render process.

Where can I use jsRule?
You can use the jsRule attribute in your configuration object. The attributes that accept jsRule are plot, tooltip, valueBox, plotLabel and scaleLabel.

Why use jsRule?
Using jsRules to adds a level of seperation so that we can keep concerns of writing functions and building the chart separate. It also allows us to add complex chart manipulation that with only JSON we could not accomplish.

Rules VS jsRules
jsRules can handle more cases than rules and is set outside the JSON which is good because it does not clutter the JSON object. Also, jsRules allow for Javascript interactions between variables outside the chart like global arrays. If something can not be accomplished by Rules, a good rule of thumb would be to use jsRules instead as jsRules are much more powerful.

We call jsRule like so:

Tooltip: {
	jsRule: ‘window.customFncs.newFunction()’
}

Since ZingChart is running in the global namespace, your function must be defined in the same namespace. For this example we have prefixed the function with window since we are running the example from an iframe. To avoid name collisions we suggest using a wrapper variable like customFncs

Now we declare the function we want to implement using jsRules:

window.customFncs.newFunction = function(p) {
  var plotIndex = p.plotindex;
  var nodeIndex = p .nodeindex;
  var backgroundColor1 = "";

  if (plotIndex === 1) {
    backgroundColor1 = "red";
    tooltipText = "Red Line";
  } else if (plotIndex === 0) {
    backgroundColor1 = "blue";
    tooltipText = "Blue Line";
  }

  // Return and object with multiple properties
  return {
    text : tooltipText,
    backgroundColor : backgroundColor1
  }	
}

Note: The p parameter is a callback argument provided by ZingChart, similar to an event callback (e). It will contain various properties about the graph including: plotindex, nodeindex, graphid and many more.

Once we have defined the function we need to return something from our function. You will need to return an object with defined attributes that follow the ZingChart declarative syntax.

Here is the finished demo showing how jsRules can be used to manipulate tooltips. This principle can be applied to other endeavors!

Relative Links:

Live Demo