Create new chart types

Protobi is a lightweight library to visualize survey data in your browser. Protobi includes a number of standard chart types, but also allows you to create your own charts.

So if you're familiar with web programming, this tutorial is for you. Protobi's API is open, and the example below shows how you how to extend it.

And in any case we're happy to create custom widgets for your specific project and we have a growing library of general charts you can import and extend.

Libraries included

Protobi includes leading visualization libraries d3.js and Plotly.js as well as utility libs like lodash.js , Backbone.js and jQuery.

You can include additional libs and stylesheets, as shown below.

Example

Here we'll create a new chart type that uses The Wall Street Journal's Squaire algorithm to displays state data geographically as a pseudo-map with neat squares:

The WSJ Squaire chart assumes an input variable with two-character state abbreviations. For this example we have a survey with a variable s3 with exactly this: 

Define a minimal chart

In the Admin tab of the project, create a new document called squaire.js. Then press "Edit/Run..." and paste the following code there and press "Save."

This is the custom code that defines our new chart. The code below is boilerplate that extends Protobi's BasicElement to define a new SquaireChart.

You don't really need to read it in great detail, just note that there are two methods that your code will override:

• preRender: function(callback) {}
• render: function() {}`

The method preRender is where you'll put background calculations or code should run asynchronously in the background before rendering.

The method render is where you'll actually draw the visualization. Specifically, you'll render a DOM element referenced by this.$content.

$(function() {
$(".protobi.app").on("protobi-loaded", function() {
var BasicElement = protobi.widgetFactory.getView('BasicElement')

  var SquaireChart = BasicElement.extend({
    alias: "Squaire",
    className: 'element resizable squaire',
    defaultOptions: {},
    moreEvents: {},
    resizable: true,
    showMargin: false,
events: function () {
  var parentEvents = BasicElement.prototype.events
  if (_.isFunction(parentEvents)) {
     parentEvents = BasicElement.prototype.events();
  }
  return _.extend({}, parentEvents, this.moreEvents);
},

renderChildren: function () {
  return false
},

postInitialize: function (args) {
  var self = this;
  SquaireChart.__super__.postInitialize.apply(this, arguments);
  this.listenTo(this.tabular, 'filter', self.update)
  this.listenTo(this.model, 'change', self.update)
  this.listenTo(this.viewModel, 'change:format', this.update)
},

preRender: function (callback) { 

  // ... add your calculation code here ...

  return callback(null, this.data)
},

renderBody: function () {
  // ... add your rendering code here...
  this.$content.html("Hello World!!);

  return;
}

  })
  protobi.widgetFactory.registerView('SquaireChart', SquaireChart)
});
})

Protobi uses Backbone.js to define charts. The above code extends the basic chart type to create a new one called "SquaireChart":

Apply the new chart

You can now apply this new chart type to any element. Create a new element. Select "Edit JSON..." and set "chartType": "SquaireChart":

Voilá, you now have a new chart that uses this code to render the element.
This doesn't do anything special yet but it will...

Define data prep

Do any calculations in the method preRender. This method is called in the background before rendering any time the element or filters change.

Here we'll just calculate the distribution of this element given its key and field attributes. Replace the method preRender as shown below:

    preRender: function (callback) {
      "use strict";
      var self = this;

  this.table = this.tabular.getDistribution(this.model, ['current']);

  return callback(null, this.data)

},</code></pre><h2>Include external libraries your code requires</h2><p>In the Admin tab of the project, create a new process called <strong>header</strong>. This will allow you to specify any additional resources your project requires. Then press "Edit/Run..." and paste the following code there and press "Save."</p><p>At the top include any external library calls your method requires. Here we'll call the WSJ Squaire library directly from GitHub using jsDelivr:</p><pre><code><script type="text/javascript" src="https://app.protobi.com/v3/datasets/5c1804033e40da00044ff56f/direct/squaire.js"></script>  

  

In the example above replace 5c1804033e40da00044ff56f with your project ID which can be found in the URL.

Render the chart

Replace the line // ... add your rendering code here... with code that draws the chart as you would like to see it. Add any content to a DOM element defined by the variable this.$content.

In this example we'll adds two new

 renderBody: function () {
      "use strict";


  var self = this;
  if (!self.table) return;
  self.$content.empty()
  var chartOptions = self.getChartOptions();
  var showMissing = this.getShowMissing()

  var mapContainer = $("<div>")
    .addClass('map-container')
    .appendTo(this.$content)

  var tipContainer = $("<div>")
    .addClass('squaire-toolbox')
    .appendTo(this.$content)

  var data = {}
  this.table.getRowKeys().map(function (rowKey) {
    var freq = self.table.getFreq(
     'current', 
      rowKey, 
      showMissing
    )
    data[rowKey] = {
      "value": freq
    }
  })

  var map = new Squaire(data,
      {
        colors: d3.scale
          .quantize()
          .domain([1, 5])
          .range(['#c9e2f5', '#0098db']),
        el: mapContainer[0]
      });

  return;

    }