Tutorial 12 – Charts (Revised 12/22/2011)

Recently we updated chart components in Formspider. This tutorial explains changes in the design and shows example use cases for the new properties of charts.

You may see the demo application here.

Changes in this release

In this version, we simplified and shortened the XML of the category and xy charts and also added some features as follow;

  • Plots are removed. Multi-plot look can still be obtained using new minimumValue and maximumValue axis attributes. More on them later.
  • Charts may contain one or zero categoryAxis.
  • Range Axises have a default attribute that can be set to ‘Y’ in order to indicate all renderers in the categoryChart to use it.
  • You may now set specific colors to bars, lines, splines and items. In addition, bars support gradient colors.

Pie Chart Example – 1

In this tutorial, for pie charts, we will use a datasource definition based on query. So, create a datasource definition and name it as “PieDS”. Then, select “Query” in “Based on” section and enter the following sql query.

select 'Volkswagen' as car_model, '3856000' as amount, 'N' as sliced from dual
union
select 'G.M.' as car_model, '4360000' as amount, 'N' as sliced from dual
union
select 'Hyundai' as car_model, '7895000' as amount, 'N' as sliced from dual
union
select 'Toyota' as car_model, '5000000' as amount, 'Y' as sliced from dual
union
select  'Fiat' as car_model, '2547000' as amount, 'N' as sliced from dual
union
select  'Ford' as car_model, '6457900' as amount, 'Y' as sliced from dual
union
select 'Others' as car_model, '8754000' as amount, 'N' as sliced from dual

After clicking OK, a new datasource named “PieDS1″ will automatically be created with 3 columns. For the first pieChart example, “car_model” column will be used as categoryColumn and “amount” column will be used as valueColumn. So, edit “mainPanel” and create a pieChart using the following XML.

<panel>
  <xyLayout>
    <cell x="10" y="10" width="500" height="500">
      <pieChart dataSource="PieDS1" categoryColumn="CAR_MODEL" valueColumn="AMOUNT"/>
    </cell>
  </xyLayout>
</panel>

This creates a simple pie chart based on the given data. You may test it by running the application. In this version, we support user interaction with the chart. You may click on a slice to pull it out or drag mouse over it to see the details. In the following screenshot, we clicked on blue slice (Fiat) and also dragged mouse on it.

A simple pie chart

A simple pie chart

Pie Chart Example – 2

For the second pie chart example, we edited the “mainPanel” XML as follow;

<panel>
  <xyLayout>
    <cell x="10" y="10" width="500" height="500">
      <pieChart dataSource="PieDS1" categoryColumn="CAR_MODEL" valueColumn="AMOUNT"
      displayStyle="3D" backgroundColor="#999999" plotBackgroundColor="#FFF38F"
      labelFormat="#{category}:#{percentage}" slicedColumn="sliced"
      title="Shares of Total Car Production">
        <subtitle text="by individual car companies"/>
        <legend border="N" position="Top" visible="Y"/>
      </pieChart>
    </cell>
  </xyLayout>
</panel>

In this example, we added title and subtitle to the pieChart and modified the legend(1). Notice that we moved the legend to “Top” and removed its border. We also changed the background color of the chart and the background color of the plot area with backgroundColor and plotBackgroundColor attributes. We added a labelFormat(2) attribute to display the categories and percentages of the slices of the pie chart. Notice that our framework automatically converts the actual value in the “amount” column to percentages. In our datasource, we have a column named “sliced” that consists of “N” and “Y” values. This column can be given as a slicedColumn to pie chart so that all slices that have “Y” will be displayed as pulled out by default. In our example, we pulled out the slice that belongs to “Ford” and “Toyota”. Notice that legend only shows data of the pulled out slices.(3) You may see the generated pie chart in the following screenshot.

