EXT: Charts¶

What does it do?¶

The arCharts extension creates chart graphics of various types, from static or dynamic data. Charts can be adapted to fit the needs through a variety of configuration options (sizes, colors, scaling, axes, labelling, free texts, ...) and come in a look fit for professional use.

The extension uses its own rendering engine. Creation process is fast enough to be done on the fly. Additionally, an internal caching mechanism is used which prevents identical images to be created twice.

For convenient use, handling of the extension is divided in roles of “chart definition” and “chart use”. The first defines chart types, sizes, contents, data source etc. - all the technical stuff; the defined chart can then easily be put onto pages without much ado. Definitions are made through forms rather than through Typoscript, allowing the developer to fast and easily test all configuration options.

The extension tries to combine the most of “vast possibilities”, “ease of use”, “minimum server load” and “maximum security”.

Charts created by the extension¶

A “Lines” chart:

The same chart, but rotated and flipped, and with line thickness increased:

The same data as before, but switched to “points” type and with a horizontal grid:

Again the same chart, now switched to “mountains” type:

The same data as “stacked bars row” chart:

A “Grouped bars” chart:

The same data in the same chart, a little modified in the look, and flipped horizontally:

A “parallel bars” chart:

One data as “stacked bar”, “pie 2D”, “parliament” and two versions of “pie 3D” chart:

General overview¶

A configurable chart has quite a few options to decide about: which chart type? Dimensions? Axes? Scaling? Line thickness? Rotation? And so on... Imagine you did all those decisions directly on the page where you want to use the chart. Whenever you want to use a similar chart, you either have to create it anew with all the options, or remember where you used that chart and copy it - in very short time there will be quite a chaos.

That's one of the reasons arCharts separates into "chart definition" and "chart use". Charts are defined in one place, they get a name and possibly a short description, then stored as "chart models" into Sysfolders. When you want to use a chart, you select one from the defined chart models, and you're done in a moment.

Aside from preventing chaos and allowing fast use on the page, this two-step approach allows a role division: all the technical and details stuff in one hand, decisions about page content in the other.

Actually, there is a third step - but it is mostly invisible. The administrator can restrict certain selections to acceptable options, and can set an overall limit to the image size. By default, no such limitation is set;. For details, see "Administration -> Global Configuration Options".

Defining chart models¶

As explained in the section before, you need a chart model to be able to use a chart on a page. The chart model can be seen as the form where tha actual data is put into, and which defines how the data is displayed.

Chart models are defined through a form that shows up when you create a new record of "Chart model" type.

Typically, you would set up a sysfolder to store the models (you need a place to store the models in). In the sysfolder, switch to "List" module, click on "Create new Record" and choose "Chart model" as record type: a form will show up, in which all configuration can be done.

The form shows a number of tabs, which organize the many configuration options. All options are explained in “Reference: Chart types, properties, and options”; but most of them are self-explaining.

A good way to go through the tabs is:

Start in the “General” tab by giving the chart model a name - it's required, you can't store the model without it.

Next click on the “Dimensions” tab: how big should the image be, how big the chart in the image, and where should the chart be placed on the image?

the “Data source” tab: which data sources should be allowed?

in the “Paths” tab, defaults should be OK for the beginning.

in the “Free texts” tab, you can enter up to five texts to be positioned anywhere on the image.

Now the interesting part starts: in the “Chart type” tab, choose a chart type. The form will reload, and the chart specific options will be presented.

In the “Chart Extras” tab, you can decide on extras like rotation, flip, axes (which include scaling), zero line and global label group. Which options are shown depends on the chart type - for example, an axis wouldn't make sense for a pie chart, so this option is not visible.

Depending on your choices in the “Chart Extras” tab, other tabs become visible, allowing configuration of the extras you chose.

An easy, intuitive way to set up a chart model is described in “Tutorials -> Setting up a chart model the easy way”. If you want to have the details on what you can configure, have a look at "Configuration -> Reference: Chart types, properties, and options".

