KavaChart Custom Tag Library Documentation
Tutorial Demos Other Downloads Purchase Page Resources Contact VE

For a quick overview, see the Chart Tag Tutorial page.

KavaChart's Custom Tag Library consists of a small set of easy to use tags that hide the complexity of applying data and style information to server-generated charts. These tags will help you effectively create persistent data stores and style information to make chart image generation as efficient as possible.

In addition, JSPs that contain these chart tags will be more intuitive and easier to work with than extensive scriplet or servlet references for non-programmers and programmers alike. These tags will make your pages more portable and flexible and will promote re-use of your existing data sources.

This library is comprised of 3 chart generation tags and a few utility tags, described below.

Include Statement

Start by adding this line to your JSP: 

<%@ taglib uri="http://www.ve.com/kavachart-taglib" prefix="chart" %>

This assumes that your web.xml file has been configured with the same URI, and that the web.xml file also references the kavachart-taglib.tld taglib descriptor.

Cached Chart Tag

Usage: 

<chart:cached attr1="value1" attr2="value2" .../>

This chart tag generates an encoded chart image and writes it to your server's filesystem. It returns a reference to that image, along with (optionally) an image map used to create tooltip labels.

All this tag's attributes are available for runtime expressions. The tag also has a number of useful inner tags described later in this document.

Streamed Chart Tag

Usage: 

<chart:streamed attr1="value1" attr2="value2" .../>

This chart tag generates an encoded chart image and saves it to your application memory. The generated page includes an "IMG" tag that points to a servlet used to retrieve the image and delete it from memory. This tag will also (optionally) create an image map used to create tooltip labels to accompany that image.

All this tag's attributes are available for runtime expressions. The tag also has a number of useful inner tags described later in this document.

Balanced Chart Tag

Usage: 

<chart:balanced attr1="value1" attr2="value2" .../>

This chart tag can be used for load balancing between multiple servers. By default this tag will encode any chart options and pass them to com.ve.kavachart.servlet.LoadBalancedChartServlet where the actual chart is created. This is useful in a mirrored resource environment as you can send a request for LoadBalancedChartServlet to any of the mirrored servers for chart generation and image encoding (at the very least the mirrored servers must have access to any property files or image files used in the encoding process). There is also the additional option of specifying a dedicated server to handle all chart creation. The generated page includes an "IMG" tag that points to LoadBalancedChartServlet using the default servletContext or optionally a user-specified context (for specifying a particular server). This tag will also (optionally) create an image map used to create tooltip labels to accompany that image.

All this tag's attributes are available for runtime expressions. The tag also has a number of useful inner tags described later in this document.

Applet Chart Tag

Usage: 

<chart:applet attr1="value1" attr2="value2" .../>

This chart tag generates an applet definition consistent with the server-side imaging processes. This definition includes data defined by your DataProvider classes, localization from ResourceBundles, and any other modifications performed by the other Chart tags.

While your HTML coders may be familiar with applet definitions, this tag provides you with the opportunity to separate style logic (properties stylesheets) from your data in a simple tag. Chart data and properties are automatically populated without cluttering the logic of your JSP source code.

Table Tag

Usage: 

<chart:table attr1="value1" attr2="value2" .../>

This tag generates an HTML table using chart styles and data sources. This tag allows you to re-use a chart DataProvider class, chart localization information, and chart property information in a concise, easyto-use tag.

HTML table styles are defined using CSS stylesheet classes defined in a conventional manner, and data, formatting, and labelling information is derived from chart properties.

Chart Tag Attributes

dataProviderID: A string value that identifies this chart's DataProvider attribute. A DataProvider class implements the KavaChart interface com.ve.kavachart.utility.DataProvider, which supplies an Enumeration of javachart.chart.Dataset classes. This class is placed into your page, session, or application context as a named attribute. The dataProviderID identifies the name used to store that DataProvider class.

A DataProvider is typically implemented as a part of your overall data retrieval process, and can be placed into your page context at any point in the page construction code. A DataProvider can also be a JavaBean.

Code Example: 

DataProvider myData = new MyDataSource();
pageContext.setAttribute("dataID", myData);

Tag Example: 

<chart:sreamed dataProviderID="dataID" />

style: A string value that defines this chart's property sheet. A property sheet is a file that contains lines in form property=value. These files can be generated easily with the KavaChart ChartWizard. Because a property file is a simple ASCII file, you can also edit it with a text editor, using the standard KavaChart server bean property strings.

Example: 

<chart:streamed style="WEB-INF/myChart.properties" />

reloadStyle: "true" or "false". By default, the chart's property sheet is loaded into application memory for efficient re-use. If you want changes to the property sheet to take effect without restarting your server, set "reloadStyle" to "true".

Example: 

<chart:cached style="WEB-INF/myChart.properties" reloadStyle="true" />

