chart component docs

Component_Reference/src/main/docbook/en-US/Component_Reference-docinfo.xml

@@ -1,11 +1,11 @@
-<subtitle>A reference guide to the components of the RichFaces 4 framework</subtitle>
+<subtitle>A reference guide to the components of the RichFaces 5 framework</subtitle>
 <productname class="trade">RichFaces</productname>
 <productnumber>5.0.0-SNAPSHOT</productnumber>
 <edition>1</edition>
 <pubsnumber>1</pubsnumber>
 <abstract>
    <para>
-			This book details each component in the RichFaces 4 framework, including examples of their use in applications.
+			This book details each component in the RichFaces 5 framework, including examples of their use in applications.
 		</para>
 </abstract>
 <corpauthor>

Component_Reference/src/main/docbook/en-US/Component_Reference.asciidoc

@@ -6556,6 +6556,155 @@ Read this chapter for details on components that display messages and other feed
 
 [[sect-Component_Reference-Output_and_messages-message]]
 
+=== [sgmltag]+<r:chart>+
+
+The [sgmltag]+<r:chart>+ component allows the user to plot data and to create line, bar or pie charts. It uses up to five children tags [sgmltag]+<r:series>+, [sgmltag]+<r:legend>+, [sgmltag]+<r:xaxis>+, [sgmltag]+<r:yaxis>+ and [sgmltag]+<r:point>+. Each child tag customizes a particular aspect of the chart. All are optional except at least one [sgmltag]+<r:series>+ tag is required.
+
+Additionally the [sgml]+<r:chart>+ component allows one to handle events using either a client-side JavaScript or using server-side listeners.
+
+[[figu-Component_Reference-chart-chart_component]]
+
+.r:chart component
+image::figu-Component_Reference-chart-chart_component.png[]
+
+
+[[sect-Component_Reference-chart-Basic_usage]]
+
+==== Basic usage
+
+The [sgmltag]+<r:chart>+ tag and its optional children tags generate and customize the chart. The chart type is selected by a [sgmltag]+<r:series>+ attribute.  The only requirements for use of the [sgmltag]+<r:chart>+ are selection of the chart type and to pass at least one series of data - explained below.
+
+
+[[sect-Component_Reference-chart-Data_input]]
+
+==== Data input
+
+The [sgmltag]+<r:chart>+ component accepts data by two means - by facelet iteration or by creating data model object.
+
+===== Facelet iteration
+
+Use [sgmltag]+<r:repeat>+ and a collection of objects inside the [sgmltag]+<r:series>+ tag and specify what you want to be plotted on the x and y axis using [sgmltag]+<r:point>+ tag. The [sgmltag]+<r:repeat>+ approach can also be used at the [sgmltag]+<r:series>+ level.
+
+[[exam-Component_Reference-chart_facelet_iteration_example]]
+
+.r:chart facelet iteration example
+====
+
+[source, XML]
+----
+<r:chart id="barChart" title="Countries by vehicles per capita">
+   <r:series type="bar">
+   	<r:repeat value="#{bean.records}" var="record">
+          <r:point x="#{record.country}" y="#{record.count}"/>
+   	</r:repeat>  
+   </r:series>
+   <r:yaxis label="Motor vehicles per 1000 people"/>
+</r:chart>
+
+----
+
+====
+
+===== Create a DataModel object
+When facelet iteration is used the ChartDataModel object is created by the ChartRenderer. An alternative to this is to create a ChratDataModel yourself and pass it using [sgmltag]+<r:series>+ data attribute. To do this, create an instance one of the child classes of ChartDataModel - NumberChartDataModel, StringChartDataModel or DateChartDataModel (not yet fully supported). Select the class according to the data type used on the x-axis. Add values to the model using the put method and pass it to the [sgmltag]+<r:series>+ tag using the data attribute.
+
+[[exam-Component_Reference-chart_datamodel_object_example]]
+
+.r:chart DataModel object example
+====
+
+[source, XML]
+----
+<r:chart id="barChart" title="Countries by vehicles per capita">
+   <r:series type="bar" data="#{bean.cars}"/>
+   <r:yaxis label="Motor vehicles per 1000 people"/>
+</r:chart>
+
+----
+
+[source,Java]
+----
+cars = new StringChartDataModel(ChartDataModel.ChartType.bar);
+cars.put("San Marino", 1263);
+cars.put("United States", 797);
+...
+
+----
+
+====
+
+
+If there is a model passed using the [sgmltag]+<r:series>+ data attribute, any nested [sgmltag]+<r:point>+ tags are ignored. If the data attribute is not used, then nested [sgmltag]+<r:point>+ tags are expected. 
+
+[[sect-Component_Reference-chart-Look_customization]]
+
+==== Chart look customization
+
+The chart configuration is split into multiple tags provide a more clear facelet API. To configure axes, their min/max values, and label use [sgmltag]+<r:xaxis>+ or [sgmltag]+<r:yaxis>+ tag. The [sgmltag]+<r:legend>+ allows one to set up the position of the legend and the order of the labels within it.
+
+To adjust the chart component size you can use CSS class .chart-container, to customize title use .chart-title the placeholder. The chart itself is placed in the div with the CSS class +.chart+. 
+
+[[sect-Component_Reference-chart-Interactivity_options]]
+
+==== Interactivity options
+
+The [sgmltag]+<r:chart>+ component does not only create static charts. 
+
+* It allows the user to zoom line charts when the [sgmltag]+<r:chart>+ attribute zoom is set true. To reset zoom you can use the JavaScript API.
+* You can also add functions to handle events fired by components. Event handlers are set up using proper [sgmltag]+<r:chart>+ attributes. They handle events fired by any series. If you want to handle an event only fired by a particular series, set up handlers using the [sgmltag]+<r:series>+ attributes.
+
+[[sect-Component_Reference-chart-chart_server-side_events]]
+
+==== [sgmltag]+<r:chart>+ server-side events
+
+* The [varname]+PlotClickEvent+ is fired when the user clicks a point in the chart. To set a listner use the [varname]+plotClickListener+ attribute.
+
+[[sect-Component_Reference-chart-chart_client-side_events]]
+
+==== [sgmltag]+<r:chart>+ client-side events
+
+* The [varname]+plothover+ event points to the client-side function to execute when the mouse cursor is over the chart point.
+* The [varname]+plotclick+ event points to the client-side function to execute when the user clicks the chart point.
+* The [varname]+mouseout+ event points to the cient-side function to execute when the mouse cursor leaves the chart grid.
+
+The plothover and plotclick handlers are given an event-object that contains the deatils of which point fired the event.
+
+[source, JavaScript]
+----
+function log(e){
+           	console.log("Series index: "+
+                 	e.data.seriesIndex +" DataIndex: "+
+                 	e.data.dataIndex+' ['+e.data.x+','+e.data.y+']');
+}
+----
+
+==== JavaScript API
+
+To access the jQuery widget of the component, use the componentID + chart
+
+[function]+resetZoom()+::  display chart without scaling
+[function]+getPlotObject()+:: returns JavaScript object containing chart data and options
+
+Example
+[source, XML]
+----
+<r:chart id=”price”>
+…
+----
+
+[source, JavaScript]
+----
+$(document.getElementById(“priceChart”)).chart(“resetZoom”)
+----
+
+==== Reference data
+
+* [parameter]+component-type+: 
+* [parameter]+component-class+: 
+* [parameter]+component-family+: 
+* [parameter]+renderer-type+: 
+
+
 === [sgmltag]+<r:message>+
 
 The [sgmltag]+<r:message>+ component renders a single [classname]+FacesMessage+ message instance added for the component. The appearance of the message can be customized, and tool-tips can be used for further information about the message.