Chart Macro

Last modified by Admin on 2024/03/19 06:46

chart_pieMacro for displaying charts
TypeJAR
Category
Developed by

XWiki Development Team

Rating
0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Standard

Installable with the Extension Manager

Description

Usage

Currently chart macro supports two types of data sources. Usage of the macro slightly differs from "xdom" mode to "inline" mode:

Usage for "xdom" data sources:

{{chart source="xdom" type="<type>" params="<params>" title="<title>" height="<height>" width="<width>"/}}

Usage for "inline" data sources:

{{chart source="inline" type="<type>" params="<params>" title="<title>" height="<height>" width="<width>"}}
// Put your data table definition here using the current page's syntax
{{/chart}}

Parameters definition

NameOptionalAllowed valuesDefault valueDescription
typenoline, area, bar, stackedbar, bar3D, stackedbar3D, pie, line3D, xy_area, xy_line_and_shape, xy_line3D and xy_stepnoneType of chart to be generated. xy_area and xy_line_and_shape have been added in XWiki 4.0M1. bar3D and line3D have been added in XWiki 4.1. xy_line3D and xy_step have been added in XWiki 4.2M3. stackedbar and stackedbar3D have been added in XWiki 6.0M1
sourceyesxdom or inlineinline if the macro has content (the content needs to be written using the page's syntax) or xdom otherwise New in XWiki 4.3. Before 4.3, xdom was always the defaultType of the data source which provides input for charting.
paramsyesstringnone

Additional parameters for the data source. This string contains a list of parameter name to value mappings. Available parameter names and values depend on the data source being used (refer to the examples below).

Note that when specifying a range (as in range:B2-D5) you can use the #.# (dot) character to specify the maximum column or line. For example range:B2-D. means till the max line and range:B2-.. means last column and last line.

titleyesstringnoneA title string to be used when rendering the chart
widthyesstring400Width of the chart image in pixels
heightyesstring300Height of the chart image in pixels
colorsyesstringnoneList of custom colors to use, specified in hexadecimal. Example: FF0000,00FF00,0000FF Since XWiki 4.1

Generic Parameters

Parameter nameDefault valueDescription
backgroundColorGrey backgroundBackground color of the non-chart area, specified using an hexadecimal notation, e.g. FFAACC (first 2 letters are for Red, following 2 are for Green and last 2 are for Blue). Since XWiki 7.4.3, 8.0
plotBackgroundColorWhiteBackground color of the plot area, specified using an hexadecimal notation (see backgroundColor). Since XWiki 7.4.3, 8.0
plotBorderColorBlackColor of the plot border, specified using an hexadecimal notation (see backgroundColor). Since XWiki 7.4.3, 8.0
borderColorBlackColor of the outer graph border, specified using an hexadecimal notation (see backgroundColor). Since XWiki 7.4.3, 8.0
legendBackgroundColorWhiteBackground color of the legend box, specified using an hexadecimal notation (see backgroundColor). Since XWiki 7.4.3, 8.0
plotBorderVisibletrueWhether the border for the plot area is visible or not. Valid values are true and false. Since XWiki 7.4.3, 8.0
legendVisibletrueWhether the legend is displayed or not. Valid values are true and false. Since XWiki 7.4.3, 8.0

Pie Chart Parameters

Parameter nameDefault valueDescription
pie_label_format{0}The format of the label for pie segments. Use {0} where the pie section key should be inserted, {1} for the absolute section value and {2} for the percent amount of the pie section, e.g. {0} = {1} ({2}) will display as "apple = 120 (5%)". Since XWiki 6.1

Examples

Example for an "xdom" data source Bar chart

An "xdom" data source can be used when you need to draw charts from data tables located anywhere in the wiki. For an example, let's say xwiki:Main.Data wiki page contains the following data table definition:

(%id="table1"%)
|=|=X|=Y|=Z
|Q1|1.2|3.4|1.3
|Q2|4.5|3.4|2.3
|Q3|1.2|4.5|9.0
|Q4|3.4|1.2|1.2

Then you can draw a chart from this data table with following syntax (from any wiki page):

{{chart type="bar" params="document:<document_source_name>;table:table1;range:B2-D5;series:columns;" title="Chart Test" width="320" height="240"/}}

For our example with Main.Data, the syntax is:

{{chart type="bar" params="document:Main.Data;table:table1;range:B2-D5;series:columns;" title="Chart Test" width="320" height="240"/}}

NOTE: As you can see here, the "params" string is used to clearly define input data source:

  • Wiki page: "document:Main.Data;"
  • Name of the data table: "table:table1;" (the table must have an id)
  • Data range: "range:B2-D5;" (just like you'd select a data range on an excel sheet)
  • Orientation: "series:columns;" (defines the x and y axes)

Result:

chart1.png

Example for an "inline" data source Pie chart

Example for a page using XWiki Syntax 2.0 or XWiki Syntax 2.1 (the table syntax is in XWiki Syntax 2.0 or XWiki Syntax 2.1).

{{chart type="pie" source="inline" params="range:B2-D5;series:columns;" title="Chart Test" width="320" height="240"}}
|=|=X|=Y|=Z
|Q1|1.2|3.4|1.3
|Q2|4.5|3.4|2.3
|Q3|1.2|4.5|9.0
|Q4|3.4|1.2|1.2
{{/chart}}

Result:

charttest.png

See also the Syntax Distribution Chart Snippet for another example.

Example of a Time Series chart

Using "xy_line_and_shape"

Example for a page using XWiki Syntax 2.0 or XWiki Syntax 2.1 (the table syntax is in XWiki Syntax 2.0 or XWiki Syntax 2.1).

{{chart type="xy_line_and_shape" params="range:B2-C19;dataset:timetable_xy;domain_axis_type:date;domain_axis_date_format:MMM-yyyy;date_format:yyyy-MM;time_period:month;range_axis_lower:100;range_axis_upper:190"}}
|=|=Series1|=Series2
|2001-2|181.8|129.6
|2001-3|167.3|123.2
|2001-4|153.8|117.2
|2001-5|167.6|124.1
|2001-6|158.8|122.6
|2001-7|148.3|119.2
|2001-8|153.9|116.5
|2001-9|142.7|112.7
|2001-10|123.2|101.5
|2001-11|131.8|106.1
|2001-12|139.6|110.3
|2002-1|142.9|111.7
|2002-2|138.7|111.0
|2002-3|137.3|109.6
|2002-4|143.9|113.2
|2002-5|139.8|111.6
|2002-6|137.0|108.8
|2002-7|132.8|101.6
{{/chart}}

Result:

timeseries.png

Using "xy_line3D"

Example for a page using XWiki Syntax 2.0 or XWiki Syntax 2.1 (the table syntax is in XWiki Syntax 2.0 or XWiki Syntax 2.1).

{{chart type="xy_line3D" params="range:B2-C19;dataset:timetable_xy;domain_axis_type:date;domain_axis_date_format:MMM-yyyy;date_format:yyyy-MM;time_period:month;range_axis_lower:100;range_axis_upper:190"}}
|=|=Series1|=Series2
|2001-2|181.8|129.6
|2001-3|167.3|123.2
|2001-4|153.8|117.2
|2001-5|167.6|124.1
|2001-6|158.8|122.6
|2001-7|148.3|119.2
|2001-8|153.9|116.5
|2001-9|142.7|112.7
|2001-10|123.2|101.5
|2001-11|131.8|106.1
|2001-12|139.6|110.3
|2002-1|142.9|111.7
|2002-2|138.7|111.0
|2002-3|137.3|109.6
|2002-4|143.9|113.2
|2002-5|139.8|111.6
|2002-6|137.0|108.8
|2002-7|132.8|101.6
{{/chart}}

Result:

timeseries-line3D.png

Using "xy_step"

Example for a page using XWiki Syntax 2.0 or XWiki Syntax 2.1 (the table syntax is in XWiki Syntax 2.0 or XWiki Syntax 2.1).

{{chart type="xy_step" params="range:B2-C19;dataset:timetable_xy;domain_axis_type:date;domain_axis_date_format:MMM-yyyy;date_format:yyyy-MM;time_period:month;range_axis_lower:100;range_axis_upper:190"}}
|=|=Series1|=Series2
|2001-2|181.8|129.6
|2001-3|167.3|123.2
|2001-4|153.8|117.2
|2001-5|167.6|124.1
|2001-6|158.8|122.6
|2001-7|148.3|119.2
|2001-8|153.9|116.5
|2001-9|142.7|112.7
|2001-10|123.2|101.5
|2001-11|131.8|106.1
|2001-12|139.6|110.3
|2002-1|142.9|111.7
|2002-2|138.7|111.0
|2002-3|137.3|109.6
|2002-4|143.9|113.2
|2002-5|139.8|111.6
|2002-6|137.0|108.8
|2002-7|132.8|101.6
{{/chart}}

Result:

timeseries-step.png

Stacked Bar Example

{{chart type="stackedbar" params="document:<document_source_name>;table:table1;range:B2-D5;series:columns;" title="Chart Test" width="320" height="240"/}}

Result:

stackedbar.png

3D Examples

Example for a page using XWiki Syntax 2.0 or XWiki Syntax 2.1 (the table syntax is in XWiki Syntax 2.0 or XWiki Syntax 2.1).

{{chart type='bar3D' source='inline' params='range:B2-B9;series:columns'}}
|=Date|=Value
|2012-02-21|1.97
|2012-02-26|2.96
|2012-03-04|3.93
|2012-03-11|4.84
|2012-03-18|5.83
|2012-03-25|4.5
|2012-04-01|3.85
|2012-04-08|4.87
{{/chart}}

Result:

3dbar.png

{{chart type="stackedbar3D" params="document:Main.Data;table:table1;range:B2-D5;series:columns;" title="Chart Test" width="320" height="240"/}}

Result:

stackedbar3D.png

Custom Colors Example

This example works only in XWiki 4.1+

Example for a page using XWiki Syntax 2.0 or XWiki Syntax 2.1 (the table syntax is in XWiki Syntax 2.0 or XWiki Syntax 2.1).

{{chart type="pie" source="inline" params="range:B2-D5;series:columns;colors:C3E3F7,1D9FF5,015891,012A45" title="Chart Test" width="320" height="240"}}
|=|=X|=Y|=Z
|Q1|1.2|3.4|1.3
|Q2|4.5|3.4|2.3
|Q3|1.2|4.5|9.0
|Q4|3.4|1.2|1.2
{{/chart}}

Result:

customcolors.png

Line chart without shapes for data points

This example works only in XWiki 5.2M2+

Example for a page using XWiki Syntax 2.0 or XWiki Syntax 2.1 (the table syntax is in XWiki Syntax 2.0 or XWiki Syntax 2.1).

The line chart type supports two additional parameters to hide the shapes used to display the data points or to hide the interpolation lines that connect the data points.

{{chart type="line" source="inline" params="range:B2-D3;series:columns;colors:FF0000,FFA500,000000;hideShapes:true" title="Disk Usage" width="400" height="200"}}
|=Date|=Warning|=Critical|=% Used
|1|90|80|85
|20|90|80|93
{{/chart}}

lineWithoutShapes.png

Pie chart with white background

Pie chart with no legend displayed, no border, no title and white background.

Example for a page using XWiki Syntax 2.0 or XWiki Syntax 2.1 (the table syntax is in XWiki Syntax 2.0 or XWiki Syntax 2.1).

{{chart type="pie" source="inline" params="range:B2-D5;series:columns;backgroundColor:FFFFFF;plotBackgroundColor:FFFFFF;plotBorderVisible:false;legendVisible:false" width="320" height="240"}}
|=|=X|=Y|=Z
|Q1|1.2|3.4|1.3
|Q2|4.5|3.4|2.3
|Q3|1.2|4.5|9.0
|Q4|3.4|1.2|1.2
{{/chart}}

pieChartWhite.png

Advanced Customization

Since XWiki 7.4.3, 8.0 For advanced customizations, you can implement the org.xwiki.chart.ChartCustomizer component role to have access to the org.jfree.chart.JFreeChart object, allowing you to fully customize the generated charts.

This can be implemented either as a component in Java or using wiki components.

The ChartCustomizer interface:

@Role
public interface ChartCustomizer
{
   /**
     * @param jFreeChart the JFree Chart instance representing the graph, on which customizations can be performed
     * @param parameters the parameters passed to the Chart generator and controlling its aspect (e.g. the Chart Macro
     *                   allows user to pass those parameters as a string, for example
     *                   {@code range:B2-D5;series:columns;colors:C3E3F7,1D9FF5,015891,012A45}
     */

   void customize(JFreeChart jFreeChart, Map<String, String> parameters);
}

Example implementation in Java:

/**
 * Customize visiblity of items on the chart.
 *
 * @version $Id: 35065820fcab9859b41f18a2526365756a882d7d $
 * @since 7.4.3, 8.0RC1
 */

@Component
@Named("visibility")
@Singleton
public class VisibilityChartCustomizer implements ChartCustomizer
{
   /**
     * Whether the plot border is visible or not.
     */

   private static final String PLOT_BORDER_VISIBLE = "plotBorderVisible";

   /**
     * Whether the legend is visible or not.
     */

   private static final String LEGEND_VISIBLE = "legendVisible";

   @Override
   public void customize(JFreeChart jfchart, Map<String, String> parameters)
   {
       if (parameters.get(PLOT_BORDER_VISIBLE) != null) {
            jfchart.getPlot().setOutlineVisible(Boolean.parseBoolean(parameters.get(PLOT_BORDER_VISIBLE)));
       }

       if (parameters.get(LEGEND_VISIBLE) != null && !Boolean.parseBoolean(parameters.get(LEGEND_VISIBLE))) {
            jfchart.removeLegend();
       }
   }
}

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).

You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.

Dependencies

Dependencies for this extension (org.xwiki.platform:xwiki-platform-chart-macro 16.1.0):

Tags:
    

Get Connected