(1) Tip: You may make the legend invisible by just setting the visible attribute to “N”.
(2) Tip: In “labelFormat” attribute you may use category, value and percentage keywords inside “#{” and “}” strings to format the labels on slices. Example of “#{category}:#{percentage}” can be seen in the following screenshot.
(3) Tip: Pie Charts that do not have slicedColumn attribute shows all slices in the legend. If a slicedColumn is given, legend only shows pulled out slices.
An advanced pie chart

An advanced pie chart

Category and XY Charts in Formspider

In Formspider, you can create bar, line, spline and item charts and combinations of them using the categoryChart and xyChart components. XML of these components are similar but rendering and input data types create slight differences between them. categoryChart can render all of the chart types in a familiar way, but xyChart displays bars as squares that have sizes according to input value. Both components display range axis intervals in proportion to data in value columns, however xyChart also displays categoryAxis values in proportion to data value in category columns. Thus requires number values in categoryColumns in the renderers of xy charts.

Category Chart Example – 1

In this example, we will create a simple categoryChart to display two set of values as bars. So, you may start with either creating a new application or editing the existing one. Create a new datasource definition named “categoryDS” using the following query;

select 'FS Alpha 0.1' as build_name, '110' as found, '75' as fixed from dual
union
select 'FS Alpha 0.2' as build_name, '78' as found, '42' as fixed from dual
union
select 'FS Beta 0.5' as build_name, '150' as found, '85' as fixed from dual
union
select 'FS Beta 0.6' as build_name, '100' as found, '95' as fixed from dual
union
select 'FS Beta 0.7' as build_name, '55' as found, '79' as fixed from dual
union
select 'FS 1.0' as build_name, '25' as found, '75' as fixed from dual
union
select 'FS 1.1' as build_name, '12' as found, '50' as fixed from dual

Then, edit the mainPanel as follow;

<panel>
  <xyLayout>
    <cell x="10" y="10" width="500" height="500">
      <categoryChart title="Bugs" backgroundColor="#CEFFE7" displayStyle="2D" plotBackgroundColor="white">
        <subtitle text="Found and Fixed Bugs in Formspider Project"/>
        <barRenderer dataSource="categoryDS1" categoryColumn="BUILD_NAME" labelFormat="#{value}">
          <bar valueColumn="FOUND" legendLabel="Bugs Found" color="red" gradientColor="#FF878D"/>
          <bar valueColumn="FIXED" legendLabel="Bugs Fixed" color="green" gradientColor="#A1FF8E"/>
        </barRenderer>
      </categoryChart>
    </cell>
  </xyLayout>
</panel>

We created a categoryChart with a single barRenderer with two bars. barRenderer has a datasource named “categoryDS1″ which is automatically created after we created previous datasource definition. It uses unique values in categoryColumn to identify the number of bars in one bar set and uses the values in valueColumns of bars to identify the height of the bars.

So, you can now run the application and see the result that looks like the following screenshot. Notice that colors of the charts are darker at the bottom and lighter at the top as we give darker color to bar‘s color attribute and lighter to gradientColor attribute. Also, this charts represents a new rendering style of category and xy charts. If there is no category or range axis specified, chart components do not display any axises so we cannot see the values in categoryColumn at the bottom of the bars and value range on the left side.

Tip: All types of renderers in category and xy charts have labelFormat attribute that can be used to set labels displayed on bars, lines and items. In this attribute, you may use category, value keywords to display the associated categoryColumn and valueColumn values by writing them inside “#{” and “}” strings.
Simple category chart with two set of bars

Simple category chart with two set of bars

Category Chart Example – 2

For this example, we will use the same datasource with the previous one so set the “mainPanel” XML as follow;