chartType: A string value that describes the KavaChart server chart bean you want to use. For example, if you specify "lineApp", the tag will use com.ve.kavachart.servlet.lineApp to create the chart. ChartBean classes that aren't part of the com.ve.kavachart.servlet package must use a fully qualified name, such as "kcfinance.ChartBean".

Example: 

<chart:cached chartType="pieApp" />

useLinkMap: "true" or "false". By default, this attribute is "true" and the tag creates a link map with "ALT" text to describe each point. While this is a nice feature for simple charts, you may want to disable it for charts with a large number of points.

Example: 

<chart:cached chartType="dateLineApp" dataProviderID="myData" useLinkMap="false" />

resourceBundleID: An attribute ID for this tag's resource bundle. Resource bundles are typically used to localize chart attributes. This attributes lets you define a resource bundle at any point in the page generation process and use it to redefine a chart's labels, titles, etc. You can even redefine the chart's style based on resource bundle information.

Example: 

<chart:streamed chartType="pieApp" resourceBundleID="myResources" />

resourceBundleBaseName: A basename for a resource bundle used by this chart. If you don't use a common resource bundle for all your page's attributes, you can still localize the chart automatically using resource bundles.

Typically a resource bundle is a set of properties files consisting of property=value statements. This file must be located within your application's CLASSPATH, and must be named with a resourceBundleBaseName.properties. Localized resource bundles use the convention resourceBundleBaseName_en.properties, where "en" is replaced by the specific locale ID represented by that bundle.

Non-western strings are generally more efficient if placed into ResourceBundle classes.

Resource bundle properties files are loaded and unloaded by the ClassLoader, so they are cached efficiently in a platform-dependent way. You may need to restart your server to see changes to your resource bundles take effect.

If your target languages includes non-Western languages, you may need to create ResourceBundle classes to get the correct character information. Some languages require specific character sets. In this case, you must also make sure your resource bundle specifies the correct fonts for the characters you're using.

Example: 

<chart:cached chartType="pieApp" resourceBundleBaseName="chartResources" />

cacheDirectory: (cached chart tag only) Because the cached chart tag must write an image file to your server's filesystem, it's important to specify where on the filesystem you wish to save the image.

The location specified here is relative to your application context, and defaults to /images/KavaChartImages.

Since the tag will return an <IMG> reference to this file, files in the cacheDirectory must be visible from a web browser.

Example: 

<chart:cached chartType="pieApp" cacheDirectory="/images/charts" />

codebase: (applet chart tag only) Applets use a CODEBASE attribute to determine security policies and class file locations. This optional attribute defaults to your application's root directory.

