(r19) XvwCharts < WebXEO

WebXEO Web>XeoPrimerXeoXwc>XvwCharts (revision 19) (raw view)~~EditAttach~~
-- Main.PedroRio - 24 Mar 2010
---+ XVW Charts: Bar, Line and Pie

The Charts component allows the creation of [[http://en.wikipedia.org/wiki/Bar_chart][Bar Charts]] (horizontal and vertical) with multiple series, [[http://en.wikipedia.org/wiki/Line_chart][Line Charts]] (with multiple series) and [[http://en.wikipedia.org/wiki/Pie_chart][Pie Charts]]. All chart components need a "DataSet" which represents the values to display in the charts, the DataSet is populated by the Bean method used in the Viewer (or by a SQL or BOQL query).

All Chart types have two different _render_ types, one as a _Flash_ animation and another as a _static image_, which can be selected in the XML chart declaration.
---++ <a name="PieChart"></a>Pie Chart

The pie chart component allows you to create a pie-shaped visualization (hence the name) of a set Key/Value pairs. The sum of all values corresponds to 100% and each value corresponding to a key represents a percentage of that sum.

<img width="500" alt="Pie Chart Example" src="http://wiki.itds.pt/pub/WebXEO/XvwCharts/PieChart.png" style="vertical-align: middle;" title="Pie Chart Example" height="174" />
---+++ XML Pie Chart declaration

Below is a declaration of all PieChart options (note that a Bean associated to the viewer with the identifier "viewBean" is assumed).

<verbatim><xvw:pieChart
    label="Example Chart"
    dataSet="#{viewBean.dataSet}"
    width="500"
    height="300"
    type="IMG"
    configOptions="#{viewBean.configOptions}"
    sql = "SQL_EXPRESSION"
    sqlAttCategory = "SQL_COLUMN_NAME_FOR_CATEGORIES"
    sqlAttValues = "SQL_COLUMN_NAME_FOR_VALUES"
    >    
</xvw:pieChart></verbatim>

---+++ Pie Chart Properties
| *Property name* | *Description* | *Type* | *Possible values* | *Default Value* | *Use* |
| label | A text to show as the chart label | String/EL | Any String | None | Required |
| dataSet | Chart dataSource, essentially a key/value set, alternatively you can use a "sql" or "boql" attribute  | EL | A implementation of java interface | None | Optional |
| width | The chart length (in pixels) | Integer/EL | Any value above zero | 400 | Optional |
| height | The chart height(in pixels) | Integer/EL | Any value above zero | 300 | Optional |
| type | The chart render type, if static image or Flash | String/EL | IMG, FLASH | None | Required |
| configOptions | Chart formatting configuration | EL | A Java Interface implementation | None | Optional |
| sql | SQL expression which returns a Result Set with two columns: categories and values (preferential method for returning a dataSet) | String/EL | A SQL expression | None | Optional |
| boql | BOQL Expression to execute, each result must have two coluns (<em>categories </em>and _values_) | String/EL | A BOQL Expression | None | Optional |
| resultLimit | Limits the number of results to display when the data source is a BOQL / SQL expression | Integer/EL | Any positive value | None | Optional |
| sqlAttCategory | Name of the Result Set column returned by the previous sql expression which contains the category names | String/EL | The column name | None | Optional* |
| sqlAttValues | Result Set column name returned by the sql expression which contains the values for each category | String/EL | A column name | None | Optional* |

__*Note: Optional, but if using a sql property, it is required.__
---+++ DataSource Java Interface (Pie Data Set)

The necessary data for a Pie Chart is a *set of Key-Value pairs*. If using the dataSet property in the XML declaration of the component you need to implement the PieDataSet interface and return an instance of that implementation. The interface is detailed bellow:
<verbatim>/**
     * Retrieves a value, given a key
     * 
     * @param key The key corresponding to the value
     * 
     * @return A number representing the value
     */
    public Number getValue(Comparable<String> key);
    
    /**
     * 
     * Retrieve the list of categories in the pie chart
     * 
     * @return A list of categories
     */
    public List<String> getCategories();
    
    /**
     * 
     * The label for the category 
     * 
     * @return A string with the label for the key set
     */
    public String getCategoryLabel();
    
    
    /**
     * 
     * The label for the value set
     * 
     * @return A string with the label for the value set
     */
    public String getValueLabel();</verbatim>

---+++ Using a SQL expression as dataSource

Beside a specific implementation of PieDateSet it is possible to use a SQL expression to generate the chart values. For example, imagine you want a Pie Chart with the number of instances by type of objects in the current XEO installation. To obtain that you could use the following SQL Expression:
<verbatim>select name, count(CLSID) as total from ebo_registry GROUP BY name</verbatim>

The previous expression returns a ResultSet with two columns (name and total) which can be used as chart DataSource. To do that you would use the following XML definition for the PieChart:

<verbatim><xvw:pieChart
         label="New Chart" 
         width="500"
         height="500"
         type="FLASH"
         sql="select name, count(CLSID) as total from ebo_registry GROUP BY name"
         sqlAttCategory="name"
         sqlAttValues="total"</strong>
         configOptions="#{viewBean.configOptions}"
         >
  </xvw:pieChart></verbatim>

When using the _sql_ property, the <em>sqlAttCategory </em>and _sqlAttValues_ properties are required, because the component needs to know where to fetch the labels and the corresponding values to display.
---+++ Configuration Java Interface (IPieChartConfiguration)

The Pie Chart is defined to have a certain appearance by default. This appearance can be customized if you implement the IPieChartConfiguration interface, which has methods to change the aspect of the chart component. The interface definition is the following:
<verbatim>/**
     * 
     * Returns the background color of the chart
     * 
     * @return The Color to use or null if the default colour should be used
     */
    public Color getBackgroundColour();
    
    /**
     * 
     * The list of colours for the pie pieces
     * 
     * @return An array of Colors
     */
    public Color[] getColours();
    
    
    /**
     * 
     * Whether or not the pie chart should show the labels
     * 
     * @return True if the labels should be shown and false otherwise
     */
    public boolean showLabels();
    
    
    /**
     * 
     * Whether or not the pie chart title should be shown
     * 
     * @return True if the chart should display the title and false otherwise
     */
    public boolean showChartTitle();
    
    /**
     * 
     * Returns the string expression to use as tooltip, one can use the following
     * special variables
     * 
     * $key = The name of the pie slice 
     * $val = The value of the slice
     * $percent = the percentage from total of the slice
     * 
     * Example: "$key has value $val which is $percent of total",
     *  which could output something like
     * "Microsoft has value 30000 which is 30% of total"
     * 
     * @return A string expression for the tooltip (or null to use the default value)
     */
    public String getTooltipString();</verbatim>

---+++ Example Implementation

As Example, the page [[WebXEO.PieChartJava][Example Implementation]] has the complete Bean and implementation code of a data interface, configuration interface and images of how the situation is changed by the configurations.
---++ <a name="BarGraph"></a>Bar Chart

The Bar Chart component renders bar chars (as the name implies). The Bar Charts may be presented vertically or horizontally and may contain multiple series.

<img width="500" alt="BarChart" src="http://wiki.itds.pt/pub/WebXEO/XvwCharts/BarChart.png" title="BarChart" height="254" />
---+++ XML Bar Chart Declaration
<verbatim><xvw:barChart 
        dataSet="#{viewBean.barDataSet}" 
        label="My Bar Chart" 
        width="1000" 
        height="400"
        type="FLASH"
        orientation="vertical"
        configOptions="#{viewBean.configBarOptions}"
        sql = "select column,series,values from data"
        sqlAttColumn="column"
        sqlAttSeries = "series"
        sqlAttValues = "values"
        >
</xvw:barChart></verbatim>

---+++ Bar Chart Properties
| *Property name* | *Description* | *Type* | *Possible values* | *Default values* | *Use* |
| label | A text to show as chart label | String/EL | Any String | None | Required |
| dataSet | Chart data source, essentially a set of Key/Value pairs | Java Interface/EL | A implementation of a Java interface | None | Optional |
| width | The chart length (in pixels) | Integer /EL | Any value above zero | 400 | Optional |
| height | The chart height (in pixels) | Integer /EL | Any value above zero | 300 | Optional |
| type | The chart render type, if static image or in flash | String /EL | IMG, FLASH | None | Required |
| orientation | The chart orientation. "vertical" for vertical and "horizontal" for horizontal | String /EL | vertical, horizontal | horizontal | Optional |
| configOptions | Chart formatting options | Java Interface /EL | A implementation of a Java interface | None | Optional |
| sql | A SQL expression of which the <em>resultSet </em>should have 3 columns (column, series and value) | String / EL | A SQL expression | None | Optional |
| sqlAttColumn | The name of a <em>resultSet </em>column, which has the name of the columns (values in X) | String / EL | The name of a SQL column | None | Optional* |
| sqlAttSeries | The name of a <em>resultSet </em>column, which has the name of the series | String / EL | The name of a SQL column  | None | Optional* |
| sqlAttValues | The name of a <em>resultSet </em>column, which has the values | String / EL | The name of a SQL column  | None  | Optional* |
| columnLabelsMap | Label mapping for the columns | Map&lt;String,String&gt; | | | Optional |
| seriesLabelsMap | Label mapping for the series | Map&lt;String,String&gt; | | | Optional |

_*Note: Optional, but if using a sql property, it's required._
---+++ Java Interface for data (Series Data Set) <a name="seriesDataSet"></a>
<verbatim>/**
 * 
 * Represents a data set which can have a set of columns (xAxis) and for each value in the xAxis, a set
 * of series (yAxis) can exist. This interface represents the data set for bar/line charts. For instance if a bar chart showing
 * page views and visits to given website over the course of a three months (January to March), the DataSet would have
 * three columns (January, February and March) and two series (page views and visits), with a value for page view and visit for
 * each of the three months
 * 
 * 
 *
 */
public interface SeriesDataSet 
{
    
    /**
     * 
     * Retrieves the list of series of this data set (must be at least one) 
     * 
     * @return The list of series
     */
    public List<String> getSeriesKeys();
    
    /**
     * 
     * Retrieves the list of columns of this data set (must be at least one)
     * 
     * @return The list of columns of this data set
     */
    public List<String> getColumnKeys();
    
    /**
     * 
     * For a given Column and a given series, retrieves the value associated
     * 
     * @param seriesKey The series key 
     * @param columnKey The column key
     * 
     * @return The numeric value associated with the series/column pair, or null if there's no value
     * for that specific pair
     */
    public Number getValue(String seriesKey, String columnKey);
    
    
    
    /**
     * 
     * The name of the XAxis values
     * 
     * @return The name of the XAxis values
     */
    public String getXAxisLabel();
    
    
    /**
     * 
     * The name of the YAxis values
     * 
     * @return The name of the YAxis values
     */
    public String getYAxisLabel();
    
}</verbatim>
---+++ Using SQL to fill the chart data.<a name="sqlExpression"></a>

As introduced before in the PieCharts section, it is possible to use a SQL expression as a data source. Bar charts may have multiple data series, so SQL expressions are required to have 3 columns. Imagine you want to show for the months (Column) of June 2007 and August 2007, the number of Pages Views and Hits (series). Imagine there's a database table called DATA which has three columns: Column, Series, Value and has the following content:
| *Column* | *Series* | *Value* |
| Aug 07 | Views | 233 |
| Aug 07 | Hits | 455 |
| Jul 07 | Views | 400 |
| Jul 07 | Hits | 1000 |

Executing the query "<strong><em>select Column, Series, Values from DATA</em></strong>" you have all necessary values to show a Bar Chart (With two series per column), you only need to declare which query attributes correspond to the columns, series and values, using the properties listed above ( _attColumn_, _attSeries_ e _attValues_)
---+++ Configuration Java interface (IBarCharConfiguration)
<verbatim>/**
     * 
     * Returns the background color of the chart as Java Color
     * 
     * @return A Color instance with the required color
     */
    public Color getBackgroundColour();
    
    /**
     * 
     * The list of colours for the series of the chart
     * 
     * @return An array with colors
     */
    public Color[] getColours();
    
    /**
     * 
     * Whether or not the pie chart title should be shown
     * 
     * @return True if the chart should display the title and false otherwise
     */
    public boolean showChartTitle();
    
    /**
     * 
     * Returns the string expression to use as tooltip, one can use the following
     * special variables
     * 
     * $val = The value for the point
     * 
     * @return A string expression for the tooltip (or null to use the default value)
     */
    public String getTooltipString();</verbatim>

---++ <a name="LineGraph"></a>Line Chart

The Line Charts are charts in which the points are united by a line. The line chart component allows to have several lines representing different data. It shares the same data model as the bar chart (i.e. you use a SeriesDataSet as a data source)

<img width="500" alt="LineChart" src="http://wiki.itds.pt/pub/WebXEO/XvwCharts/LineChart.png" title="LineChart" height="250" />
---+++ XML Definition (Line Chart)
<verbatim><xvw:lineChart 
    dataSet="#{viewBean.lineDataSet}" 
    label="Sample Line Chart" 
    width="500" 
    height="500"
    type="FLASH"
    configOptions="#{viewBean.configLineOptions}"
    sql = "select column, series, values from data"
    sqlAttColumn = "column"
    sqlAttSeries = "series"
    sqlAttValues = "values"
/></verbatim>

---+++ Line Chart Properties
| *Property name* | *Description* | *Type* | *Possible values* | *Default Value* | *Use* |
| label | A text to show as the chart label | String / EL | Any String | None | Required |
| dataSet | Chart data Source, essentially a set of key / value pairs | Java Interface / EL | A implementation of a Java interface | None | Required |
| width | The chart lenght (in pixels) | Integer /EL | Any value above zero | 400 | Optional |
| height | The chart height (in pixels)  | Integer / EL | Any value above zero | 300 | Optional |
| type | The chart render type (static image or in flash) | String | IMG, FLASH | None | Required |
| configOptions | Chart formating options | Java Interface / EL | A implementation of a Java interface | None | Optional |
| sql | A SQL expression, whose result set should have 3 columns (column, serie and value) | String / EL | A SQL expression | None | Optional |
| sqlAttColumn | The name of the Result Set column which has the names of the several columns (values in X) | String / EL | The name of a SQL column | None | Optional* |
| sqlAttSeries | The name of the Result Set column which has the series | String / EL | The name of a SQL column | None | Optional* |
| sqlAttValues | The name of the Result Set column which has the values | String / EL | The name of a SQL column | None | Optional* |

_*Note: Optional, but if using a sql property, it is required._
---+++ Java Data Interface (Series Data Set)

The Line Chart data interface is exactly the same as from a Bar Chart, [[#seriesDataSet][so consult the Bar Chart Series Data Set]].
---+++ Using a SQL expresion as Data Source

The use of a SQL expression in a Line Chart is [[#sqlExpression][exactly the same as from a Bar Chart]].
---+++ Configuration Java Interface of a Line Chart
<verbatim>public interface ILineChartConfiguration 
{

    /**
     * 
     * Returns the background color of the chart as Java Color
     * 
     * @return A Color instance with the required color (or null to retain the default color)
     */
    public Color getBackgroundColour();
    
    /**
     * 
     * The list of colours for the series of the chart
     * 
     * @return An array of colors
     */
    public Color[] getColours();
    
    /**
     * 
     * Whether or not the pie chart title should be shown
     * 
     * @return True if the chart should display the title and false otherwise
     */
    public boolean showChartTitle();
    
    /**
     * 
     * Returns the string expression to use as tooltip, one can use the following
     * special variables
     * 
     * $val = The value for the point
     * 
     * @return A string expression for the tooltip (or null to use the default value)
     */
    public String getTooltipString();
    
    /**
     * 
     * Retrieves the stroke size for the lines
     * 
     * @return An integer with the stroke size (in pixels) for each line or 0 to use the default size
     */
    public int getStrokeSize();
    
    
    
}</verbatim>
Attachments
Topic attachments
I	Attachment	Action	Size	Date	Who	Comment
png	BarChart.png	manage	9.4 K	2010-03-29 - 09:26	PedroRio	Bar Charts
png	LineChart.png	manage	14.4 K	2010-03-29 - 09:36	PedroRio	Line Chart
png	PieChart.png	manage	8.9 K	2010-03-26 - 18:24	PedroRio	Pie Chart
Topic revision: r19 - 2013-03-22 - JoaoAires
No permission to view TWiki.WebTopBar
No permission to view TWiki.WebBottomBar