Charts

The seamless integration of chart generation within Docxpresso is one of its more distinctive features.

One may create with a few lines of code truly sophisticated and fully customizable 2D and 3D charts.

Currently the following chart types are available:

• 2D:
  • column,
  • bar,
  • pie,
  • donut,
  • area,
  • line,
  • scatter,
  • bubble,
  • radar,
  • filled-radar and
  • column-line.
• 3D:
  • 3Dcolumn,
  • 3Dbar,
  • 3Dpie,
  • 3Ddonut,
  • 3Darea,
  • 3Dline and
  • 3Dscatter.

The support for charts in .docx format is still incomplete so you should double check the results or use .doc output format if MS Word is the target of your choice.

Like you can imagine the public API for the generation of charts is “pretty big” so, in order to facilitate your work, Docxpresso offers a number of auxiliary methods that allows to better organize your code. Namely:

• chart3DTransform: specifies the 3D rendering properties of a chart: rotation angles and perspective.
• chartAxis: allows to customize the different properties of the chart x, y and z axis: labels, tick lines, etcetera
• chartComponent: allows for the customization of the chart wall and floor: background-color and border lines.
• chartData: inserts the actual data together with its styling options: color, lines, etcetera.
• chartGrid: sets the chart grid properties for the different grids: major and minor.
• chartLegend: specifies the chart legend properties: position, font properties, etcetera.

It is, of course, not mandatory to specify all of this properties for every chart: some of them are completely optional and other will default to pre-established values that may serve your purposes most of the times.

Let us now pass to describe in detail the APIs of these different methods and illustrate their respective functionality with a few examples.

Beware that you may also generate your charts using Docxpresso extended HTML5 code: Advanced document components via extended HTML5.

Chart method

The chart method is the responsible to generate the basic chart that may be later decorated with the help of the other chart methods described above.

Its public API is given by:

The relevant CSS style type styles that one may apply globally to a chart include (where ‘*’ in this context stands for top, right, bottom or left).

• Size:
  • width: the chart width.
  • height: the chart height.
• Borders (individual borders are not supported):
  • border: shorthand for border properties.
  • border-color: sets the border color.
  • border-style: sets the border line style.
  • border-width: sets the border width.
• Display:
  • float: it can be left, right and also center.
  • margin: specifies all margin widths in one shot.
  • margin-*: specifies one margin at a time.
  • padding: specifies all padding widths in one shot.
  • padding-*: specifies one padding at a time.
  • position: absolute or relative.
  • top: distance from the top for absolutely positioned charts.
  • left: distance from the left for absolutely positioned charts.

Let us start by a simple example that will generate a plain column chart with all options left to their default values:

<?php
/**
 * This sample script inserts a basic column chart
 */
require_once 'pathToDOCXPRESSO/CreateDocument.inc';
$doc = new Docxpresso\CreateDocument();
$format = '.pdf';//.pdf, .doc, .docx, .odt, .rtf
//insert a basic column bar chart
$data = array(
                'series' => array('First series', 'Second series'),
                'Category 1' => array(20,40),
                'Category 2' => array(30,10),
                'Category 3' => array(12.5, 54),
              );
$doc->chart('column', array('data' => $data));
//include in the render method the path where you want your document to be saved
$doc->render('basic_column_chart' . $format); 
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'basic_column_chart' . $format . '">Download document</a>';

DOWNLOAD:

We could customize its positioning, size and borders by just adding the required style information:

<?php
/**
 * This sample script inserts a basic column chart
 */
require_once 'pathToDOCXPRESSO/CreateDocument.inc';
$doc = new Docxpresso\CreateDocument();
$format = '.pdf';//.pdf, .doc, .docx, .odt, .rtf
//insert a basic column bar chart
$data = array(
                'series' => array('First series', 'Second series'),
                'Category 1' => array(20,40),
                'Category 2' => array(30,10),
                'Category 3' => array(12.5, 54),
              );