Tip: when the number of chart models grows, you can put the models into different sysfolders to achieve better overview. When selecting a chart model to put a chart onto a page, the user can limit the list of shown models so that only models from certain folders are listed.

Putting a chart onto a page¶

First of all, if you want a chart, you need at least one chart model ready for use. If you don't have that, a look at the previous sections "General overview" and "Defining chart models" might be useful.

There are two ways to get a chart onto a page. The standard way is creating a new “page content” record; the other way calling the plugin by Typoscript.

Calling the plugin by Typoscript needs some developer knowledge. Please refer to “Configuration -> Reference: Typoscript”, or have a look at “Tutorials -> Example: call the plugin via Typoscript” for details.

The standard way, however, is easy.

When you clock “create new record”, choose the “Chart” type from the list of selectable record types. It might be at the bottom of the list. In the form that shows up, click the “plugin” tab. All the following inputs are located in that tab.

Go top to bottom through the inputs that are shown:

With the “Data Input Type ” selector, choose between passing data dynamically to the plugin or entering manually (“direct input”). After that selection is done, the form reloads.

Select a model. When you do, and when the person who defined the chart model took the time, the “internal infotext” field will show information related to the selected model.The “Chart model” select is filled with all models that allow the chosen data input type. If the list is too long, you can narrow the selection with the “Chart Model Folders” input. Select one or more sysfolders, save the form, and only models that are stored in the selected folders show up in the list.

If you chose “dynamic data” as data input type, select the data source. It can be “typoscript” or “PHP Hook” depending on the model. Of course, using one of these needs an appropriate data source set up to make it work; see next chapter, "Passing data to the chart".

Optional: choose a file format - PNG is default and typically has the best look. Depending on the file format, an input “JPG Quality” of “PNG compression” may show up - their default values are quite OK, change them if you want. You can change again later, if you want (as almost everything).

Optional: choose a background color - white is default

Optional: if you want to make sure that the chart model you chose always remains the same, set “Store model locally” to “yes”. If set to “no”, updates in the model will reflect directly on the page - which, by the way, is an excellent way to set up a model and test all the options of model definition (using a hidden page)

Disregard the “Restart Image Caching” button for now (see “Configuration -> Reference: Flexform options” for details)

If you chose “direct input” as data input type,you have to provide the data. Have a look at the next chapter, "Passing data to the chart".

You see: the jobs that needs some work are “defining a model” and “setting up the data source”. Just putting the chart on the page is the easy one.

Passing data to the chart¶

A note on the image file names¶

The image file names look a bit ugly. They consist of a prefix (“chart_” is the default), followed by a long random-looking string. This is due to the internal caching mechanism that prevents an already existing image to be created a second time (thus speeding things up). The file names are made up from a hash that is unique for the very information displayed in the image: if you change one parameter, the image will get a new file name.

If you need a human readable file name, consider using “Store Copy As”, which creates a copy of the chart under a name that is free to choose - see "Reference: Chart types, properties, and options -> Chart Model Parameters ->Paths->Store Copy As" for details.

Installation¶

Install the extension via Extension Manager.

Extension Manager will ask to create two tables in the database, and to create the folder “uploads/tx_archarts/”; confirm.

Extension Manager will show global configuration options for the extension (see “Global Configuration Options” below); change them or leave them as they are, and click “make updates”.

That's all - now you can start creating charts (see “User manual” below).

Global Configuration Options¶

Note - for better understanding of the options mentioned here, you might want to read the first paragraph of the “Users manual” chapter, “General overview”, which describes the overall data organization.

Global configuration options enable the server administrator to disallow certain configuration options.

During installation, they show up automatically ; later, they are reached in Extension manager by a click on the extension name.

The options are:

