Chart |
||||||||||||||||||||||
|
OverviewThe Chart component is used to present data in a graphical form enabling the user to see trends, make comparisons, or view percentage of the whole. The component represents the entire chart area, including the chart graph and all pertinent elements (title, legend, background). The Chart component is based on the JFreeChart engine and exposes a friendly API with JSF-specific features and enhancements. Key Features
Quick StartLet's start creating a chart using a simple example. Then, we will improve it step-by-step. Step 1Add the <q:chart> tag to where you want to place the chart on the JSP page. To specify the chart type, use the view attribute. In the backing bean, specify the method that will provide data for the chart. <q:chart model="#{PopulationBean.population}" view="pie" titleText="Largest Cities of the European Union by Population" /> The data for the chart is provided in the backing bean as shown in the example below: public ChartModel getPopulation() { HashMap data = new HashMap(); data.put("London, United Kingdom", new Integer(7615000)); data.put("Berlin, Germany", new Integer(3396990)); data.put("Madrid, Spain", new Integer(3155359)); data.put("Rome, Italy", new Integer(2542003)); data.put("Paris, France", new Integer(2142800)); PlainSeriesImpl series = new PlainSeriesImpl(); series.setData(data); series.setId("Largest cities of the European Union"); PlainModelImpl model = new PlainModelImpl(); model.addSeries(series); return model; } As a result, you will see the following pie chart on your page: Step 2An alternative way to specify the same chart is by using the <q:pieChartView> tag instead of the view attribute of the <q:chart> tag. It gives you the ability to customize the chart type in many ways. For example, you can hide percentage labels or apply specific style attributes to the plot area. For more information about the chart areas and their styling, see the section Customizing Chart Elements. Now let's change the way the chart type is declared. Instead of the view attribute, we will use a specific <q:pieChartView> tag. Unless we provide any additional information, the output will be the same as in the previous example. However, in this case, you will be given more options to change the chart display. <q:chart model="#{PopulationBean.population}" titleText="#{PopulationBean.title}"> <q:pieChartView /> </q:chart> If necessary, you can turn off the visibility of slice labels and display this information as a tooltip for each slice. <q:chart model="#{PopulationBean.population}" titleText="#{PopulationBean.title}"> <q:pieChartView labelsVisible="false" tooltip="#{sector.key} - #{sector.value}" /> </q:chart> The sector variable is a request-scope variable which is provided by the engine and accesses each pie slice one after another when it is requested. This means that for different pie slices, the tooltip value will be calculated separately. In our example, the following tooltip values will be shown: If you want to specify a different function for calculating tooltip values, you can use the standard JSF expression language or a method specified in the backing bean. For example: public String getTooltip(){ PieSectorInfo sector = (PieSectorInfo) FacesUtil.getRequestMapValue("sector"); DecimalFormat format = new DecimalFormat("#,###"); return (String)sector.getKey() + " - " + format.format(sector.getValue()); } In this case, the tooltip values will be shown in the following formatted way: To know whether an attribute is calculated dynamically, like a tooltip, or its value is the same for all pie slices (i.e. labelsVisible is a common attribute for all the slices), see the section Pie Slices. Creating a ChartTo add the Chart component to a page, use the <q:chart> tag. There are two basic things that essentially affect the final chart visualization: a data model and a chart type. The data model is a dataset that is used for processing and displaying in the chart (see the section below). The Chart component provides three chart types for plotting data: pie, bar, line (see the section Specifying Chart Types). Specifying a Data ModelTo specify a data model for a chart, use the model attribute of the <q:chart> tag. This attribute should be specified as a value-binding expression that references a teamdev.jsf.component.chart.ChartModel instance. The data model represents a set of the teamdev.jsf.component.chart.Series instances and their series IDs. The series ID is used as the description of a single data series and also serves to sort series in the order they will be displayed in the legend. By default, they are shown as a legend in a chart. Each series represents a set of teamdev.jsf.component.chart.Tuple instances that is sorted by the key (a key is plotted in the key axis). Every tuple is a pair of key and value. Specifying Chart TypesThere are three chart types supported by the Chart component: pie, bar, and line charts. The easiest way to specify a chart type is through the view attribute of <q:chart> tag. In this case, the default properties that are available for a specific chart type will be used for rendering this chart, and you will not be able to customize it. The view attribute can take values of "pie", "line", "bar" for a corresponding chart type. If you want to have more fine-grained control over chart customization, use specific chart type tags: <q:pieChartView>, <q:lineChartView>, <q:barChartView>. There is no difference in specifying a model for each chart type. Note, however, that you can use a pie chart for only one data series. No matter whether you use the view attribute or specific chart type tags, the data will be treated in the same way. Line and bar charts can be vertically or horizontally oriented. To specify the orientation, set the orientation attribute to "vertical" (default) or "horizontal". The following example demonstrates the one of the ways to specify a chart type: <q:chart model="#{PopulationBean.population}" view="pie"/> The data for the chart is provided in the backing bean as shown in the example below: public ChartModel getPopulation() { HashMap data = new HashMap(); data.put("London, United Kingdom", new Integer(7615000)); data.put("Berlin, Germany", new Integer(3396990)); data.put("Madrid, Spain", new Integer(3155359)); data.put("Rome, Italy", new Integer(2542003)); data.put("Paris, France", new Integer(2142800)); PlainSeriesImpl series = new PlainSeriesImpl(); series.setData(data); series.setId("Largest cities of the European Union"); PlainModelImpl model = new PlainModelImpl(); model.addSeries(series); return model; } Request-Scope VariablesWhen customizing the Chart component, you can use request-scope variables that reference a particular slice or data point. There are two such variables:
The point variable has the following properties:
The sector variable has the following properties:
Moreover, the sector.series and point.series objects have the following properties:
Customizing Chart ElementsThe major output of the Chart component is a graph which is rendered on the server side and then is embedded in the page within a standard HTML <img> tag. The graph represents an entire chart area which includes the following:
The plot area is an area bound by the chart axes with all data series. A pie chart doesn't have axes. Chart AreasEach chart area can be styled separately, but if no explicitly defined style for a certain area is provided, its parent style will be used. A standard CSS-like style definition is used for setting a visual property for the chart elements. Also, the CSS principle is applied, i.e. if you specify style="background: red;" for the chart area and do not use any style definition for the plot area which is nested in the chart area, style="background: red;" will be used for the plot area too. The same principle applies to the standard HTML document. If you provide a set of nested <div> elements and style properties are provided for an outer <div> , an inner <div> element will be rendered following the rules of the outer <div>. So, for a better understanding of the chart area styling, you can interpret these areas as a set of nested HTML block elements like <div> or <span>. Note The following CSS properties are supported:
If you use other CSS properties, no error will occur but they will take no effect. By default, the Chart component has the width and height equal 400 px. To change them, use the width and height attributes. You can also define these attributes as value-binding expressions that reference int values. Chart AxesYou can specify which axes are shown on the chart with the showAxes attribute of the <q:lineChartView> and <q:barChartView> tags. The pieChartView component cannot have axes. The showAxes attribute can take the following values:
If you specify axes with the showAxes attribute, the axes will have default look-and-feel. If you need more customization options, you can use the following tags:
These tags should be nested within a particular chart type component: lineChartView and barChartView. You can specify both axes with the same parameters or customize each axis separately. The domain attribute lets you specify to which axes the values of the attributes specified in the axes tags are actually applied. The attribute can take the following values:
For the <q:numberAxis> and <q:dateAxis> tags, you can specify the minimum and maximum scale values on the axis by using the lowerBound and upperBound attributes. These attributes should be used if you need that axes are displayed in the same way, independent of data. In the following example, you can see NumberAxis and CategoryAxis specified and a style applied to both axes: <q:chart width="350" height="300" model="#{AverageTemp}"> <q:barChartView binding="#{ChartDemo.barView}"> <q:categoryAxis domain="key" position="up_45"/> <q:numberAxis domain="value" lowerBound="-30" upperBound="45"/> <q:chartAxis domain="all" style="color:#4747B3"/> </q:barChartView> <q:chartTitle text="Average Temperature During the Year"/> </q:chart> Pie SlicesOne of the slices in a pie chart can be pulled out on a mouse click or according to some condition. The <q:pieSectorProperties> tag is used to apply a style to pie slices and specify whether or not a pie slice is pulled out upon a mouse click. This tag should be placed inside the pieChartView component. The condition according to which a style is applied to pie sector and pie sector is pulled out is specified in the condition attribute. This attribute should be specified as value-binding expression. When you define the condition attribute, you can use request-scope variables that are described in the appropriate section. A pie slice that meets the condition specified in the condition attribute can be pulled out. You can specify whether or not a pie sector that meets the condition is pulled out by using the pulled attribute. It defines the distance at which this sector is moved away from the center of the pie. To indicate how far from the center a pie slice should be pulled out, set the pulled attribute to a float-pointing value from "0" to "1", as a percentage of the radius. Setting a value greater than 1 will move the pie slice outside the chart graph. The following example shows the usage of the <q:pieSectorProperties> tag: <q:chart width="500" height="300" model="#{ChartView.pieChartModel}"> <q:pieChartView binding="#{ChartView.pieView}"> <q:pieSectorProperties condition="#{ChartView.selectedSector || ChartView.defaultSector}" pulled="0.1f"> </q:pieSectorProperties> </q:pieChartView> <q:chartTitle text="Total Income"/> </q:chart> LinesLines in a line chart can be customized by declaring the <q:lineProperties> tag. This tag should be defined as a child for <q:lineChartView> tag. The condition according to which the properties from the <q:lineProperties> tag are applied can be specified by using the condition attribute. This attribute should be specified as a value-binding expression. When you define the condition attribute, you can use request-scope variables that are described in the appropriate section. The data series that meets the condition can be hidden on a chart. You can specify whether or not to show the series using the hideSeries boolean attribute. By default, it is "false". You can also specify whether or not to show the legend for the lines of the data series that meet the condition by using the showInLegend attribute. By default, it is set to "true". The shapesVisible attribute specifies whether or not data markers on the lines of data series that meets the condition are visible. By default, it is set to "true". You can also specify whether or not to show data markers on the line chart for all visible data series by using the shapesVisible attribute. By default, it is set to "true". The following example shows the usage of the <q:lineProperties> tag: <q:chart width="500" height="400" model="#{WeatherData}"> <q:lineChartView shapesVisible="true" binding="#{TestView.lineView}"> <q:lineProperties condition="#{point.series.key=='Ukraine'}" shapesVisible="true" showInLegend="true" style="border:none;"> </q:lineProperties> </q:lineChartView> <q:chartTitle text="Temperature Distribution During a Year for #{TestView.pieInfo.key}"/> </q:chart> GridlinesGridlines for a line and bar chart can be customized with the <q:chartGridLines> tag which you should place inside <q:lineChartView> or <q:barChartView>. To specify whether the gridlines are visible or not, use the visible attribute. By default, it is "true". You can customize both vertical and horizontal gridlines at the same time or separately. The domain attribute specifies to which gridlines a style is applied. This attribute can take the "key", "value" and "both" values. By default, the domain attribute is set to "both". A style for the gridlines can be applied by setting the style attribute of the <q:gridLines> tag. Data SeriesBy default, data series use default colors of the JFreeChart component. You can apply custom colors to the data series with the colors attribute, by specifying a comma-separated list of colors. The colors attribute can be specified for all chart types supported by the Chart component: <q:pieChartView>, <q:lineChartView>, and <q:barChartView>. For a line and bar chart, colors will be applied in the order the data series are defined in the backing bean. For a pie chart, colors are applied clockwise. Note The following example shows a pie chart with custom colors for each slice: <q:chart model="#{PopulationBean.population}" titleText="#{PopulationBean.title}"> <q:pieChartView colors="#3E8EB3, #5ACAFF, #B3773E, #FFC559" /> </q:chart> LabelsTo identify data plotted in the chart, the Chart component provides the following labels:
You can specify whether or not to show labels with the labelsVisible boolean attribute of a corresponding chart type: <q:lineChartView>, <q:barChartView>, or <q:pieChartView>. By default, data labels are hidden. To apply a style to data labels, nest the <q:chartLabels> tag within a required chart type. To specify whether to show axis titles, use the labelVisible attribute of any axis type: <q:chartAxis>, <q:numberAxis>, <q:dateAxis>, <q:categoryAxis>. By default, it is set to "true". Text for the axis titles can be set with the keyAxisLabel and valueAxisLabel attributes of the <q:lineChartView> or <q:barChartView> tags. For more information about the axes, read the section Chart Axes. Tick marks on the axes can be specified with the ticksVisible and ticksLabelsVisible boolean attributes of a specific axis type. The ticksVisible attribute defines whether to show ticks on the axis, and the ticksLabelsVisible attribute is responsible for displaying tick-mark labels. By default, both attributes are set to "true". A style for the ticks can be specified with the <q:chartAxisTicks> tag that should be defined as a child of <q:barChartView> and <q:lineChartView> chart types. If your chart has a time-scale axis, you can specify the date format of tick-mark labels by using the dateFormat attribute of the <q:dateAxis> tag. The dateFormat attribute should be bound to an java.text.DateFormat instance. The following example shows all the chart labels specified: <q:chart model="#{PopulationBean.population}" titleText="#{PopulationBean.title}"> <q:lineChartView labelsVisible="true" keyAxisLabel="Cities" valueAxisLabel="Population"> <q:chartLabels style="color:gray; font-size: 8pt;"/> <q:chartAxis labelsVisible="true" ticksVisible="true" ticksLabelsVisible="true"/> </q:lineChartView> </q:chart> You can change the way axis labels are aligned and rotated by using the position attribute of the <q:categoryAxis> tag. The attribute can take the following values:
LegendYou can specify whether or not to show the chart legend by setting the legendVisible attribute of the Chart component. By default, it is set to "true". To apply a style to the legend and specify its position, use the <q:chartLegend> tag. The legend position relative to the chart is specified by setting the position attribute to one of the following values: top, bottom (default), left, and right. Chart TitleThe chart title is specified by setting the text in the title attribute of the Chart component. If you want to customize the chart title, use the text attribute of the <q:chartTitle> tag. There are also the tooltip, url, action, and actionListener attributes which you can use for making the chart title respond to user actions (for more details, see the section Chart ToolTips). Chart ToolTipsCertain chart elements can respond to user actions. For example, when the mouse pointer is placed over a specific chart element, a tooltip can appear. To specify text for the tooltip, use the tooltip attribute. It can be also specified as a value-binding expression. The user can be redirected after clicking on a specific chart element. To specify the destination URL, use the url attribute. The action and actionListener attributes are similar to the corresponding attributes of the HTMLCommandButton component, i.e. are specified as a method-binding. Almost all chart elements have the tooltip, url, action, actionListener attributes. You can specify them for the <q:pieChartView>, <q:lineChartView>, <q:barChartView>, <q:chartTitle> tags. The following example shows the usage of all these attributes: <q:chart model="#{PopulationBean.population}" titleText="#{PopulationBean.title}"> <q:pieChartView tooltip="#{sector.key}" action="#{TestView.onSectorClickAction}" actionListener="#{TestView.onSectorClickActionListener}" url="detailInfo.jsp"/> </q:chart> Specifying TransparencyYou can specify transparency for the plot area or pie graph with the foregroundAlpha attribute of the <q:lineChartView> , <q:barChartView> or <q:pieChartView> tag. Transparency should be specified as a percentage, from "0" to "1". The default value is "1". Displaying a Message for Empty DataIf there is no data to be plotted in a chart, the Chart component is not displayed. You can specify message text to be displayed in place of the chart using the text attribute of the <q:chartNoDataMessage> tag. To apply a style to the text, use the style attribute. The <q:chartNoDataMessage> tag should be placed inside any chart type: pieChartView, barChartView, lineChartView. Client-side EventsYou can specify onclick, onmouseover and onmouseout client-side events for the plot areas for each chart type:<q:pieChartView>, <q:lineChartView> and <q:barChartView>. |
|||||||||||||||||||||
© 2007 TeamDev Ltd. | ![]() |