$doc->paragraph()->style('text-align: center')
        ->chart('column', array('data' => $data))->style('border: 1pt solid #777; width: 12cm; height: 9cm; padding: 0.2cm');
//include in the render method the path where you want your document to be saved
$doc->render('basic_column_chart_2' . $format); 
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'basic_column_chart_2' . $format . '">Download document</a>';

DOWNLOAD:

Beware that currently the support for styling in Word and RTF is somehow limited, so if those are your target formats and you need to style the chart bounding box we recommend to use a wrapping table or textbox.

Chart data

If you need to customize further your data point chart styles you may use the chartData method.

Its public API is given by:

Following with our previous example we may change the data styles as follows:

<?php
/**
 * This sample script inserts a custom column chart
 */
require_once 'pathToDOCXPRESSO/CreateDocument.inc';
$doc = new Docxpresso\CreateDocument();
$format = '.pdf';//.pdf, .doc, .docx, .odt, .rtf
//insert a custom column bar chart
$data = array(
                'series' => array('First series', 'Second series'),
                'Category 1' => array(20,40),
                'Category 2' => array(30,10),
                'Category 3' => array(12.5, 54),
              );
$dataStyles = array(
                    array(
                          'fill-color' => '#b70000',
                          'stroke' => 'solid',
                          'stroke-color' => '#660000',
                          'stroke-width' => '2pt',
                          ),
                    array(
                          'fill-color' => '#0000b7',
                          'stroke' => 'solid',
                          'stroke-color' => '#000066',
                          'stroke-width' => '2pt',
                          ),
                    );
$doc->paragraph()->style('text-align: center')
        ->chart('column')->style('width: 12cm; height: 9cm;')
            ->chartData($data, $dataStyles);
//include in the render method the path where you want your document to be saved
$doc->render('custom_column_chart' . $format); 
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'custom_column_chart' . $format . '">Download document</a>';

DOWNLOAD:

Chart legend

In order to add a legend to our chart one should make use of the chartLegend method which public API is given by:

<?php
/**
 * This sample script inserts a column chart with a legend
 */
require_once 'pathToDOCXPRESSO/CreateDocument.inc';
$doc = new Docxpresso\CreateDocument();
$format = '.pdf';//.pdf, .doc, .docx, .odt, .rtf
//insert a column bar chart with a legend
$data = array(
                'series' => array('First series', 'Second series'),
                'Category 1' => array(20,40),
                'Category 2' => array(30,10),
                'Category 3' => array(12.5, 54),
              );
$doc->paragraph()->style('text-align: center')
        ->chart('column', array('data' => $data))->style('width: 14cm; height: 9cm; padding: 0.2cm')
            ->chartLegend();
//include in the render method the path where you want your document to be saved
$doc->render('legend_column_chart' . $format); 
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'legend_column_chart' . $format . '">Download document</a>';

DOWNLOAD:

You may further customize the display properties of the legend with the available option parameters, for example, in order to have the legend positiones in the top and with a border we should run the following code:

<?php
/**
 * This sample script inserts a column chart with a custom legend
 */
require_once 'pathToDOCXPRESSO/CreateDocument.inc';
$doc = new Docxpresso\CreateDocument();
$format = '.pdf';//.pdf, .doc, .docx, .odt, .rtf
//insert a column bar chart with a custom legend
$data = array(
                'series' => array('First series', 'Second series'),
                'Category 1' => array(20,40),
                'Category 2' => array(30,10),
                'Category 3' => array(12.5, 54),
              );
$doc->paragraph()->style('text-align: center')
        ->chart('column', array('data' => $data))->style('width: 12cm; height: 10cm; padding: 0.2cm')
            ->chartLegend(array('legend-position' => 'top', 'stroke' => 'solid', 'stroke-color' => '#cccccc'));
//include in the render method the path where you want your document to be saved
$doc->render('custom_legend_column_chart' . $format); 
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'custom_legend_column_chart' . $format . '">Download document</a>';

DOWNLOAD:

Chart axis

You may also customize all chart axis: x, y and z (in 3D charts) with the help of the chartAxis method which public API is given by:

