Rickshaw toolkit in an Angularjs application

The topic of this article is to show how to integrate smoothly the Rickshaw toolkit in an Angularjs application. The aim is to take advantage of this graphing toolkit within the Angularjs concepts. In order to get the display more user-friendly, Bootstrap CSS and JQuerywill be used.

Explanations will be completed with code snippets and a link to a Github repository will be provided for testing a real example.

Here is the plan of this article:

• PART 1: A short presentation of Rickshaw toolkit
• PART 2: The Angularjs application
• PART 3: The strategy
• PART 4: Defining Angularjs directives
• PART 5: Integrating the directives in the application
• PART 6: Getting a working example

PART 1: A short presentation of Rickshaw toolkit

Rickshaw is an opensource Javascript toolkit based on d3.js for creating interactive graphs. It is developed by Shutterstock and as it is opensource the code is available on Github.

The first and simplest example given by Shutterstock for creating a graph with Rickshaw is to define an empty div element in an HTML page (after loading d3js and Rickshaw scripts) and render a graph built with this div element through rickshaw graph class.

<script src="/vendor/d3.min.js"></script> 
<script src="/vendor/d3.layout.min.js"></script> 
<script src="/rickshaw.min.js"></script>
 
<div id="chart"></div>

<script> 
var graph = new Rickshaw.Graph( {
    element: document.querySelector("#chart"), 
    width: 300, 
    height: 200, 
    series: [{
        color: 'steelblue',
        data: [ 
            { x: 0, y: 40 }, 
            { x: 1, y: 49 }, 
            { x: 2, y: 38 }, 
            { x: 3, y: 30 }, 
            { x: 4, y: 32 } ]
    }]
});
 
graph.render();
</script>

You can find a working example of this code here.

As you can see in the code snippet above, Rickshaw is based on DOM manipulation (with jquery for instance). Rickshaw will populate the empty div element with some SVG tags and will style it with some CSS.

PART 2: The Angularjs application

The Angularjs application will display a simple graph with 4 forms below for changing some properties (the colour, the width and the height) of the graph and add new points in the graph.

The application is based on a single html page. At the first load of the page, the graph will be empty (only one point at 0,0). In order to display something in the graph, you need to first add a point: add a value in the field dedicated to adding a data point and then click the button "Add a data point".

PART 3: The strategy

In an Angularjs application, it is not recommended to directly manipulate the DOM elements as it is explained in the Rickshaw example. The best strategy for manipulating DOM elements in Angularjs application is to use directives which are HTML tags or HTML attributes that are interpreted by the framework for rendering or behaving the way they have been designed. For more information on directives you can read directly the dedicated page in Angularjs Developer Guide here.

The strategy for displaying a graph with Rickshaw in an Angularjs application will be to create a custom directive and use it in our HTML page. The directive will be an HTML tag <rickshawgraph></rickshawgraph> with the following attributes: color, width, height and graphicaldata.

PART 4: Defining Angularjs directives

The custom directive will be defined in an angularjs module dedicated to implementing custom directives for integrating Rickshaw toolkit. The directive will replace the rickshawgraph tag by an empty div element. When the framework will attach the behaviour of the directive to the div element (calling the link function defined in the directive), a new rickshaw graph will be created based on the div element thanks to the Graph class provided by the Rickshaw toolkit and the graph render function will be called to display the graph.

In order to bind the attribute values (color, graphicaldata, width and height) to the data scope of the application and update the view when the data change, some callbacks will be attached to the attributes thanks to the $watch and $watchCollection functions of the scope object. These callbacks will update the Rickshaw graph object and call its update function.

var angularrickshawmodule = angular.module('angularrickshaw', ['ngRoute', 'angularrickshaw.tpl']);
angularrickshawmodule.directive('rickshawgraph', function() {
  return {
    restrict: 'E',
    templateUrl: 'rickshawgraphDirective.html',
    replace: true,
    link: function(scope, element, attrs) {
      var graph = null;
      var series = [{
        color: 'black',
        data: [{x:0,y:0}]
      }];
      
      scope.$watch(attrs.color, function(value){
        if (graph != null) {
          graph.series[0].color = value;
          graph.update();
        }
      });
      
      scope.$watch(attrs.height, function(value){
        if (graph != null) {
          graph.setSize({height: value, width: graph.width});
          graph.update();
        }
      });
      
      scope.$watch(attrs.width, function(value){
        if (graph != null) {
          graph.setSize({height: graph.height, width: value});
          graph.update();
        }
      });
      
      scope.$watchCollection(attrs.graphicaldata, function(value){
        if (graph != null) {
          graph.series[0].data = value;
          graph.update();
        }
      });
      
      graph = new Rickshaw.Graph( {
          element: element[0],
          width: 200,
          height: 100,
          series: series
      });
      graph.render();
    }
  };
});

Here are few comments on the code snippet displayed above:

• The restrict property is set for using the directive as an attribute ('A' value) or an element ('E' value) or both ('AE' value).
• The templateUrl property set the url of the HTML template to use. In our case, rickshawgraphDirective.html is only an empty div element.
• The replace property set whether the element(s) defined in the template should replace the directive element (the rickshawgraph tag in our case).
• The link property is a function with 3 parameters which are the scope of the directives, the DOM element retrieved by jqlite or jquery and the attributes represented by an object.
• The function used for listening to changes of graphicaldata attributes is $watchCollection because the value that would be passed to this attribute should be a function that returns an array or a reference to an array.

PART 5: Integrating the directives in the application

The first step for integrating the custom directives in the application is to use them in the HTML makup. You can see below in the code snippet of the index.html page that a <rickshawgraph> tag is used:

<div class="graphic-content">
    <rickshawgraph color="graphcolor" graphicaldata="graphdata" height="graphheight" width="graphwidth"></rickshawgraph>
    <form class="form-inline" role="form">
        <!-- The form for modifying one attribute of the custom directive -->
    </form>
    <form class="form-inline" role="form">
        <!-- The form for modifying one attribute of the custom directive -->
    </form>
    ...
</div>

The second step is to inject the dependency of the angularrickshaw module (the module in which the custom directives are defined) into the rickshawapp module which is the application main module. The scope used for defining the data injected in the attributes of the custom HTML tag (color, graphicaldata, width and height) will also be defined in a controller attached to the rickshawapp module.

var rickshawapp = angular.module('rickshawapp', ['ngRoute', 'angularrickshaw']);
rickshawapp.controller('MainCtrl', function MainCtrl($scope) {
  $scope.text = "The aim of this code example is to show how to implement some angular directives for integrating Rickshaw framework in Angularjs.";
  $scope.title = "Test Angular Rickshaw";
  $scope.graphcolor = "steelblue";
  $scope.graphheight = 100;
  $scope.graphwidth = 200;
  $scope.graphdata = [{x:0,y:0}];
  ...
});

PART 6: Getting a working example

You can find a working example in my github repository (the angularrickshaw folder).