<panel>
  <xyLayout>
    <cell x="10" y="10" width="500" height="500">
      <categoryChart title="Bugs" backgroundColor="#81FF54" plotBackgroundColor="#C1CBFF">
        <subtitle text="Found and Fixed Bugs in Formspider Project"/>
        <lineRenderer dataSource="categoryDS1" categoryColumn="BUILD_NAME">
          <line valueColumn="FOUND" legendLabel="Bugs Found"/>
        </lineRenderer>
        <splineRenderer dataSource="categoryDS1" categoryColumn="BUILD_NAME">
          <line valueColumn="FIXED" legendLabel="Bugs Fixed"/>
        </splineRenderer>
        <categoryAxis label="Formspider Releases" name="cax" position="Bottom"/>
        <rangeAxis label="Bug Count" position="Left" default="Y"/>
        <legend position="Bottom"/>
      </categoryChart>
    </cell>
  </xyLayout>
</panel>

After saving the “mainPanel”, run the application which displays following chart. This chart shows the difference between splineRenderer and lineRenderer. splineRenderer is a smoother type of lineRenderer. Notice that we added categoryAxis and rangeAxis to the categoryChart, so they are displayed in the specified positions.

Category Chart with spline and line renderers

Category Chart with spline and line renderers

Category Chart Example – 3

In this example, we will use three different types of renderers in a single categoryChart. The two of them will use the already created datasource named “categoryDS1″ and we will create a datasource for the last one. So, create a datasource definition named “categoryDS2″ using the following query;

select 'FS Alpha 0.1' as build_name, '75' as feature from dual
union
select 'FS Alpha 0.2' as build_name, '65' as feature from dual
union
select 'FS Beta 0.5' as build_name, '45' as feature from dual
union
select 'FS Beta 0.6' as build_name, '47' as feature from dual
union
select 'FS Beta 0.7' as build_name, '33' as feature from dual
union
select 'FS 1.0' as build_name, '2' as feature from dual
union
select 'FS 1.1' as build_name, '5' as feature from dual
union
select 'FS 1.2' as build_name, '25' as feature from dual
union
select 'FS 1.3' as build_name, '15' as feature from dual

Notice that the data of the “categoryDS2″ contains more rows that the data of the “categoryDS”. Chart components merge the common categoryColumn values for all renderers and add uncommon values to the end of the categoryAxis.

Edit the “mainPanel” XML and save as follow;

<panel>
  <xyLayout>
    <cell x="10" y="10" width="500" height="500">
      <categoryChart title="Bugs and Features" backgroundColor="#C0C0C0" displayStyle="3D" plotBackgroundColor="#DEE4E5">
        <subtitle text="Formspider Project"/>
        <barRenderer dataSource="categoryDS1" categoryColumn="BUILD_NAME">
          <bar valueColumn="FOUND" legendLabel="Bugs Found" color="red" gradientColor="orange"/>
        </barRenderer>
        <lineRenderer dataSource="categoryDS1" categoryColumn="BUILD_NAME" labelFormat="#{value}">
          <line valueColumn="FIXED" legendLabel="Bugs Fixed" color="green"/>
        </lineRenderer>
        <itemRenderer dataSource="categoryDS21" categoryColumn="BUILD_NAME" labelFormat="#{value}">
          <item valueColumn="FEATURE" legendLabel="Features Added" color="blue"/>
        </itemRenderer>
        <categoryAxis position="Bottom"/>
        <rangeAxis name="RangeAxis" position="Left" default="Y"/>
        <legend border="N" position="Bottom" visible="Y"/>
      </categoryChart>
    </cell>
  </xyLayout>
</panel>

Now, save and run the application. You will see the following chart. In this category chart, we used 3 different renderers. Datasources of lineRenderer and barRenderer do not contain values for “FS 1.2″ and “FS 1.3″ categories so they are not displayed for those category values. Notice that we added displayStyle attribute with “3D” value to the categoryChart so it is displayed in 3D.

3D categoryChart with 3 different renderers

3D categoryChart with 3 different renderers

Category Chart Example – 4

In this chart, we will create multiple renderers that are attached to different range axises. We will use a new datasource definition named “categoryDS3″, so create it using the following query;