• Acceptable Data Sources - defines which data sources can be selected for model definition. Value must be set to a comma-separated list consisting of one or more from typoscript - data is given by from typoscript phpHook - data is given by PHP hook directInput - data is entered manuallyAs default, all of these sources are allowed.
• Acceptable Chart Types - defines which chart types may be used. Value must be set to a comma-separated list consisting of one or more from pie2d, pie3d, parliament, lines, mountains, points, parallelBars, groupedBars, stackedBar, stackedBarsRow .As default, all of these values are allowed.
• Acceptable File Formats - defines which file formats may be used. Value must be set to a comma-separated list consisting of one or more from png, jpg, gif.As default, all of these values are allowed.
• Maximum Image Area - defines up to how many pixels an image may contain (width * height), both during creation and in final image. If the adminstrator wants to set an overall limit to protect the server (or to avoid a PHP error message because it tried allocating too much memory), this is the place to do it. If not set, or set to zero, no limit is in effect.As default, the value is set to “0”, so no limit is in effect.

Permissions¶

The only built-in permission issues outside the global configuration options (see above) regard the storage of the image files.

The file name under which the chart images are stored consists of

• a prefix defined in the model,
• a hash made from all parameters used for image creation,
• and the file extension, depending on the file format chosen.

The file is stored in a folder that is defined in the model.

Both “Charts File Prefix” and “Charts Storage Folder” are Typo3 “Exclude Fields”, which only an admin user can change.

The values default to “chart_” and “uploads/tx_archarts/”.

File storage & removal¶

Chart images are stored in a Charts Storage Folder that is defined within the chart model.

The file name is made from a prefix defined in the model, then a md5-hash of the image content, and the file extension according the the file format defined on the page (flexform or typoscript).

Over the time, a lot of images might be created. For the moment, the extension doesn't care of your server's disk space; so you might want to set up a cronjob to remove old files.

Error handling¶

When an error occurs that prevents the script from further work, the internal error message is written to the Typo3 syslog, the plugin does no further processing, and a replacement image or nothing is shown where the chart should be.

Standard error handling can be overridden by hook; see “Configuration -> Hooks -> internalError Hook” for details.

Be sure to turn the syslog on (in install tool), if you want to make use of this feature.

List of supported chart types¶

Currently, these chart types are supported:

• Pie Types: Pie 2D, Pie 3D, Parliament
• Line Types: Lines, Points, Mountains
• Bar types: Parallel Bars, Grouped Bars, Stacked Bar, Stacked Bars Row

Chart type characteristics and requirements¶

There are some characteristics which are shared by groups of chart types. These characteristics determine some of the options which are available for the charts.

Reference: Chart types, properties, and options¶

Note: if this reference helps you somehow - great; but you don't really have to read this if you just want to set up a chart model. Most options do what you'd expect them to do. Have a look at “Tutorials -> Setting up a chart model the easy way” for - well, an easy, intuitive way to set up a chart model.

The reference list contains all parameters available when defining a chart model. It is ordered following the tabs where the options appear.

Reference: Typoscript¶

Reference: Flexform options¶

Reference: Templates¶

The following two templates are used:

• ###TPL_CHART### This template is used to wrap the chart image.There is one marker that can be used: ###HREF_CHART_IMAGE### - gets replaced by path to the chartBy default, this template just wraps the image source in an img-tag, and adds “chart” as alt text.
• ###TPL_ERROR### This template is used when an internal error occurs.There are two markers that can be used:- ###MESSAGE_TEXT### - gets replaced with the localized content of “internalError” as defined in pi1/locallang.xml- ###BLANK_IMAGE_SRC### - gets replaced by the path to the replacement image as defined in the modelBy default, this template is empty, so neither image nor error message is shown on the page.

The template file that is used is defined per model. By default, pi1/templates.html is used as the file from where to take the templates. If you customize its content, consider moving the file out of the extension folder, as updates will otherwise overwrite your customized file.

Reference: Hooks¶

There are two hooks built into the extension: one hook to set data by PHP, and one hook to customize error handling.

$TYPO3_CONF_VARS[ 'EXTCONF' ][ 'ar_charts' ][ 'setData' ][] = 'user_example_hooks->setArchartsData';

$datasets = array(
  0 => array(
    'values' => 10 // numeric value
    'color' => '#ff0000' // hex RGB color
    'label' => 'Value A' // string
  ),
  1 => array(
    'values' => 20 // numeric value
    'color' => '#ffff00' // hex RGB color
    'label' => 'Value B' // string
  ),
  2 => ...
  ...
);

