Protovis Part 3: Variables and animation

Introduction

Part 3 of our Protovis JavaScript library tutorials introduces variables. You’ll learn how to turn charts into templates you can update and publish in minutes. You’ll edit the wedge chart you built in Part 1 and add some basic animation.

Variables

Simply put, variables are shorthand for code that you want to reuse. We’re going to create a set of variables at the top of the script that will allow us to edit the finished chart in the fewest steps possible. Make sure your preview window is open. Lets start by typing the letters v-a-r, hit space and type w = 150 and add a comma. We have just written a variable that says if the letter w is found in our code, its value will always be 150. We’ll use this as our width. Hit return and hit Tab then type h = 150, this will be our height. Hit return and type r = w/2, r will be used to define the radius of our wedge chart. because w = 150, when it’s divided by two we get a radius of 75 Hit return and type data = now copy the data array from the wedge chart. Make sure to include the square brackets. paste the array after the “data =” variable then type a comma at the end. Hit return and type sum = pv.sum(data), We’re going to use a different method to calculate the wedges in this chart because we want to preserve the values in the data array to create labels. Finally, hit return and type colors = [] (square brackets). Now copy the colors from the fill style and paste them into the square brackets. Make sure to end the chain with a semicolon.

Update the chart

Now we’re ready to edit the wedge code. Replace the width value of 150 with the variable w and the height value of 150 with the variable h. Then in the data property, replace the entire value with the variable data. Don’t worry that the preview has changed. We’ll fix that in a moment. Next, replace the left value of 75 with w/2 and replace the bottom value with h/2. This is the same basic math we used to set the r variable. Since this has already been done for the r variable we can simply replace the outerRadius value of 75 with r We also have to fix the angle of our wedges. to do this, we simply have to change d to d / sum. Now notice that if you change the w and h variables to 200, the entire graphic scales proportionately. Be sure to change them back to 150 to follow along. Finally, select the array of colors in the fillStyle property and replace it with the variable colors.

Now lets add some labels to the chart. Put cursor after the lineWidth value, hit return and type .anchor(“center”). This will anchor each label to the center of it’s wedge. Next, type .add(pv.Label). Notice that labels appear in the chart but they rotate around its center. To make them all horizontal, hit return and type .textAngle(0) Hit return and type .textStyle(“white”) so they are easier to see. hit return and type .font(“bold 10pt sans-serif”) and end the chain with a semicolon.

It’s important that the labels are closer to the edge of the wedges. Otherwise, when the chart is resized, they may bump into each other. Fortunately, there’s a nifty little trick to doing this. Copy the entire wedge code and paste a copy below it. Now delete all of the label code from the original, starting with . anchor. Go to the copied code and find .outerRadius and put your cursor at the end of the line. Hit return and type .innerRadius (r/2). This creates a donut chart on top of the pie chart that moves the labels outward. That’s great but we don’t want to see two charts. To fix this, Change the fillStyle value to null to make the chart invisible. Then delete the .strokeStyle.

Perfect. Now let’s animate this chart. Go to the protovis web site at vis.stanford.edu/protovis There is a lot of code and documentation here that you are free to use, so don’t be shy. We’re going to the documentation area to borrow some sample code. Click on Documentation on the top. on the resulting page, click on wedges in the left column. This takes us to a page with all the documentation for the wedge chart. scroll down to the very bottom until you the see a chart that animates when you move your mouse over it. Look at the code on the left and find the line near the top that starts with .def. Copy this entire line. Return to TextMate and paste it above the .data property in the original wedge code. This code essentially declares a variable on the fly. “o” will be whatever the mouse is over. The -1 is the position in the array. Because it’s negative number, it’s used to turn the animation off when the mouse moves away from the chart. Go back to the protovis site and select everything from the .left property down to and including the .event property. Make sure to get it all then copy it. Return to text mate and select the left and bottom properties in the original wedge. Take note of the values. We’ll need them in a minute. Delete these then put your cursor at the end of the linewidth line but before the semicolon. Hit return and paste.

Finishing up

Let’s take a look at the code. We’re now using a different math function to define the angle of each wedge. But the second line is what makes animation possible. Essentially, it asks if the mouse is over each item in the data array, which is signified by this.index. If the mouse is over an item, then the corresponding wedge is offset by 10 pixels. If the mouse is not over the item, it defaults to 0 pixels. the .event property listens for the mouse position and feeds the result into the function. OK. So we still have some editing to do. Find the left property you just pasted in. Change the value of 75 to w / 2. Next find the bottom property and change the value of 75 to h / 2. Lets make the animation offset a variable so it can be easily edited. Change the value of 10 in both the left and bottom properties to the word offset. Scroll up to your variables and put your cursor at the end of the h variable line. hit return and type offset = 10 Finally, we have to change our radius to make sure the offset wedges fit inside the panel. Find the r variable and type – offset after the w/2 And there you go. You now have a custom pie chart you can update and publish in minutes. Below is the final completed code Be sure to check out our next tutorial. We’ll use an external data file to create an animated bar chart.