Class com.java4less.rchart.ChartApplet (and RChartServlet)

Visit also our new on-line tutorial


 

Introduction

RChart is a Java[TM] charting package that can used as:

Charts can be created in two ways:

We provide examples of all types of charts (see examples.htm), we recommend you to use the examples for learning and use this document as reference. In the same way, we recommend you to use the example we provide as starting point for your charts, instead of starting from scracht.

 

Parameters

This section describes the parameters you can use in order to create a chart using the applet, the servlet or RChart Visual Builder. If you want to create the chart using our API please refer to the Javadoc[TM] files.

There are some parameters that have a special format:

You can define transparency in Fill and line styles using an additional parameter:

where <transparency> is a value between 0 (full transparent) and 1 (opaque). We recommend 0.5.

Note 1: transparency will only work with the Java Development Kit 1.2 or later (previous versions will ignore it).

 

The parameters of the chart are:

Title

Axis Label

Scale

if you don't specify the max and min values, Rchart will calculate the values automatically, using the maximum and minimum values provided in the data series. You can tune this behaviour with the following parameters:

 

Logarithmic Scales

the following additional parameters are needed for logarithmic scales:

Examples:

Note: logarithmic scales do not admit negative values.

Axis

RChart supports 3 axis, a horizontal axis (X) at the bottom of the chart, and 2 vertical axis to the left (Y) and the right (Y2) of the chart.

 

you can also let RChart calculate the value for the tick interval using the following parameters:

You can also use dates as labels for the ticks with the following parameters:

For example:

BIG_TICK_INTERVALX=2
TICK_INTERVALX=1
XAXIS_DATE_STEP=d
XAXIS_INITIAL_DATE=01-01-2001

will result in the following secuence of ticks/labels

- big tick, label "01-Jan-01"
- small tick, no label
- big tick, label "03-Jan-01"
- small tick, no label
- big tick, label "05-Jan-01"
- .....

 

Legend

DataSerie (SERIE_1,SERIE_2, ...)

PieChart

 

BarChart

LineChart

ScatterChart

A scatterchart is a normal linechart where you have suppressed the lines using:

SERIE_DRAW_LINE_1=N

for example, in order two plot 2 points at coordinates (x=1,y=1) and (x=3,Y=2) you would use

SERIE_DATA_1=1|2
SERIE_DATAX_1=1|3
SERIE_DRAW_LINE_1=N
SERIE_POINT_1=Y

 

RadarChart

MaxMin charts (OHLC and Candlestick)

Gauge

A gauge can contain up to 2 subgauges. In order to activate the subgauges you must set:

the last (or last two) value of the SERIE_DATA_1 parameter will be used plotter in the subgauge1 (and/or subgauge2).

paramterers of the gauge marked with (*) can be used to defined the subgauges by adding "1" or "2" to the "GAUGE" word in the parameter's name. For example: GAUGE1_BORDER,GAUGE1_BASE,GAUGE2_BORDER,GAUGE2_BASE and so on.

Gaugechart needs at least 1 scale, defined using the XAXIS* parameters. You can define a second scale for the gauge using the YAXIS* parameters. However, if you have defined subgauges, the YAXIS* scale will be used for subgauge1 and the Y2AXIS* scale parameters will be used for subgauge2.

 

Chart

Interactive features

This parameters can only be used in the interactive version.

Tips

If you want to display tips when the mouse is placed over a bar, point or item you can use these parameters:

< PARAM NAME="SERIE_TIPS_1" VALUE="tip for first bar|tip for second bar| tip for third bar">

you can use "\n" in order to create multiline tips.

Use the following parameters to change the aspect of the tips:

if you also want to display the current position (Y axis value) of the cursor you can use:

< PARAM NAME="CHART_SHOW_POSITION" VALUE="true">

 

 How to use 2 Y axis.

It is possible to draw more than one Y axis. The default Y axis is painted on the left side of the chart, however a second axis can be painted on the right side. In this case you must use the Y2* parameter. The SERIE_SECONDYAXIS parameter of the data serie spacifies which scale a data serie is using (scale of the first Y axis or scale of the second Y axis).

 

