Protovis JavaScript Charts: Part 1

Tutorial: Protovis JavaScript Charts: Part 1


The Protovis JavaScript library allows users to create and design graphics with a bare minimum of programing. Libraries are collections of small programs that are called by JavaScript on an html page. They take care of the difficult programming so you spend less time writing code and more time making graphics. The code and data are housed on your servers so you are in control.

It also insures that they are viewable on mobile devices. But readers will need a modern browser such as FireFox, Chrome, Safari or Internet Explorer 9 to see them.

This video tutorial explains how to set up your document and make basic charts using Protovis. It is designed for beginners with little or no JavaScript experience. Some concepts are simplified to make getting started easier.


Protovis JavaScript Library Tutorial – Part 1 from kdmcinfo on Vimeo.

Protovis JavaScript Charts: The Basics

Getting Started

Let”s start with the html starter page from the related links section. Open the page in the TextMate text editor. (Free 30-day trial) Under the Window menu select Web preview. TextMate uses the Safari browser engine to give you immediate feedback on your code. Once you have the document open, find the script that looks like this in the head area:


Take a moment to look at the URL, this URL tells the browser where to find the Protovis library. Eventually, you will need to load the Protovis files on your own Web server, but until then use ours. Just know that when we update it, the link will change and your graphics will stop working.

Now look for this script in the body tags.

Note that is says javascript+protovis. This area is where we are going to make our charts.

Creating a variable

Lets start by creating a variable called example. A variable is shorthand for numbers, text or code that you want to reuse.

Example equals a new protovis class file called pv. panel which defines an image area. Set the width and height at 150 pixels.

Notice the periods. These act like links in a chain. This is powerful because any information declared in the chain travels to the end, which is defined by a semicolon.

Remember that case and punctuation are important. If at some point your graphic stops working, check this first.

Creating a chart

So lets make an area chart inside our example panel. Type example.add.pvArea

This calls Protovis class file that describes an area chart. See the pattern?

Next, we need data for the chart in the form of an array. The array is the series of numbers inside the square brackets. Each number has a position, starting with 0. That may seem odd but we need to do this because we use 10-base math.

Now we have to describe the parameters of the chart. Since we want the chart to start at the bottom we set that to 0.

Next, lets set the height of the data point. We do that with a function. Remember, the data has traveled down the chain. The d in the parenthesis looks at the data at each position in the array to do some basic math to calculate the height.

For example, if d = 1 and is multiplied by 75, the height of the first data point is 75

When d = 1.2 and is multiplied by 75, the height of the second data point is 90

Because all of the data points are less than two, they all fit in our 150 pixel panel.

Now we need to describe how the data points are stretched across the panel
starting from the left. We declare a second function that looks at this.index. This represents the position of each data point in the array that has traveled down the chain. Each position is multiplied by 25 to move it to the right 25 pixels.

Finally, we need to tell the example panel to render and add our semicolons.

An area chart appears on the right.

Changing Bar to Line

One of the great things about protovis is that with just a little editing, you can make many different chart types. Lets change Bar to Line.

Lines differ in that they don’t have a bottom and a height. They are described only by their distance from the bottom. Fortunately, we can copy the function from height and apply it to bottom. Delete the width and height and we have a line chart

Dot Charts

Now change Line to Dot.

Dots use the same structure as lines but notice that the one on the left is cut off. That’s because the circle is drawn around the data point. We can fix this with the simplest of Math. Find the 25 in the left property and type + 10 to shift the entire chart to the right 10 pixels.

Creating Pie Charts

Finally lets make a pie chart. In Protovis, this is called a Wedge so replace Dot with the word Wedge.

Wedge has a few important differences. Data in a pie chart illustrates the proportion of the whole, or more simply put the percentage. Protovis gives us several simple ways to calculate this. In this case, we’re going to use a method called pv.normalize. This makes the sum of the data equal to one and creates a copy of the array. Remember 1 is just 2 decimal places away from 100 so this effectively creates a new array with percentage values and passes it down the chain.

Next we need to center the Wedge chart. We do this by setting left and bottom to 75.

Set the outerRadius to 70 pixels to leave 5 pixels of space around the chart. A wedge appears in the Web preview window.

Calculating the Arc

Now we need to calculate the arc of each wedge in our array. We still use function d but with an important change. At the end of our function we see Math.PI.

If you recall, pi is the ratio of a circle’s circumference to it’s diameter. This can be used to calculate an arc for each point of data. This is one of several math shortcuts built into javascript.

We now have a pie with appropriately sized slices. But we want to highlight the first slice. We do that by changing the fillStyle and using a method called pv.colors. This lets us create a series of colors that correspond to our data. We’ll make the first one black and the rest blue. You can also use hexadecimal or rgb colors if you wish.

Adding the Stroke Style

That’s better but we can’t see all of the wedges. So lets add a strokeStyle of white.

That’s it for basic charts in Protovis. The next tutorial will show you how to add lines and labels.


About this Tutorial

This tutorial was produced as a presentation for the Knight Digital Media Center’s Interactive Census Workshop and for the Berkeley Graduate School
of Journalism

Republishing Policy

This content may not be republished in print or digital form without express written permission from KDMC. Please see our Content Redistribution Policy at