select 'Y-2001' as year, 1.21 as dollar, 1.7 as euro, 600 as gold from dual
union
select 'Y-2002' as year, 1.32 as dollar, 1.6 as euro, 800 as gold from dual
union
select 'Y-2003' as year, 1.38 as dollar, 1.71 as euro, 900 as gold from dual
union
select 'Y-2004' as year, 1.42 as dollar, 1.77 as euro, 1100 as gold from dual
union
select 'Y-2005' as year, 1.40 as dollar, 1.83 as euro, 1300 as gold from dual
union
select 'Y-2006' as year, 1.45 as dollar, 1.89 as euro, 1500 as gold from dual
union
select 'Y-2007' as year, 1.56 as dollar, 1.91 as euro, 1600 as gold from dual
union
select 'Y-2008' as year, 1.61 as dollar, 2.01 as euro, 2000 as gold from dual
union
select 'Y-2009' as year, 1.78 as dollar, 2.28 as euro, 2100 as gold from dual
union
select 'Y-2010' as year, 1.81 as dollar, 2.34 as euro, 2400 as gold from dual

Now, edit the “mainPanel” XML and save as follow;

<panel>
  <xyLayout>
    <cell x="10" y="10" width="500" height="500">
      <categoryChart title="Currency In TRY" backgroundColor="#C0C0C0" displayStyle="2D" plotBackgroundColor="#FFEEDD">
        <subtitle text="Dollor, Euro and Gold"/>
        <barRenderer rangeAxis="GoldAxis" dataSource="categoryDS31" categoryColumn="YEAR" >
          <bar valueColumn="GOLD" legendLabel="Gold" color="gold" gradientColor="orange"/>
        </barRenderer>
        <lineRenderer rangeAxis="MoneyAxis" dataSource="categoryDS31" categoryColumn="YEAR" >
          <line valueColumn="EURO" legendLabel="Euro" color="red"/>
        </lineRenderer>
        <itemRenderer dataSource="categoryDS31" categoryColumn="YEAR" >
          <item valueColumn="DOLLAR" legendLabel="Dollar" color="green"/>
        </itemRenderer>
        <categoryAxis label="Years" position="Bottom"/>
        <rangeAxis label="Currency in Try" name="MoneyAxis" position="Left" default="Y"/>
        <rangeAxis label="Gold Ons in Try" name="GoldAxis" position="Right"/>
        <legend border="N" position="Top" visible="Y"/>
      </categoryChart>
    </cell>
  </xyLayout>
</panel>

You will see the following chart. In this category chart, we used 3 different renderers. It contains 2 range axises, “MoneyAxis” and “GoldAxis”. “MoneyAxis” is the default(1) rangeAxis that is shown on the left side. itemRenderer, which does not explicitly specify it as a range axis with rangeAxis attribute, uses it. barRenderer uses “GoldAxis” and lineRenderer uses “MonexAxis” lineRenderer has a rangeAxis attribute with “RangeAxis” value so it also uses that range axis. itemRenderer explicitly specifies its range axis to be “RangeAxis-2″ which is shown on the right side.

(1) Tip: You can make a rangeAxis default by setting default attribute to “Y”. So that, all renderers that do not have rangeAxis attribute uses the default one.
categoryChart with multiple axises

categoryChart with multiple axises

XY Chart Example

In this example, we will create an xyChart to display bars, lines and items. So, you may start with either creating a new application or editing the existing one. Create a new datasource definition named “xyDS” using the following query;

