KavaChart Applet Tutorial


This document is a quick start guide to using KavaChart applets. If you're already familiar with using Java applets, you might want to skip ahead, but any user can find valuable tips on using KavaChart here.


The Basics

A Java applet is a small software application that runs within a web browser. When a web page contains an "applet" tag, a space in the web page is assigned to the Java program defined by the applet tag, and the browser starts a Java Virtual Machine (JVM) to run the program. The JVM will then download the program and run it, displaying whatever the program is designed to do.

An applet definition looks like this:

	<APPLET CODE=programname WIDTH=100 HEIGHT=100>
</APPLET>

The applet definition starts with <APPLET ...> and ends with </APPLET>. The definition start includes some information about what applet code you want to run, and how big the applet should be.

In a web page's HTML, this defintion will cause your browser to create a 100x100 pixel rectangle, and transfer control of that visual space to the Java program "programname". A KavaChart applet would draw a chart in this space.

The program code for this example is contained in the file "programname.class". More complex programs use multiple class files, but all applets have a starting point, which is named in the applet defintion.

Archives

KavaChart applets are contained in archive files, which end with a ".jar" suffix. A jar file is a zip format compressed archive with Java program classes and other resources. You'll find the KavaChart applet jar files in the directory com.ve.kavachart.jars.

Each KavaChart applet is contained in a jar file of the same name. For example, the bar chart class is called "barApp", and it's contained in the jar file "barApp.jar". Here's an example:

	<APPLET CODE=com.ve.kavachart.applet.barApp ARCHIVE="barApp.jar" WIDTH=100 HEIGHT=100>
</APPLET>

You'll also notice that the CODE attribute includes a long name: "com.ve.kavachart.applet.barApp". All standard KavaChart applets start with the specifier "com.ve.kavachart.applet". This is required to enforce Java's namespace rules.

Codebase

All our examples so far assume that the applet will be loaded from the same directory as the HTML. There are times this might not be practical, though. For example, your page might be generated by a servlet, where the "current directory" is ambiguous. In these cases, you can use the applet CODEBASE directive to point to the actual location of your KavaChart jar archive. It's also important to note that any images or other resources your chart uses must also be under the CODEBASE. Here's an example:

	<APPLET CODE=com.ve.kavachart.applet.barApp 
ARCHIVE="barApp.jar"
CODEBASE="http://localhost:8080/appletstuff/"
WIDTH=100 HEIGHT=100>
</APPLET>

The examples above will indeed draw a chart, but it's not very interesting. The chart will not have any meaningful data, and it will be tiny; 100 pixels square. To make the chart more interesting, we'll use applet PARAM statements to define the chart's aesthetic and data properties.


Adding Parameters

To make your chart applet meaningful, you'll have to add some parameters. KavaChart defines a large number of parameters to manage your chart's aesthetics and data. Insert your parameters between the applet opening and closing tags like this:

	<APPLET CODE=com.ve.kavachart.applet.barApp ARCHIVE="barApp.jar" WIDTH=300 HEIGHT=300>
<PARAM NAME="dataset0yValues" value="123,432,234">
<PARAM NAME="titleString" value="My Chart Title">
</APPLET>

This definition will yield a chart like this:

We can add more parameters to modify the overall appearance of the chart. Here's the same applet with a slightly more complex definition:

This definition just changes the size a little, and defines some things like axis titles and bar colors. The actual HTML code is still pretty simple:

	
<APPLET CODE=com.ve.kavachart.applet.barApp 
ARCHIVE=barApp.jar WIDTH=500 HEIGHT=300> <PARAM NAME="dataset0yValues" value="123,432,234"> <PARAM NAME="titleString" value="My Chart Title"> <PARAM NAME="xAxisLabels" value="Popcorn,Candy,Soft Drinks"> <PARAM NAME="outlineColor" value="black"> <PARAM NAME="individualColors" value="true"> <PARAM NAME="yAxisOptions" value="gridOn"> <PARAM NAME="xAxisOptions" value="tickOff,rotateTitle"> <PARAM NAME="3d" value="true"> <PARAM NAME="yAxisTitle" value="Millions of Dollars Per Year"> <PARAM NAME="xAxisTitle" value="Movie Revenue"> </APPLET>

Dynamic Parameters

It's worth noting that all the applets' parameters are simple text. They're either strings or comma delimited lists of strings. That makes it easy to make changes to your applet definitions with whatever server-side scripting language you have available.

By changing one of the parameters when your server sends the page out, you will change the chart your users see. For example, let's say your server has Apache style scripting enabled. You should be able to set your title like this:

	<PARAM name="titleString" value="<!--#echo $DATE_GMT-->">

You might not be particularly interested in displaying the current date as your chart title, but this technique has powerful application elsewhere in your chart definition. For example, if you're using ASP or JSP to generate your output, you can simply define the data and labels based on information in your server's database.

You could even modify all the text in an applet based on a browser's locale, assuming your server has the ability to tell you about the user's locale preferences.


Data Sources

If your charts all had the same data, you could just create a GIF or JPEG image and embed it into your page. You're using applets because you want to use data that changes. It might change based on the user viewing the information, or it might vary over time.

KavaChart gives you several ways to apply dynamic data to your charts. You can use a scripting language to change the PARAM statements that define your data, you can instruct the applet to reach out to a URL to acquire data, or you can define your own data interface, using Java code and KavaChart's DataProvider interface.

Inline Data

For most recent web servers, the easiest way to apply dynamic data to a chart is to use your server's scripting facilities to write an applet definition that contains the dynamic data. In this case, the data is written into the applet's PARAM statements. For example, let's say you want an applet definition that looks like this:

	<APPLET CODE=com.ve.kavachart.applet.barApp ARCHIVE="barApp.jar" WIDTH=300 HEIGHT=300>
