-- PedroRio - 24 Mar 2010

Gráficos XVW: Barras, Linhas e em Tarte

A componente de gráficos XVW permite a criação de Gráficos de Barras (Horizontais e Verticais) com múltiplas séries, assim como gráficos de linhas (com múltiplas séries) e gráficos em tarte. Todos os componentes de gráficos precisam de um "Data Set" que representa os valores a apresentar nos respectivos gráficos, os data sets são preenchidos através de métodos da Bean utilizada no Viewer.

Todos os tipos de gráficos tem dois tipos de render diferentes, uma em Flash e outra em Imagem estática, que podem ser escolhidos na declaração XML do gráfico.

Gráfico em Tarte (Pie Chart)

O gráfico em tarte permite criar uma visualização em forma de tarte (daí o nome) para um conjunto de pares chave/valor. O total dos valores somados corresponde a 100% e cada valor correspondente à chave representa uma percentagem desse total.

Declaração XML de Pie Chart

Em baixo fica uma declaração completa com todas as opções do Pie Chart (de notar que se assume a existência de uma Bean associada ao viewer com o identificador "viewBean".

<xvw:pieChart
    label="Gráfico Exemplo"
    dataSet="#{viewBean.dataSet}"
    width="500"
    height="300"
    type="IMG"
    configOptions="#{viewBean.configOptions}"
    sql = "SQL_EXPRESSION"
    sqlAttCategory = "SQL_COLUMN_NAME_FOR_CATEGORIES"
    sqlAttValue = "SQL_COLUMN_NAME_FOR_VALUES"
    >    
</xvw:pieChart>

Os elementos, label, width e height, sql, sqlAttCategory e sqlAttValue podem ter os valores a partir da Bean do viewer, como tal é possível algo como:

<xvw:pieChart
    label="#{viewBean.label}"
    dataSet="#{viewBean.dataSet}"
    width="#{viewBean.width}"
    height="#{viewBean.height}"
    type="IMG"
    configOptions="#{viewBean.configOptions}"
    sql = "#{viewBean.sql}"
    sqlAttCategory = "#{viewBean.sqlAttCategory}"
    sqlAttValue = "#{viewBean.sqlAttValue}"
    >    
</xvw:pieChart>

Propriedades do Pie Chart

Nome da Propriedade	Descrição	Tipo	Valores Possíveis	Valor por omissão	Uso
label	Um texto para mostrar gráfico como legenda	String	Qualquer String	Nenhum	Obrigatório
dataSet	Fonte de dados para o gráfico, essencialmente um conjunto de pares chave/valor, a alternativa é usar o atributo "sql" (ver em baixo)	Interface Java	Uma implementação da interface Java	Nenhum	Opcional
width	O comprimento do gráfico (em pixeis)	Integer	Qualquer valor maior que zero	400	Opcional
height	A altura do gráfico (em pixeis)	Integer	Qualquer valor maior que zero	300	Opcional
type	O tipo de render do gráfico, se imagem estática ou em flash	String	IMG, FLASH	Nenhum	Obrigatório
configOptions	Configurações da formatação do gráfico	Interface Java	Uma implementação da interface Java	Nenhum	Opcional
sql	Expressão SQL que retorne um Result Set com duas colunas, categorias e valores (método preferencial para devolver um conjunto de dados)	String	Uma expressão SQL	Nenhum	Opcional
sqlAttCategory	Nome da coluna do Result Set devolvido pela expressão sql anterior que contém os nomes das categorias	String	O nome de uma coluna	Nenhum	Opcional
sqlAttValue	Nome da coluna do Result Set devolvido pela expressão sql anterior que contém os valores para cada categoria	String	O nome de uma coluna	Nenhum	Opcional

Interface Java da Fonte de Dados (Pie Data Set)

Os dados necessários para um Pie Chart são um conjunto de pares chave-valor. O método que se colocar na configuração XML para a propriedade "dataSet" TEM de devolver uma implementação desta interface para que o gráfico possa ser construído.

/**
     * 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();

Usar uma expressão SQL como fonte de dados

Além de uma implementação específica da interface PieDataSet é possível usar uma expressão SQL para gerar os valores do gráfico. Por exemplo, imagine-se que se queria um gráfico em tarte com o número instâncias por tipo de objecto existente na instalação XEO corrente. A expressão SQL a usar poderia ser a seguinte:

select name, count(CLSID) as total from ebo_registry GROUP BY name

Esta expressão devolve um ResultSet com duas colunas (name e total) que podem ser usados como fonte de dados para o gráfico, para seria usar a seguinte definição XML para o pieChart

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

O nome das colunas às quais correspondem os valores são imprescindíveis pois só assim o componente consegue saber o que mostrar correctamente.

Interface Java das Configurações (IPieChartConfiguration)

Os gráficos em tarte estão configurados para terem determinado aspecto por omissão. Esse aspecto pode ser customizado se se fizer a implementação da interface IPieChartConfiguration, que possui métodos para alterar o aspecto de alguns componentes do gráfico. A definição da Interface é a seguinte:

/**
     * 
     * 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();

Implementação Exemplo

A titulo exemplificativo, a página da Implementação Exemplo tem o código completo de uma Bean e uma implementação da interface de dados e da interface de configurações e imagens de como a situação é alterada consoante as configurações.

Gráfico de Barras (Bar Chart)

O gráfico de barras permite uma visualização de pontos sobre dois eixos (X,Y). Os gráficos de barras podem ser apresentados na vertical ou horizontal e podem conter múltiplas séries.

Declaração XML de um Bar Chart

<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>

Tal e qual como no Pie Chart, as propriedades label, width e height podem ser alimentadas a partir da Bean do Viewer.

Propriedades do Bar Chart

Nome da Propriedade	Descrição	Tipo	Valores Possíveis	Valor por omissão	Uso
label	Um texto para mostrar gráfico como legenda	String	Qualquer String	Nenhum	Obrigatório
dataSet	Fonte de dados para o gráfico, essencialmente um conjunto de pares chave/valor	Interface Java	Uma implementação da interface Java	Nenhum	Opcional
width	O comprimento do gráfico (em pixeis)	Integer	Qualquer valor maior que zero	400	Opcional
height	A altura do gráfico (em pixeis)	Integer	Qualquer valor maior que zero	300	Opcional
type	O tipo de render do gráfico, se imagem estática ou em flash	String	IMG, FLASH	Nenhum	Obrigatório
orientation	A orientação do gráfico. "vertical" para vertical e "horizontal" para horizontal	String	vertical, horizontal	horizontal	Opcional
configOptions	Configurações da formatação do gráfico	Interface Java	Uma implementação da interface Java	Nenhum	Opcional
sql	Uma expressão SQL cujo result set deve ter 3 colunas (coluna, série e valor)	String	Uma expressão SQL	Nenhum	Opcional
sqlAttColumn	O nome da coluna do Result Set que contém os nomes das várias colunas (valores em X)	String	O nome de uma coluna SQL	Nenhum	Opcional
sqlAttSeries	O nome da coluna do Result Set que contém os nomes das várias séries	String	O nome de uma coluna SQL	Nenhum	Opcional
sqlAttValues	O nome da coluna do Resut Set que contém os valores	String	O nome de uma coluna SQL	Nenhum	Opcional

Interface Java para os dados (Series Data Set)

/**
 * 
 * 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();
    
}

Utilização de SQL para preencher os dados do gráfico.

Tal como introduzido anteriormente para os PieChart é possível utilizar uma expressão SQL para preencher os valores do gráfico. Gráficos de barras podem possuir múltiplas séries de dados, pelo que as expressões SQL estão obrigadas a ter 3 colunas de valores. Imaginando que queremos mostrar para os meses (Colunas) de Julho de 2007 e Agosto de 2007, os dados de Pages Views e Hits (Séries), se existir uma tabela SQL chamada DATA que possui três colunas: Column, Series, Value e que tem o seguinte conteúdo:

Column	Series	Value
Aug 07	Views	233
Aug 07	Hits	455
Jul 07	Views	400
Jul 07	Hits	1000

Executando a query "select Column, Series, Values from DATA" ficamos com todos os valores necessários a mostrar um gráfico de barras (com duas séries por coluna), tudo o que é preciso é dizer quais os atributos da query que correspondem às colunas, séries e valores, usando as propriedades enunciadas anteriormente (attColumn, attSeries e attValues)

Interface Java de Configurações (IBarCharConfiguration)

/**
     * 
     * 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();

Gráfico de Linhas (Line Chart)

Gráficos de linhas são gráficos em que os pontos (pares X,Y) estão unidos por uma linha, sendo que no mesmo gráfico podem-se ter várias linhas representados dados diferentes. É um tipo de gráfico que partilha o mesmo tipo de dados do gráfico de Barras.

Definição XML (Line Chart)

<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"
/>

As propriedades label, width e height (assim como sql, sqlAttColumn, sqlAttSeries e sqlAttValues) podem ser provenientes da Bean do viewer como tal podemos ter o seguinte:

<xvw:lineChart 
    dataSet="#{viewBean.lineDataSet}" 
    label="#{viewBean.label}" 
    width="#{viewBean.width}" 
    height="#{viewBean.height}"
    type="FLASH"
    configOptions="#{viewBean.configLineOptions}"
    sql = "#{viewBean.sql}"
    sqlAttColumn = "#{viewBean.sqlAttColumn}"
    sqlAttSeries = "#{viewBean.sqlAttSeries}"
    sqlAttValues = "#{viewBean.sqlAttValues}"
/>

Propriedades de um Line Chart

Nome da Propriedade	Descrição	Tipo	Valores Possíveis	Valor por omissão	Uso
label	Um texto para mostrar gráfico como legenda	String	Qualquer String	Nenhum	Obrigatório
dataSet	Fonte de dados para o gráfico, essencialmente um conjunto de pares chave/valor	Interface Java	Uma implementação da interface Java	Nenhum	Obrigatório
width	O comprimento do gráfico (em pixeis)	Integer	Qualquer valor maior que zero	400	Opcional
height	A altura do gráfico (em pixeis)	Integer	Qualquer valor maior que zero	300	Opcional
type	O tipo de render do gráfico, se imagem estática ou em flash	String	IMG, FLASH	Nenhum	Obrigatório
configOptions	Configurações da formatação do gráfico	Interface Java	Uma implementação da interface Java	Nenhum	Opcional
sql	Uma expressão SQL cujo result set deve ter 3 colunas (coluna, série e valor)	String	Uma expressão SQL	Nenhum	Opcional
sqlAttColumn	O nome da coluna do Result Set que contém os nomes das várias colunas (valores em X)	String	O nome de uma coluna SQL	Nenhum	Opcional
sqlAttSeries	O nome da coluna do Result Set que contém os nomes das várias séries	String	O nome de uma coluna SQL	Nenhum	Opcional
sqlAttValues	O nome da coluna do Resut Set que contém os valores	String	O nome de uma coluna SQL	Nenhum	Opcional

Interface Java de Dados (Series Data Set)

A interface de dados de um Line Chart é exactamente a mesma de um Bar Chart, como tal é consultar a Series Data Set dos Bar Chart.

Utilização de uma expressão SQL como fonte de dados

A utilização da expressão SQL num gráfico de linhas é exactamente igual à do gráfico de barras.

Interface Java de Configurações para um Line Chart

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();
    
    
    
}