select 1341 as c1, 50000 as r1, 22345 as r2, 34600 as r3 from dual
union
select 1458 as c1, 57000 as r1, 61000 as r2, 21800 as r3 from dual
union
select 1678 as c1, 34000 as r1, 48900 as r2, 35900 as r3 from dual
union
select 1792 as c1, 21000 as r1, 26789 as r2, 31100 as r3 from dual
union
select 1899 as c1, 23909 as r1, 45678 as r2, 51300 as r3 from dual
union
select 2100 as c1, 45999 as r1, 56784 as r2, 61500 as r3 from dual
union
select 2112 as c1, 33000 as r1, 37897 as r2, 51600 as r3 from dual
union
select 2341 as c1, 28765 as r1, 54678 as r2, 32000 as r3 from dual
union
select 2456 as c1, 67000 as r1, 23749 as r2, 22100 as r3 from dual
union
select 2678 as c1, 56888 as r1, 34389 as r2, 42400 as r3 from dual

Then, edit the “mainPanel” as follow;

<panel>
  <xyLayout>
    <cell x="10" y="10" width="500" height="500">
      <xyChart title="XY Chart Example" orientation="Horizontal" backgroundColor="#FFDDEE" plotBackgroundColor="#FFFFAA">
        <barRenderer dataSource="xyDS1" categoryColumn="C1">
          <bar valueColumn="R1" legendLabel="Bar" color="blue"/>
        </barRenderer>
        <lineRenderer dataSource="xyDS1" categoryColumn="C1">
          <line valueColumn="R2" legendLabel="Line" color="green"/>
        </lineRenderer>
        <itemRenderer dataSource="xyDS1" categoryColumn="C1">
          <item valueColumn="R3" legendLabel="Item" color="red"/>
        </itemRenderer>
        <categoryAxis label="Values in Category Axis" name="cax" position="Bottom"/>
        <rangeAxis label="Values in Range Axis" name="rax" position="Left" maximumValue="80000"/>
        <legend border="N" position="Bottom" visible="Y"/>
      </xyChart>
    </cell>
  </xyLayout>
</panel>

In this xyChart, we used 3 rendererers; barRenderer, lineRenderer and itemRenderer. All of the rendererers use same datasource named “xyDS1″. As you can see in the next screenshot, barRenderers in xyChart are displayed a little different than ones inside categoryCharts. They look like itemRenderers but their sizes differ according to values in valueColumns. Also, lineRenderers do not have dots to show values in specific positions. In addition, default value range in both category and range axises do not start from or end in 0. The chart arranges the display area according to values in order to enable a closer look to nodes(item, line, bar).

In Formspider, we recommend using categoryCharts to get a familiar charting look. However, in some cases xyChart can be viable option to display the change of the range axis values according to category axis values.

XY Chart Example

XY Chart Example

How to Create Multiple Plot Charts?

In this release, we simplified the charts and removed plot nodes inside xyCharts and categoryCharts. However, you can still create multiplot charts by using either “maximumValue” and “minimumValue” attributes or using same categoryColumn values. To use attributes method, you may put 2 charts into same sized cells in right-left position and set same values for “maximumValue” and “minimumValue” attributes of rangeAxises so that for same values items, bars, lines will be displayed in same y coordinate. For the second method, you may use two or more charts that share same categoryColumn values.

In this part, we will create an multiplot chart example using two categoryCharts. First create a new datasource definition named “categoryDS4″ using the following query:

select 'FS Alpha 0.1' as build_name, '35' as features, '39' as needed from dual
union
select 'FS Alpha 0.2' as build_name, '23' as features, '28' as needed from dual
union
select 'FS Beta 0.5' as build_name, '41' as features, '45' as needed from dual
union
select 'FS Beta 0.6' as build_name, '37' as features, '41' as needed from dual
union
select 'FS Beta 0.7' as build_name, '26' as features, '27' as needed from dual
union
select 'FS 1.0' as build_name, '19' as features, '23' as needed from dual
union
select 'FS 1.1' as build_name, '11' as features, '15' as needed from dual

Notice that we used same values for “build_name” column with “categoryDS” datasource definition. Datasources of these definitions will be used as categoryColumns in two categoryCharts. So, create a panel named “Tutorial-Plot1″ using the following xml;