For instance, if we want to customize the minimum and maximun values of the y axis and change the colors of the x and y axis lines, one should do the following:

<?php
/**
 * This sample script inserts a column chart with a custom legend and axis
 */
require_once 'pathToDOCXPRESSO/CreateDocument.inc';
$doc = new Docxpresso\CreateDocument();
$format = '.pdf';//.pdf, .doc, .docx, .odt, .rtf
//insert a column bar chart with a custom legend and axis
$data = array(
                'series' => array('First series', 'Second series'),
                'Category 1' => array(20,40),
                'Category 2' => array(30,10),
                'Category 3' => array(12.5, 54),
              );
$doc->paragraph()->style('text-align: center')
        ->chart('column')->style('width: 12cm; height: 10cm; padding: 0.2cm')
            ->chartData($data)
            ->chartLegend(array('legend-position' => 'top', 'stroke' => 'solid', 'stroke-color' => '#cccccc'))
            ->chartAxis('y', array('maximum' => 120, 'minimum' => 5, 'stroke-color' => '#b70000', 'stroke-width' => '2pt'))
            ->chartAxis('x', array('stroke-color' => '#b70000', 'stroke-width' => '2pt'));
//include in the render method the path where you want your document to be saved
$doc->render('axis_legend_column_chart' . $format); 
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'axis_legend_column_chart' . $format . '">Download document</a>';

DOWNLOAD:

Chart grid

If the default chart grid does not cover your needs you may use the chartGrid to customize the major as well as minor grid lines for the differents x, y and z axis (this last one only applicable to 3D charts).

Its public API is given by:

If, for example we would like to include the minor grid lines for the x axis in our last example we would only need to make a simple call to this method:

<?php
/**
 * This sample script inserts a column chart with a custom legend and axis and a minor grid
 */
require_once 'pathToDOCXPRESSO/CreateDocument.inc';
$doc = new Docxpresso\CreateDocument();
$format = '.pdf';//.pdf, .doc, .docx, .odt, .rtf
//insert a column bar chart with a custom legend and axis and a minor grid
$data = array(
                'series' => array('First series', 'Second series'),
                'Category 1' => array(20,40),
                'Category 2' => array(30,10),
                'Category 3' => array(12.5, 54),
              );
$doc->paragraph()->style('text-align: center')
        ->chart('column')->style('width: 12cm; height: 10cm; padding: 0.2cm')
            ->chartData($data)
            ->chartLegend(array('legend-position' => 'top', 'stroke' => 'solid', 'stroke-color' => '#cccccc'))
            ->chartAxis('y', array('maximum' => 120, 'minimum' => 5, 'stroke-color' => '#b70000', 'stroke-width' => '2pt'))
            ->chartAxis('x', array('stroke-color' => '#b70000', 'stroke-width' => '2pt'))
            ->chartGrid('x', 'minor');
//include in the render method the path where you want your document to be saved
$doc->render('grid_legend_column_chart' . $format); 
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'grid_legend_column_chart' . $format . '">Download document</a>';

DOWNLOAD:

Chart components: wall and floor

With the help of the charComponent one may customize the so called chart wall, i.e. the back of the chart plot area, and in 3D charts the chart floor.

Its public API is given by:

If, for example we would like to change the default wall and floor chart colors of the 3D version of the previous chart we need to:

<?php
/**
 * This sample script inserts a column bar chart with custom wall and floor components
 */
require_once 'pathToDOCXPRESSO/CreateDocument.inc';
$doc = new Docxpresso\CreateDocument();
$format = '.pdf';//.pdf, .doc, .docx, .odt, .rtf
//insert a column bar chart with custom wall and floor components
$data = array(
                'series' => array('First series', 'Second series'),
                'Category 1' => array(20,40),
                'Category 2' => array(30,10),
                'Category 3' => array(12.5, 54),
              );
