diff --git a/Component_Reference/src/main/docbook/en-US/Component_Reference-docinfo.xml b/Component_Reference/src/main/docbook/en-US/Component_Reference-docinfo.xml index d3065523..25aaae35 100644 --- a/Component_Reference/src/main/docbook/en-US/Component_Reference-docinfo.xml +++ b/Component_Reference/src/main/docbook/en-US/Component_Reference-docinfo.xml @@ -1,11 +1,11 @@ -A reference guide to the components of the RichFaces 4 framework +A reference guide to the components of the RichFaces 5 framework RichFaces 5.0.0-SNAPSHOT 1 1 - 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. diff --git a/Component_Reference/src/main/docbook/en-US/Component_Reference.asciidoc b/Component_Reference/src/main/docbook/en-US/Component_Reference.asciidoc index 8b855c05..8407b849 100644 --- a/Component_Reference/src/main/docbook/en-US/Component_Reference.asciidoc +++ b/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]++ + +The [sgmltag]++ component allows the user to plot data and to create line, bar or pie charts. It uses up to five children tags [sgmltag]++, [sgmltag]++, [sgmltag]++, [sgmltag]++ and [sgmltag]++. Each child tag customizes a particular aspect of the chart. All are optional except at least one [sgmltag]++ tag is required. + +Additionally the [sgml]++ 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]++ tag and its optional children tags generate and customize the chart. The chart type is selected by a [sgmltag]++ attribute. The only requirements for use of the [sgmltag]++ 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]++ component accepts data by two means - by facelet iteration or by creating data model object. + +===== Facelet iteration + +Use [sgmltag]++ and a collection of objects inside the [sgmltag]++ tag and specify what you want to be plotted on the x and y axis using [sgmltag]++ tag. The [sgmltag]++ approach can also be used at the [sgmltag]++ level. + +[[exam-Component_Reference-chart_facelet_iteration_example]] + +.r:chart facelet iteration example +==== + +[source, XML] +---- + + + + + + + + + +---- + +==== + +===== 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]++ 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]++ tag using the data attribute. + +[[exam-Component_Reference-chart_datamodel_object_example]] + +.r:chart DataModel object example +==== + +[source, XML] +---- + + + + + +---- + +[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]++ data attribute, any nested [sgmltag]++ tags are ignored. If the data attribute is not used, then nested [sgmltag]++ 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]++ or [sgmltag]++ tag. The [sgmltag]++ 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]++ component does not only create static charts. + +* It allows the user to zoom line charts when the [sgmltag]++ 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]++ 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]++ attributes. + +[[sect-Component_Reference-chart-chart_server-side_events]] + +==== [sgmltag]++ 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]++ 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] +---- + +… +---- + +[source, JavaScript] +---- +$(document.getElementById(“priceChart”)).chart(“resetZoom”) +---- + +==== Reference data + +* [parameter]+component-type+: +* [parameter]+component-class+: +* [parameter]+component-family+: +* [parameter]+renderer-type+: + + === [sgmltag]++ The [sgmltag]++ 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. diff --git a/Component_Reference/src/main/docbook/en-US/images/figu-Component_Reference-chart-chart_component.png b/Component_Reference/src/main/docbook/en-US/images/figu-Component_Reference-chart-chart_component.png new file mode 100644 index 00000000..29b27b2f Binary files /dev/null and b/Component_Reference/src/main/docbook/en-US/images/figu-Component_Reference-chart-chart_component.png differ