Loading the applet definition from a URL

You may also want to create the chart definition/data with a CGI, servlet or file in you server. RChart let's you:

normal applet's parameters look like this:

<PARAM NAME = "parameter name1" VALUE = "parameter value1">
<PARAM NAME = "parameter name2" VALUE = "parameter value2">
...

the definition file for RChart looks like this:

parameter name1=parameter value1
parameter name2=parameter value2
...

You can use all parameters explained in this document as applet parameters or within a definition file. In order to instruct RChart to read from a file you must include an applet parameter like this one:

<PARAM NAME = "DATAFILE" VALUE = "definition.txt">

See the files AppletData.html and AppletData2.html for an example.

JavaScript integration

You may also use javascript to change the chart displayed in the applet. The applet has the following methods:

For example, to change the line's style of the second serie of a chart you can use the following JavaScript function:

See file chart1.hml for an example.

 

JavaScript event OnClickRChart

RChart (only the applet) will trigger the OnClickRChart event when the user clicks on bar (barchart), point (linechart) or item (piechart). In order to activate this feature you must set the parameter

<PARAM NAME="CHART_JAVASCRIPT_EVENTS" VALUE="True">

This event will receive two parameters:

 

For example:

<SCRIPT>
function OnClickRChart(serieName, valuePosition) {

}
</SCRIPT>

 

Note that you must also include the word MAYSCRIPT in the applet parameters.

 

Update the chart with realtime data

If you want to update the chart (the applet) every X seconds with new data from your server you must configure the applet like this:

  1. Set the following parameter to set the update frecuency (the default is 2000= 2 seconds): REALTIME_MSECS=2000.
  2. If you want RChart to read new data (parameters) from a Url (for example, a servlet, ASP, Php program ...) set the parameter REALTIME_DATAFILE=http://myserver.com/updateData.asp

    where the program "updateData.asp" (can also be php, JSP ...) must return the parameters in the usual format (see Loading the applet definition from a URL). For example it might return this information: "SERIE_DATA_1= 12|34|46|56" in order to update the values for serie 1.

  3. RChart will also trigger a Javascript function called "onRChart()" if you set REALTIME_JS=true.

 

HTML Links

 

RChart (only the applet) will open an HTML when the user clicks on bar (barchart), point (linechart) or item (piechart). In order to activate this feature you must set the parameter: SERIE_LINKS_*.

For example, if your data serie 1 has 3 values, you can set the parameter like this:

< PARAM NAME="SERIE_LINKS_1" VALUE="value1.html|value2.html|value3.html">

Furthermore you can specify the frame where the HTML page will be displayed:

<PARAM NAME="CHART_LINKS_TARGET" VALUE="_new">