$doc->paragraph()->style('text-align: center')
        ->chart('3Dcolumn')->style('width: 12cm; height: 10cm; padding: 0.2cm')
            ->chartData($data)
            ->chartLegend(array('legend-position' => 'top', 'stroke' => 'solid', 'stroke-color' => '#cccccc'))
            ->chartComponent('wall', array('fill-color' => '#ffff99'))
            ->chartComponent('floor', array('fill-color' => '#f0f0f0'));
//include in the render method the path where you want your document to be saved
$doc->render('wall_floor_column_chart' . $format); 
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'wall_floor_column_chart' . $format . '">Download document</a>';

DOWNLOAD:

3D Transformations

Whenever using 3D charts one may prefer a different perspective or view angle that the one offered by default by Docxpresso. If that is the case we may use the chart3DTransform method to customize the 3D display.

Its public API is given by:

The following code serves as an example of this method capabilities:

<?php
/**
 * This sample script modifies the default 3d view of a chart
 */
require_once 'pathToDOCXPRESSO/CreateDocument.inc';
$doc = new Docxpresso\CreateDocument();
$format = '.pdf';//.pdf, .doc, .docx, .odt, .rtf
//insert a 3D column bar chart and change its angle and perspective
$data = array(
                'series' => array('First series', 'Second series'),
                'Category 1' => array(20,40),
                'Category 2' => array(30,10),
                'Category 3' => array(12.5, 54),
              );
$doc->paragraph()->style('text-align: center')
        ->chart('3Dcolumn')->style('width: 12cm; height: 11cm; padding: 0.2cm')
            ->chartData($data)
            ->chartLegend(array('legend-position' => 'bottom'))
            ->chart3dTransform(array('right-angled-axes' => false, 'perspective' => 15, 'rotate-y' => 30));
//include in the render method the path where you want your document to be saved
$doc->render('transform_3D_column_chart' . $format); 
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'transform_3D_column_chart' . $format . '">Download document</a>';

DOWNLOAD:

Notice that the rendering of slanted lines in RTF format is not as good as expected so try to set the right-angled-axes option to true for this output format.

Let us finish this section by offering a few other examples with other chart types.

Miscellaneous examples

Pie charts

<?php
/**
 * This sample script inserts a 3D pie chart
 */
require_once 'pathToDOCXPRESSO/CreateDocument.inc';
$doc = new Docxpresso\CreateDocument();
$format = '.pdf';//.pdf, .doc, .docx, .odt, .rtf
//insert a 3D pie chart
$data = array(
              'category_1' => 3,
              'category_2' => 5,
              'category_3' => 4.3,
             );
$chartProperties = array('data-label-number' => 'percentage', 'label-position' => 'center');
$doc->paragraph()->style('text-align: center')
        ->chart('3DPie', array('data' => $data, 'chart-properties' => $chartProperties))
			->style('width: 14cm; height: 12cm')
			->chartLegend();
//include in the render method the path where you want your document to be saved
$doc->render('pie_chart' . $format); 
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'pie_chart' . $format . '">Download document</a>';

DOWNLOAD:

Donut charts

<?php
/**
 * This sample script inserts a exploded donut chart
 */
require_once 'pathToDOCXPRESSO/CreateDocument.inc';
$doc = new Docxpresso\CreateDocument();
$format = '.odt';//.pdf, .doc, .docx, .odt, .rtf
//insert a donut chart
$data = array(
              'category_1' => 3,
              'category_2' => 5,
              'category_3' => 4.3,
             );
$chartProperties = array('data-label-number' => 'percentage', 'label-position' => 'center', 'pie-offset' => 20);
$doc->paragraph()->style('text-align: center')
        ->chart('donut', array('data' => $data, 'chart-properties' => $chartProperties))
			->style('width: 14cm; height: 12cm')
			->chartLegend();
//include in the render method the path where you want your document to be saved
$doc->render('donut_chart' . $format); 
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'donut_chart' . $format . '">Download document</a>';

DOWNLOAD:

Area charts

<?php
/**
 * This sample script inserts an area chart
 */
