 
HOW TO USE THE LIBRARY
To use the library, you first have to include it. Start by downloading the library to your local hard drive. Right-click on graph.js and select "Save Link As...." Next, add the following line of code below the <HEAD> tag of your document:
<SCRIPT LANGUAGE="JavaScript1.2" SRC="graph.js"></SCRIPT>
You will also need a collection of images to reside in the same directory as the file in order for the graphs to display correctly. You can get these images by downloading graphimg.zip. Now that the library and images have been included, you can call Graph Builder functions from within the <BODY> of your document, and the graphs will be built as the page loads.
Getting Started
All the interaction with the JavaScript Graph Builder library takes place inside the body of your HTML document, which lets you place the graph anywhere you want among regular HTML content. Once you decide where in the page you want the graph to appear, add the following lines of code:
<SCRIPT LANGUAGE="JavaScript1.2">
var g = new Graph(400,300);
</SCRIPT>
This calls the Graph object constructor function, which creates a new Graph object that you can use to set attributes of your graph before you build it. By calling the constructor function, you've already set two properties. The first argument specifies the width (in pixels) of the graph, and the second specifies the height. The Graph object above has a width of 400 pixels and a height of 300 pixels.
Once the Graph object has been created, you can set the style of the graph (more on that later) and add the data. The data is the actual information you wish to plot. Because of the limitations of HTML, it would be extremely difficult to graph a line graph or a pie chart. Therefore, the Graph Builder library builds only bar graphs. The data that you are entering are y-values in the order they appear in the graph (from left to right). The x-values will be assigned automatically, determined by the order the data is entered and the x-scale definition (see the Using Scales section).
In this example, I want to plot the number of hits on my Web page about fly fishing. I have collected the data from logs and I wish to graph it:
Date | Hits |
8/9/98 | 124 |
8/10/98 | 138 |
8/11/98 | 216 |
8/12/98 | 143 |
8/13/98 | 256 |
8/14/98 | 302 |
To plot this data, I can use the addRow() function and simply list the data:
<SCRIPT LANGUAGE="JavaScript1.2">
var g = new Graph(300,200);
g.addRow(124,138,216,143,256,302);
g.build();
</SCRIPT>
(Note that I highlighted the new code in grey.) You'll see that I snuck in the build() function. Call this function after you have set all the attributes of the graph, and it will make the graph display. The result of this code is this:
Of course, this isn't a very satisfactory plot because it's unclear what exactly I am trying to plot. I'll have to do a little more work setting the Graph object attributes before I can call this a bona fide graph.
Using Scales
Start by setting the Y-axis scale. By setting the scale attribute, the Graph Builder library will automatically add a Y-axis scale. For this data, a good scale would be 50:
<SCRIPT LANGUAGE="JavaScript1.2">
var g = new Graph(300,200);
g.addRow(124,138,216,143,256,302);
g.scale = 50;
g.build();
</SCRIPT>
Here's the result:
So now I've got a nifty Y-axis scale running up the left side of the graph to indicate the values of the bars. There's another way to get the exact values of the bars, though, which you may not have noticed. If you hold the mouse over the bar (on Windows/UNIX version of Navigator and Internet Explorer), a small yellow box will appear showing the exact value of the data. Try it!
My graph still isn't quite ready, because it's unclear to what the X-axis corresponds. There are three types of X-axis scales you can choose from. Because my data points are each on separate days, I am going to use the date-type X-axis scale. However, if I had data that I wanted to graph over hours or minutes, I would use the time-type X-axis scale. There is also the "other" type of X-axis scale which can be used to create a more generalized X-axis for almost any sort of data.
To set the starting date of the X-axis, use the setDate() function. This function takes three arguments: the month, the day, and the year. Here's my example, continued:
<SCRIPT LANGUAGE="JavaScript1.2">
var g = new Graph(300,200);
g.addRow(124,138,216,143,256,302);
g.scale = 50;
g.setDate(8,10,1998);
g.build();
</SCRIPT>
Here's the result:
And that's it. In five lines of code, I've created the graph I need to convey my data. But there's much more we can do, so keep reading.
If, instead, my data points came every hour, I could use the setTime() function to set the starting time on the X-axis. This function takes three arguments: the hour, the minute, and a boolean (true/false), which specifies whether the time is AM or PM. True means PM; false means AM. If I wasn't graphing times or dates, I could use the setXScale() to create a more generalized X-axis scale. This function takes only one argument, which is the starting value of the X-axis (13, e.g.).
What if, however, I was graphing points every three days, or every week, or even every 42 minutes? How would I do that? By setting the inc property of the Graph object, you can determine how much time (or, more generally, x-values) passes between each data point. For example, if I had a date-type x-scale and I set inc to 7, it would mean the points came every week. If I had a time-type x-scale and I set inc to 60, it would mean the points came every hour. (inc means minutes in the time-type scale, and days in the date-type scale.)
ADDITIONAL FUNCTIONALITY
Legends
Besides plotting data and setting scales, Microsoft Excel lets you add labels to your axes, legends, and titles. Not to worry, the Graph Builder library can handle that, too. To add a label to the X-axis, simply set the xLabel property of the Graph object. To add a label to the Y-axis, set the yLabel property. To add the title? Set the title property. Continuing with my example:
<SCRIPT LANGUAGE="JavaScript1.2">
var g = new Graph(300,200);
g.addRow(124,138,216,143,256,302);
g.scale = 50;
g.setDate(8,10,1998);
g.title = "My Fly Fishing Page";
g.xLabel = "Date";
g.yLabel = "Hits";
g.build();
</SCRIPT>
Here's the result:
Legends are a bit more complicated. They are only relevant when you are graphing more than one series at a time. That is simple to do, however, by successive calls to the addRow() function. Say, in my example, that instead of just graphing hits on my Fly Fishing page, I was also graphing hits on my Sport Fishing page, and that I wanted to get an idea of how the growth in hits compare. I would want to graph them side-by-side, and so I'd make two calls to the addRow() function. Then, I'd use the setLegend() function and list the names of the series:
<SCRIPT LANGUAGE="JavaScript1.2">
var g = new Graph(300,200);
g.addRow(124,138,216,143,256,302);
g.addRow(201,234,340,210,314,320);
g.scale = 50;
g.setDate(8,10,1998);
g.title = "My Web Pages";
g.xLabel = "Date";
g.yLabel = "Hits";
g.setLegend("Fly Fishing","Sport Fishing");
g.build();
</SCRIPT>
Here's the result:
Stacked and Relative-Area Graphs
Say that instead of a side-by-side graph, I want to stack the values one on top of each other, so that I can see the total growth of hits on my two Web pages, not just each one individually. I can do this by setting the stacked property to true. But say that I not only want to stack the values on top of each other, but I want to see the relative contributions, as a percentage, of the two Web pages to the total amount of hits. I can do this by setting the relative property to true.
A stacked graph:
A relative-area graph:
FINAL NOTE
Because there's quite a bit you can do with the Graph Builder library, I've compiled a Quick Reference sheet that you can print out. It also lists six other attributes not mentioned here that you can set to tweak its appearance.
Comments/Questions? Please send feedback to: mikebos@netscape.net
UPDATE - 10/22/98
After getting the same request from many different developers, I decided to update the Graph Builder library to include one more function, setXScaleValues(). This function takes any number of arguments (usually the number of x values) and can be used to explicitly label each column. For instance, if you wanted to graph the sales of different types of fruit in your store, it would be useful to set the x-scale values to "Oranges", "Apples", and "Lemons". Calling g.setXScaleValues("Oranges", "Apples", "Lemons") (where g is your Graph object) will accomplish this.
ABOUT THE AUTHOR
Michael Bostock is a class of 2000 student at Princeton University in New Jersey. He is a Computer Science major in the Engineering school. When not interning with Netscape Communications Corporation, he is a tenor saxophonist in the thousand-member strong Princeton University Band.
previous page
|