$datasets = array(
  0 => array(
    'values' => 10, 20, 40 // string containing comma-separated numeric values (at least 2)
    'color' => '#ff0000' // hex RGB color
    'label' => 'Value A' // string
  ),
  1 => array(
    'values' => '20, 10, 35' // string containing comma-separated numeric values (at least 2)
    'color' => '#ffff00' // hex RGB color
    'label' => 'Value B' // string
  ),
  2 => ...
  ...
);

$indexLabels = '2001,2004,2007';
$indexLabelsDivider = ',';

$indexLabels = '2001-2004-2007';
$indexLabelsDivider = '-';

class user_example_hooks
{
  public function setArchartsData( $parameters=array(), &$callingExtObject )
  {
    $datasets = array( ... );
    $indexLabels = '2001-2004-2007';
    $indexLabelsDivider = '-';

    $callingExtObject->setContentDataFromPhp( $datasets, $indexLabels, $indexLabelsDivider );
  }
}

$TYPO3_CONF_VARS[ 'EXTCONF' ][ 'ar_charts' ][ 'internalError' ][] = 'user_example_hooks->showErrorMessage';

$parameters = array(
  'errorMesssage' => $msg,
  'doNotLog' => false,
  'unsetErrorState' => false,
  'chartParams' => $this->chartParams,
  'dataContent' => $this->dataContent,
  'chartVars' => $this->chartVars,

Error handling / debugging¶

By default, internal errors result in the error template (see “Templates”) being shown - if you did not customize the templates, this means that simply nothing is displayed where the chart should be.

All errors are logged in the Typo3 syslog by default. To take advantage of this, you have to enable syslog in the Install Tool.

Error handling can be customized by a Hook - see “Reference: Hooks -> internalError Hook” above for details.

Setting up a chart model the easy way¶

Start setting up a chart model (see "Users manual -> Defining chart models"), up to the point where you are able to store and use it - that is, model name, chart type and data source must be set. Set data source to “typoscript”.

Store the model

Create a hidden page

Put the Chart plugin on that page (see "Users manual -> Putting a chart onto a page"), and in the plugin choose the model you started to create

Set up some fake data, e.g. by copy/paste of the example data given in this manual (see "Tutorials -> Example: pass data via Typoscript")

Go back to the model definition and continue.

Let Typo3 show you a preview of the hidden page

Each change in the model will reflect directly in the preview, so hit reload fat the preview page whenever you want to see what a change in the model definition did

Play around with model and fake data until you're OK with the result

Keep the model, discard the hidden page

Example: pass data via Typoscript¶

Note: if you want to set data via Typoscript AND call the plugin via Typoscript, please refer to "Example: call the plugin and pass data via Typoscript and not to this chapter.

For “single index” chart types (see "Configuration -> Chart type characteristics and requirements" for explanation of the term), copy this snippet into the TS-setup of the page's template:

plugin.tx_ar_charts_pi1 {
  chart {
    datasets{
      0 {
        values = TEXT
        values.value = 10
        label = TEXT
        label.value = Series A
        color = TEXT
        color.value = #ffcc00
      }
      1 {
        values = TEXT
        values.value = 10
        label = COA
        label {
          10 = TEXT
          10.value = that's a typo
          20 = TEXT
          20.value = script COA
        }
        color = TEXT
        color.value = #00ccff
      }
    }
  }
}

For “multi index” chart types (see "Configuration -> Chart type characteristics and requirements" for explanation of the term), copy this snippet into the TS-setup of the page's template:

plugin.tx_ar_charts_pi1 {
  chart {
    datasets{
      0 {
        values = TEXT
        values.value = 10, 20, 30
        label = TEXT
        label.value = Serie A
        color = TEXT
        color.value = #ffcc00
      }
      1 {
        values = TEXT
        values.value = 5, 40, 25
        label = TEXT
        label.value = Serie B
        color = TEXT
        color.value = #00ccff
      }
    }
    indexLabels = TEXT
    indexLabels.value = 1999|2004|2009

    indexLabelsDivider = TEXT
    indexLabelsDivider.value = |
  }
}

2) In the model, set "data source" to "typoscript" and make sure “Data variable name” is set to “data” (as is default). And, of course, set chart type, dimensions etc.