require_once 'pathToDOCXPRESSO/CreateDocument.inc';
$doc = new Docxpresso\CreateDocument();
$format = '.odt';//.pdf, .doc, .docx, .odt, .rtf
//insert an area chart
$data = array(
                'series' => array('First series', 'Second series'),
                'Category 1' => array(20,40),
                'Category 2' => array(30,10),
                'Category 3' => array(12.5, 54),
              );
$dataStyles = array(
                    array(
                          'opacity' => '65%',
                          ),
                    array(
                          'opacity' => '65%',
                          ),
                    );
$doc->paragraph()->style('text-align: center')
		->chart('area')->style('width: 12cm; height: 9cm;')
			->chartData($data, $dataStyles)
			->chartLegend();
//include in the render method the path where you want your document to be saved
$doc->render('area_chart' . $format); 
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'area_chart' . $format . '">Download document</a>';

DOWNLOAD:

The RTF format has no support for transparencies in charts.

Line charts

<?php
/**
 * This sample script inserts a 3D line chart
 */
require_once 'pathToDOCXPRESSO/CreateDocument.inc';
$doc = new Docxpresso\CreateDocument();
$format = '.odt';//.pdf, .doc, .docx, .odt, .rtf
//insert a 3D line chart
$data = array(
                'series' => array('First series', 'Second series'),
                'Category 1' => array(20,40),
                'Category 2' => array(30,10),
                'Category 3' => array(12.5, 54),
              );
$dataStyles = array(
                    array(
                          'opacity' => '85%',
                          ),
                    array(
                          'opacity' => '85%',
                          ),
                    );
$doc->paragraph()->style('text-align: center')
		->chart('3Dline')->style('width: 12cm; height: 9cm;')
			->chartData($data, $dataStyles)
			->chartLegend();
//include in the render method the path where you want your document to be saved
$doc->render('line_chart' . $format); 
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'line_chart' . $format . '">Download document</a>';

DOWNLOAD:

Radar charts

<?php
/**
 * This sample script inserts a radar chart
 */
require_once 'pathToDOCXPRESSO/CreateDocument.inc';
$doc = new Docxpresso\CreateDocument();
$format = '.odt';//.pdf, .doc, .docx, .odt, .rtf
//insert a radar chart
$data = array(
                'series' => array('First', 'Second', 'Third'),
                'Cat 1' => array(20,40, 60),
                'Cat 2' => array(30,10, 10),
                'Cat 3' => array(12.5, 54),
                'Cat 4' => array(50, 20, 60),
                'Cat 5' => array(90, 54, 12),
              );
$doc->paragraph()->style('text-align: center')
		->chart('radar')->style('width: 12cm; height: 9cm;')
			->chartData($data)
			->chartLegend()
			->chartGrid('y', 'minor');
//include in the render method the path where you want your document to be saved
$doc->render('radar_chart' . $format); 
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'radar_chart' . $format . '">Download document</a>';

DOWNLOAD:

Bubble charts

<?php
/**
 * This sample script inserts a bubble chart
 */
require_once 'pathToDOCXPRESSO/CreateDocument.inc';
$doc = new Docxpresso\CreateDocument();
$format = '.odt';//.pdf, .doc, .docx, .odt, .rtf
//insert a bubble chart
//each data point array is given by (y, x, size) in pdf, odt and ref
//or (x, y, size) in doc format
$data = array(
               array(40, 10, 4),
               array(50, 20, 3),
               array(12, 30, 9),
               array(30, 40, 2),
               array(22, 50, 7),
              );
$doc->paragraph()->style('text-align: center')
		->chart('bubble')->style('width: 12cm; height: 9cm;')
			->chartData($data)
			->chartGrid('y', 'minor');
//include in the render method the path where you want your document to be saved
$doc->render('bubble_chart' . $format); 
//echo a link to the generated document
echo 'You may download the generated document from the link below:<br/>';
echo '<a href="' . 'bubble_chart' . $format . '">Download document</a>';

DOWNLOAD:

Beware that the Word (.doc) format interchanges the x and y axis with respect the PDF, ODT and RTF formats.