<panel>
  <xyLayout>
    <cell x="0" y="0" width="500" height="300">
      <categoryChart title="Bugs and Features in Formspider Project" backgroundColor="#81FF54" displayStyle="2D" plotBackgroundColor="white">
        <lineRenderer dataSource="categoryDS1" categoryColumn="BUILD_NAME">
          <line valueColumn="FOUND" legendLabel="Bugs Found" color="red"/>
          <line valueColumn="FIXED" legendLabel="Bugs Fixed" color="green"/>
        </lineRenderer>
        <rangeAxis name="RangeAxis" position="Left" default="Y"/>
        <legend border="N" position="Top" visible="N"/>
      </categoryChart>
    </cell>
  </xyLayout>
</panel>

Now, create the second panel named “Tutorial-Plot2″ using the following xml;

<panel>
  <xyLayout>
    <cell x="0" y="0" width="500" height="350">
      <categoryChart backgroundColor="#81FF54" displayStyle="2D" plotBackgroundColor="white">
        <lineRenderer dataSource="categoryDS41" categoryColumn="BUILD_NAME">
          <line valueColumn="FEATURES" legendLabel="Features Added" color="gold"/>
          <line valueColumn="NEEDED" legendLabel="Features Needed" color="silver"/>
        </lineRenderer>
        <categoryAxis name="CAX" position="Bottom"/>
        <rangeAxis name="RangeAxis" position="Left" default="Y"/>
        <legend border="N" position="Bottom" visible="N"/>
      </categoryChart>
    </cell>
  </xyLayout>
</panel>

Next, edit the mainPanel using the following XML.;

<panel>
  <xyLayout>
    <cell x="10" y="10" width="500" height="300">
      <include panelName="Tutorial-Plot1"/>
    </cell>
    <cell x="10" y="310" width="500" height="350">
      <include panelName="Tutorial-Plot2"/>
    </cell>
    <cell x="520" y="260" width="20" height="20">
      <box backgroundColor="red"/>
    </cell>
    <cell x="520" y="285" width="20" height="20">
      <box backgroundColor="green"/>
    </cell>
    <cell x="520" y="310" width="20" height="20">
      <box backgroundColor="silver"/>
    </cell>
    <cell x="520" y="335" width="20" height="20">
      <box backgroundColor="gold"/>
    </cell>
    <cell x="547" y="260" height="20">
      <textLabel font-style="Bold" label="Bugs Found"/>
    </cell>
    <cell x="547" y="285" height="20">
      <textLabel font-style="Bold" label="Bugs Fixed"/>
    </cell>
    <cell x="547" y="310" height="20">
      <textLabel font-style="Bold" label="Features Needed"/>
    </cell>
    <cell x="547" y="335" height="20">
      <textLabel font-style="Bold" label="Features Added"/>
    </cell>
  </xyLayout>
</panel>

In the first categoryChart, we created two lines colored as “red” and “green” using the “categoryDS1″ datasource to display the number of found and fixed bugs in Formspider project releases. In the second categoryChart, we again created two lines colored as “gold” and “silver” using the “categoryDS41″ to display the number of features needed and added in Formspider project releases. In the “mainPanel”, we added first chart on top of second chart. First chart has title to be displayed for both of the charts and second chart has categoryAxis so that category values will be shared by both charts and displayed at the bottom.

In addition, we created legend-like look using textLabel and box components. As we know the colors of the lines used in both charts, we created 4 boxes that have backgroundColor attributes with values same as line colors and using textLabel components we set the labels of the legends. You may see generated multiplot chart in the next screenshot.

Multiplot Chart Example

Multiplot Chart Example

You may click here to run the application.

  • Ilia

    Hi,
    Can we set line width?
    Is there a full list of supported attributes and their values?
    Thanks,
    Ilia

  • Jeremy

    can you output the chart into an image (i.e. jpeg), could be image blob