<PARAM NAME="dataset0yValues" value="123,432,234">
</APPLET>

In this case, the values "123,432,234" would vary depending on information in your company's internal databases.

If your server supports PHP, and you can put the values "123,432,234" from your database into a variable named "dat", you could build the data PARAM statement like this:

	<APPLET CODE=com.ve.kavachart.applet.barApp ARCHIVE="barApp.jar" WIDTH=300 HEIGHT=300>
		<PARAM NAME="dataset0yValues" value="<?=dat?>">
</APPLET>

Your chart will vary every time you view it, based on the value of the information in the PHP variable "dat". Since all KavaChart's applet definitions are simple text, you can build or vary any PARAM using JSP, ASP, Perl, PHP, ColdFusion, Python, or whatever other scripting language you might be using.

URL Data

KavaChart also has the ability to read data from a specified URL. Several PARAMs are specifically designed to accomodate this feature. The primary advantage of this approach is that the applet can re-read the data periodically to provide real time data updates.

Here's a sample applet definition that reads data from a URL:

	<APPLET CODE=com.ve.kavachart.applet.barApp ARCHIVE="barApp.jar" WIDTH=300 HEIGHT=300>
<PARAM NAME="dataset0yURL" value="data.dat">
<PARAM NAME="networkInterval" value="5">
</APPLET>

This definition creates a bar chart based on the data in "data.dat". The applet loads "data.dat" when it starts up, and then reloads it every 5 seconds. You can create a definition like this and experiment with it by changing the file "data.dat". The applet will update every 5 seconds to match your new data.

It's not very practical to manually update a data file to provide real-time data, though. More likely, your applet will point to a cgi-bin script or an ASP or JSP to provide the data. This might require a slightly more sophisticated applet definition.

Applets run in a very secure context, called a "sandbox". The security sandbox prevents an applet from accessing any URL outside its "CODEBASE". Our example above will run because the default CODEBASE is the same as the directory that contains the applet's HTML. If you're pointing to a cgi-bin directory, however, you'll need to make sure cgi-bin is contained within your CODEBASE.

To do this, your applet definition might change to look like this:

	<APPLET CODE=com.ve.kavachart.applet.barApp 
CODEBASE="http://localhost:8080/"
ARCHIVE="appletstuff/barApp.jar" WIDTH=300 HEIGHT=300>
<PARAM NAME="dataset0yURL" value="cgi-bin/data.cgi">
<PARAM NAME="networkInterval" value="5">
</APPLET>

In this example, our data script is found at "http://localhost:8080/cgi-bin/data.cgi". The jar file is found at "http://localhost:8080/appletstuff/barApp.jar". Our applet HTML can be located anywhere on the server.

In the definition, CODEBASE has changed to point to the root directory of our server. That means we're free to point to any script on the server to get the applet's data. It also means we had to change our ARCHIVE definition to point to add the path to the applet's jar file.

DataProvider Data

If you have some Java programming resources, you might want to implement a KavaChart DataProvider. A DataProvider is designed to supply data to all sorts of charting objects, including applets. While a DataProvider is subject to the same restrictions as a URL data source, it's also reusable. You can use the same DataProvider to supply data to a JSP ChartTag, or a scriptlet. After creating a DataProvider, you can install it by setting a param:

<param name="dataProvider" value="MyDataProvider">

This example assumes your DataProvider class is named "MyDataProvider", and that it has a "zero-argument" constructor. Consult the KavaChart AlaCarte User's Guide for more information about using DataProviders.


Using the Chart Wizard

KavaChart applet parameters are easy to learn and easy to add to your HTML, but sometimes it's hard to find exactly the parameter you're looking for. To help you design your charts Visual Engineering has created a Chart Wizard to build KavaChart applet definitions. The Chart Wizard starts with a selection of chart types that correspond to the KavaChart applet collection.

wizard

You can select chart items by clicking on the preview image, or by navigating the style tree. Each chart item has a property sheet that you can use to adjust things like margins, fonts, colors, titles, and so on.

The Chart Wizard simulates your data inputs, because we assume you want to use dynamic data sources. The wizard's data simulator lets you view the chart's appearance with a variety of data to see how your design holds up.

results

When you're finished with your chart design, the wizard walks you through some common options for acquiring data and displaying tooltip labels, and then generates a complete applet definition. This definition can include sample code that uses ASP or JSP to acquire data from a database, or it can just provide the exact parameters to reproduce your chart design, including the simulated data.

You can run the Chart Wizard online here


Applets and JSP Tags

For complex applications, KavaChart ProServe includes a JSP tag library that can make your applet definitions even more powerful. These chart tags will generate applet definitions or images, depending on your requirements. A chart tag looks like this:

	<chart:applet chartType="barApp" style="myStyle.txt" dataProviderId="myData" />
This tag will output the HTML applet definition for a KavaChart "barApp" applet, using the properties from the style sheet "myStyle.txt", and data from the DataProvider "myData".

By using a chart tag to generate your applet definition, you'll find it easier to implement a "Model2" architecture. The tag separates your applet's style properties from the overall page's presentation. This lets you apply a single style to multiple charts, and to change the style for all your charts from one location. It also makes the presentation logic of your pages simpler and easier to maintain.

Perhaps more important, you can use a common data source for your page's tables and charts, and build that data source (a DataProvider object) outside the page presentation layer. The person tasked with designing the page doesn't have to worry about data acquisition work, and vice-versa.

Chart tags also let you automate the process of localizing your applet output. If you create ResourceBundles for various locales, and identify the ResourceBundle basename in your chart tag, the outgoing applet definition will use properties from your ResourceBundles to populate things like chart titles, labels, or even colors and fonts.