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.
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.
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.
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.
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:
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>
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.
You can also modify your applet using JavaScript. This allows you to make updates to your applet when events are triggered by JavaScript running at the client. See
this link 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.
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:
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:
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.
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:
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:
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.
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:
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.
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.
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.
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
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:
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.
for more information, and see the demos for sample code.
Data Sources
Inline Data
<APPLET CODE=com.ve.kavachart.applet.barApp ARCHIVE="barApp.jar" WIDTH=300 HEIGHT=300>
<PARAM NAME="dataset0yValues" value="123,432,234">
</APPLET>
<APPLET CODE=com.ve.kavachart.applet.barApp ARCHIVE="barApp.jar" WIDTH=300 HEIGHT=300>
<PARAM NAME="dataset0yValues" value="<?=dat?>">
</APPLET>
URL Data
<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>
<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>
DataProvider Data
<param name="dataProvider" value="MyDataProvider">
Using
the Chart Wizard
Applets and JSP Tags
<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".