3. Clear caches, and see the data in the chart.

Example: call the plugin via Typoscript¶

Note: if you want to call the plugin by Typoscript AND set data in Typoscript, please refer to "Example: call & pass data via Typoscript" and not to this chapter.

1) Copy this snippet into the TS-setup of the page's template (replace the “modelId” value with an existing model Id, and the “dataSource” value to a value that is allowed in the model):

userLibs.tx_archarts_pi1 = EXT:ar_charts/pi1/class.tx_archarts_pi1.php
temp.ar_chart{
  userFunc = tx_archarts_pi1->main

  getPath = 0
  absolutePath = 0

  modelId = 1
  dataSource = phpHook
  imageFileFormat = png
  pngCompression = 0
  backgroundColor = #ffffff
}

2) In the code, replace the “modelId” value with an existing model Id, and the “dataSource” value to a value that is allowed in the model.

3. Still in the template TS-setup, use something like

page.10 < temp.ar_chart

to copy the plugin output to the place you want. Place this behind the first snippet, else “temp.ar_chart” won't most likely contain anything.

4) In the model, make sure that data source, chart type, dimensions etc. are set.

5. Clear caches, and see the chart on the page.

Example: call & pass data via Typoscript¶

Note: if you want to call the plugin by Typoscript OR set data in Typoscript, please refer to "Example: call the plugin via Typoscript" or "Example: pass data via Typoscript" and not to this chapter.

For “single index” chart types (see "Configuration -> Chart type characteristics and requirements" for explanation of the term), copy this snippet into the TS-setup of the page's template:

userLibs.tx_ar_charts_pi1 =
temp.ar_chart{
  userFunc = tx_archarts_pi1->main

  getPath = 0
  absolutePath = 0

  modelId = 1
  dataSource = typoscript
  imageFileFormat = png
  pngCompression = 0
  backgroundColor = #ffffff


  chart {
    datasets {
      0 {
        values = TEXT
        values.value = 10
        color = TEXT
        color.value = 70a3d8
        label = TEXT
        label.value = Series A
      }
      2 {
        values = TEXT
        values.value = 20
        color = TEXT
        color.value = 98c038
        label = TEXT
        label.value = Series B
      }
    }
  }
}

For “multi index” chart types (see "Configuration -> Chart type characteristics and requirements" for explanation of the term), copy this snippet into the TS-setup of the page's template:

userLibs.tx_ar_charts_pi1 =
temp.ar_chart{
  userFunc = tx_archarts_pi1->main

  getPath = 0
  absolutePath = 0

  modelId = 1
  dataSource = typoscript
  imageFileFormat = png
  pngCompression = 0
  backgroundColor = #ffffff


  chart {
    datasets {
      0 {
        values = TEXT
        values.value = 200, 52, 47, 52, 87, 14, 180, 129
        color = TEXT
        color.value = 70a3d8
        label = TEXT
        label.value = Series A
      }
      2 {
        values = TEXT
        values.value = 50, 28, 25, 30, 41, 62, 120, 86
        color = TEXT
        color.value = 98c038
        label = TEXT
        label.value = Series B
      }
    }
    indexLabels = TEXT
    indexLabels.value = a|b|c|d|e|f|g|h
    indexLabelsDivider = TEXT
    indexLabelsDivider.value = |
  }
}

2) In the code, replace the “modelId” value with an existing model Id, and the “dataSource” value to a value that is allowed in the model.

3. Still in the template TS-setup, use something like

page.10 < temp.ar_chart

to copy the plugin output to the place you want. Place this behind the first snippet, else “temp.ar_chart” won't most likely contain anything.

4) In the model, make sure that data source, chart type, dimensions etc. are set.

5. Clear caches, and see the chart on the page.