You can set this value to point to another directory, or even another server (which would contain your applet's jar file, image resources, etc.). Since the chart's data is embedded into the parameters, you can easily host the applet from another server.

Example: 

<chart:applet chartType="columnApp" codebase="/jarfiles/charts" />

archive: (applet chart tag only) Applets use an ARCHIVE attribute to point to a jar archive containing the applet's code resources. This attribute defaults to KavaChart's applet naming convention (e.g. com.ve.kavachart.applet.lineApp is contained in a jar archive named applet.lineApp.jar), but you can override this in the case you have a customized applet.

Example: 

<chart:applet chartType="custom.FancyChart" archive="FancyChart.jar" />

streamServletName: (streamed chart tag only) By default the streamed chart tag points to a servlet named /servlet/com.ve.kavachart.servlet.ChartStream to retrieve its image bytes. You may wish to obscure this by changing the servlet-mapping attribute in your web.xml file, and by applying this attribute to your streamed chart tag.

Example: 

<chart:streamed streamServletName="charts" />

imageType: (balanced chart tag only) This attribute functions like the imageType server-side property and is a required attribute for the balanced tag.

Example: 

<chart:balanced imageType="swf" />

width: (balanced chart tag only) This attribute functions like the width server-side property.

Example: 

<chart:balanced width="400" />

height: (balanced chart tag only) This attribute functions like the height server-side property.

Example: 

<chart:balanced height="300" />

servletContext: (balanced chart tag only) Use this attribute to specify a specific servlet context path for load balancing. The actual request to generate the chart will be sent to this path.

By defining this tag, you can either send your chart requests to a mirrored cluster of servers, or to a server that has been optimized for chart generation.

Example: 

<chart:balanced servletContext="http://localhost:9019/" />

Data Web Service Inner Tag

Usage: 

<chart:datawebservice serviceURL="http://www.kavachart.com/dat.xml" .../>

An inner tag that reads data from a web service providing data conforming to the DTD located at http://www.ve.com/kavachart/KavaChartDataProvider.dtd. A data sample is located at http://www.kavachart.com/dat.xml.

Data Filter Inner Tag

Usage: 

<chart:datafilter startDataset="0" endDataset="7" .../>

This inner tag constrains the data provided by a referenced DataProvider class. All attributes are settable by runtime expressions, and all attributes are optional.

Data Arithmetic Inner Tag

Usage: 

<chart:dataarithmetic multiplier="0.001" ...>

This inner tag manipulates the data provided by a referenced DataProvider class, scaling each value by a multiplier, and then adding to each value as specified. All attributes are settable by runtime expressions, and all attributes are optional.

Data Transposer Inner Tag

Usage: 

<chart:datatransposer .../>

This inner tag changes row-wise observations into column-wise observations, or vice-versa. It's typically used to regroup bars differently. For example, a default bar (column) chart with multiple datasets creates clusters of bars; the first cluster is each dataset's first observation, the second cluster is each dataset's second observation, and so on.

The datatransposer tag would alter that data so that the first cluster consists of all the first dataset's observations, the second cluster consists of the second dataset's observations, and so on.

Data Accumulator Inner Tag

Usage: 

<chart:dataaccumulator dataProviderID="source1,source2".../>

An inner tag to combine several data sources into a single chart. This tag is particularly useful when a page needs to display data in a variety of charts. For example, a page may use one data source for each of two pie charts, and then combine the data sources into a single bar chart.

Data Histogram Inner Tag

Usage: 

<chart:datahistogram .../>

An inner tag to generate histogram metadata from incoming data sources. Data is automatically arranged into a reasonable number of "bins", with ranges used to label the bins. This tag is typically used with a column or bar chart.

Data Percent Change Inner Tag

Usage: 

<chart:datapercentchange .../>

An inner tag to generate metadata that describes the percentage change of incoming data source Y values. This type of chart is typically used with time-series data to understand how values have changed over time. It is common in financial services to use this technique to compare two stocks, for example.

Data Regression Feed Inner Tag

Usage: 

<chart:dataregressionfeed .../>

Linear regression is typically used to understand correlation between two variables. In practice, these variables often exist as the dependent (Y) values of two different datasets. This tag uses Y values from two datasets to create X and Y metadata for an output dataset. The output data is then directed to a regressionApp chart or scatter plot to visualize the correlation between these variables.

Data Sorter Inner Tag

Usage: 

<chart:datasorter .../>

A tag to sort incoming data sources. Combined with a column chart, this can turn data into a Pareto analysis chart. You can also use this chart to visually understand other aspects of incoming data sources.

Datasimulation Inner Tag

Usage: 

<chart:datasimulation numDatasets="2" numObservations="25" />

This inner tag provides datasets with random numbers to permit your page designers to proceed with page development in the absence of a working DataProvider class.

Timedatasimulation Inner Tag

Usage: 

<chart:timedatasimulation numDatasets="2" numObservations="25" />

This inner tag provides datasets with random numbers to permit your page designers to proceed with page development in the absence of a working DataProvider class.

The X values in this DataProvider are timestamps, starting with now, and increasing by a specified number of days for each observation. The default is one day per point.

This simulator provides extended data suitable for charts that use CandlestickDatum, such as candelstick charts, hi-lo-open charts, and so on.

Param Inner Tag

Usage: 

<chart:param name="titleString" value="hello, world" />

This inner tag overrides properties set in the style properties file and localized resource bundles. It provides a behavior similar to conventional applet param tags, but can be set with JSP runtime expressions. This inner tag can be set multiple times.

Locale Inner Tag

Usage: 

<chart:locale name="localeString" value="BE_fr" />

This inner tag overrides locale settings from your page or application context. It's useful for testing resource bundles in an ad-hoc way.

com.ve.kavachart.utility.DataProvider Interface

Implement this interface in any class to create a chart DataProvider. 

public Interface com.ve.kavachart.utility.DataProvider {
	/*
	 ** Returns an Enumeration of Dataset classes.
	 */
	public Enumeration getDatasets();
	/*
	 ** Returns a String that uniquely identifies this data.
	 ** Needed to make chart image caching work properly.  Otherwise unnecessary.
	 */
	public String getUniqueIdentifier();
}

A DataProvider is a class that supplies a chart tag with an Enumeration of Dataset classes. A new instance of this class should be created when your Datasets change to avoid thread contention issues. Generally this means a new DataProvider for each page, although DataProviders that don't change values very often (as in some of the weather examples) may be safely re-used.

Consult the javachart.chart.Dataset documentation for more information on constructing Dataset classes. Convenient constructor signatures are available for most situations.

web.xml, kavachart-taglib.tld

To add KavaChart's Tag Library to your own application:

  1. Add "kcServlet.jar" to your CLASSPATH (usually WEB-INF/lib)
  2. Integrate WEB-INF/web.xml into your own. In particular, you'll need the servlet definition and mapping for cached charts, and you'll need the taglib reference.
  3. Add kavachart-taglib.tld (the taglib descriptor) to the location specified in your web.xml file.

Consult the javachart.chart.Dataset documentation for more information on constructing Dataset classes. Convenient constructor signatures are available for most situations.

Tutorial Demos Other Downloads Purchase Page Resources Contact VE