Valid values are: "_new" (new browser's window) , "_top" (current window) and "<frame name>" (if you ise frames).

Database (JDBC[TM] drivers) data population

 

If you use RChart as a servlet or in your Java or JSP application (not as applet) you can use Rchart's JDBC[TM features in order to read data from a database. First of all you must specify how to connect to the database using the following parameters:

when RChart is connected to your database you can put a SQL Select command in any RChart parameter. SQL Queries must have the "JDBC:" prefix. For example:

SERIE_DATA_1=JDBC:Select soldQty from SalesMonth Order by salesMonth DESC

note that rchart will only read the first field in the select statement, for this reason it is useless to use more than 1 field in the query. If the query returns more than 1 record, rchart will return the values as a list separated by | , just like parameters are expected.

Parameters

The SQL queries you define in RChart can also contain parameters. For example:

SERIE_DATA_1=JDBC:Select soldQty from SalesMonth where ProductId='[%product]' Order by salesMonth DESC

contains a parameter called "product". Before you try to create a chart containing this query you must provide a value for all parameters. This is done in the following way:

chart.setSQLParameter("product","1");

where the first parameter of setSQLParameter is the parameter name and the second is the value.

 

Servlets

RChartServlet will allow you to use RChart as Servlet without any Java programming. The servlet has the advantage that the Java classes must not be downloaded to the client's browser. This means your chart will be displayed faster. It has however the disadvantage that you need to have a web server able to execute servlets.

In the case of servlets, the charts are created in the server and the output in GIF, PNG or JPEG format is sent to the browser. This also means that you can use RChart to display charts in browser that do not support Java.

You can very easily use RChartServlet. The parameters are the same as those for the applet. You can send the parameters to the Servlet using the POST or GET methods. Furthermore there are some additional parameters:

Note:

Servlet installation on JSWDK 1.0

In order to run the servlet using JSWDK 1.0 you must do the following:

  1. copy the RChart classes to /jswdk-1.0.1/examples/Web-inf/servlets
  2. Add the following line to the file /jswdk-1.0.1/examples/Web-inf/servlets.properties :

    RChartServlet.code= RChartServlet

  3. Copy the data files (ChartData1.htm, ChartData2.htm .... ) to

    /jswdk-1.0.1/examples

  4. Start the server an test the servlet entering the following address and parameters in your browser:

    http://localhost:8080/examples/servlet/RChartServlet?DATAFILE=http://localhost:8080/examples/ChartData1.htm
    http://localhost:8080/examples/servlet/RChartServlet?DATAFILE=http://localhost:8080/examples/ChartData2.htm
    .. ...

  5. You can use the servlet with the POST or GET method.
  6. You can put additional parameters to modify the image format and the size:

    http://localhost:8080/examples/servlet/RChartServlet?DATAFILE=http://localhost:8080/examples/ChartData2.htm&FORMAT=gif&WIDTH=600&HEIGHT=600

 

Servlet installation on Tomcat 3.2.3

In order to run the servlet using Tomcat 3.2.3 you must follow these steps:

  1. create a new web application. directory "tomcat_home/webapps/rchart"
  2. modify the file "tomcat_home/conf/server.xml" and add the following line

    <Context path="/rchart"
    docBase="webapps/rchart"
    crossContext="false"
    debug="0"
    reloadable="true" >
    </Context>


    so that Tomcat can find your new application. For tomcat 4.0 you must use:

    <Context path="/rchart" docBase="rchart" debug="0" reloadable="true">

  3. copy Rchart classes to "webapps/rchart/web-inf/classes"
  4. copy RChart sample data files (ChartData1.htm, ChartData2.htm .... ) to "webapps/rchart/data"
  5. start Tomcat
  6. start your browser and enter the link:

    http://localhost:8080/rchart/servlet/RChartServlet?DATAFILE=http://localhost:8080/rchart/data/chartData1.htm

Note about the servlet on Linux: if texts are not displayed while running the servlet on Linux you should change default the font. RChart uses "Arial" as default font. This may be missing on Linux, for this reason texts could be missing. In this case you should use another font, for example: "TITLE_FONT=DIALOG|PLAIN|12"

Image maps (interactive servlets)

RChart comes with a servlet called RChartMapServlet that will create a HTML image map. This can be used together with RChartServlet in order to create interactive servlets that will display tooltips labels (SERIE_TIPS_* parameter) and html links (SERIE_LINKS_* parameter).

The following JSP code would produce a interactive chart image:

<jsp:include page="servlet/RChartMapServlet" flush="true">
<jsp:param name="DATAFILE" value="http://localhost:8080/rchart/data/dataFile.html"/>
</jsp:include>

<img src="http://localhost:8080/rchart/servlet/RChartServlet?DATAFILE=http://localhost:8080/rchart/data/dataFile.html" BORDER=0 ISMAP USEMAP="#CHARTMAP">

this JSP code uses boths servlets:

  1. RChartMapServlet calculates the HTML image map
  2. RChartServlet returns the image (gif, png ...)

see example chartServletMap.jsp included in the product.

 


Java, JSP, JDBC, JDK and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. J4L Components is independent of Sun Microsystems, Inc.