ZK Developer's Guide/ZUL Components/Chart and Report/Chart

This documentation is for an older version of ZK. For the latest one, please click here.

Components: chart

A chart is used to show a set of data as a graph, which helps users to digest data quickly.

In order to use a chart component we only need to prepare a suitable data model and give it to the chart. The following is an example of pie chart.

<zk>
	<chart id="mychart" type="pie" width="400" height="200" threeD="true" fgAlpha="128">
		<zscript><![CDATA[
			PieModel model = new SimplePieModel();
			model.setValue("C/C++", new Double(17.5));
			model.setValue("PHP", new Double(32.5));
			model.setValue("Java", new Double(43.2));
			model.setValue("VB", new Double(10.0));
			mychart.setModel(model);
		]]>
		</zscript>
	</chart>
</zk>

Different types of chart are used to demonstrate different kind of data thus, a chart needs to be provided a suitable data model. To use a pie chart, developers must provide use a PieModel as their data model while bar chart, line chart, area chart, and waterfall chart needs CategoryModel and XYModel.

• Details of Charts

Live Data

The above example is a little misleading. In fact, developers don't have to prepare real data before feeding it into a chart as chart components support live data mechanism. With live data, developers are able to separate the data from the view enabling the developer to add, update and remove data from the data model with the framework taking care of redrawing the chart. For advanced implementations, developers can even provide their own chart model by implementing the ChartModel interface.

Drill Down (The onClick Event)

Sometimes a user wants more details on a section of a chart, such as a piece of the pie chart or a bar of the bar chart. This functionality is provided as each part of the of the chart is split up into area components allowing the users to click on them. When clicked they will fire an onClick event. Developers can then extrapolate the information from the area component and display it.

Each area component’s componentScope contains information that developers can use.

name	description
entity	Entity type of the area. (e.g. TITLE, DATA, CATEGORY, LEGEND)
series	Series name of the associated data (CategoryModel, XYModel, or HiLoModel).
category	Category name of the associated data (PieModel or CategoryModel).
URL	A string URL which can be used to drill down to a legacy page.
value	Numeric value of the associated data ( PieModel or CategoryModel).
x	The x value of the associated data (XYModel).
y	The y value of the associated data (XYModel).
date	The date value of the associated data (HiLoModel).
open	The open value of the associated data (HiLoModel).
high	The high value of the associated data (HiLoModel).
low	The ow value of the associated data (HiLoModel).
close	The close value of the associated data (HiLoModel).
volume	The volume value of the associated data (HiLoModel).

In the following example, we provide an onClick event listener for the chart. It locates the associated area component and shows the area category.

<zk>
	<chart id="mychart" type="pie" width="400" height="250">
		<attribute name="onClick">
		alert(self.getFellow(event.getArea()).getAttribute("category"));
		</attribute>
		
		<zscript><![CDATA[
			PieModel model = new SimplePieModel();
			model.setValue("C/C++", new Double(17.5));
			model.setValue("PHP", new Double(32.5));
			model.setValue("Java", new Double(43.2));
			model.setValue("VB", new Double(10.0));
			mychart.setModel(model);
		]]>
		</zscript>
	</chart>
</zk>

Manipulate Areas

Chart components also provide an area renderer meaning developers can manipulate the attributes of a chart’s area components.

There are only two steps needed to use the area renderer.

1. Implement the ChartAreaListener interface for manipulating area components. e.g. Change the tooltiptext of the area.
2. Set the listener object or listener class name to the chart's areaListener attribute.

Using this method, developers have a change to change the area component’s attributes and insert more information in the componentScope for use within the application.