Extension:Pchart4mw

From MediaWiki.org
Jump to: navigation, search
MediaWiki extensions manual
Crystal Clear action run.png
pChart4mw

Release status: stable

Pchart4mw-sample-00.png
Implementation Tag, Parser function
Description Create professional charts for MediaWiki
Author(s) Robert Horlings &
(Gérard de Smaeletalk)
Latest version 1.4.0 (May 12th 2012)
MediaWiki 1.12, 1.13, 1.14, 1.15, 1.16, 1.17, 1.18, 1.19, 1.20
License GPL
Download Project page
Subversion [Help]

Browse source code
View code changes
Note: no localisation updates provided by translatewiki.net.

Parameters

http://code.google.com/p/pchart4mw/wiki/Parameters

Translate the Pchart4mw extension if it is available at translatewiki.net

Check usage and version matrix; code metrics

This PHP Chart for MediaWiki extension (pchart4mw)[1] allows you to visualize your data with charts like line-, bar-, pie-, radar-, scatter- and bubble charts. It uses the (free) PHP Chart library pChart[2] to produce the charts. It allows for 2- or 3-dimensional charts, which are all within the potential of the pChart library. The charts are based on your data from the wiki page.

pchart4mw works, together with the pChart library, fully within your MediaWiki Server environment. The data is processed completely within the server environment. To enable full flexibility and full integration with other extensions pchart4mw supports both the standard MediaWiki tag syntax and the parser function syntax.

Use[edit | edit source]

pchart4mw has a unique tag or function for each chart type it supports. It can be used with its tags or with its parser functions.

Usage with parser functions Usage with tags
 {{#pChartType: p1|p2|p3|...|data=
 data...
 }}
 <pChartType p1 p2 p3 ...>
 data...
 </pChartType>
  • Each chart type starts with {{#pChartType: and ends with }}.
  • Between the start {{#pChartType: and "data=" additional parameters can be added. Parameters are optional and are used for detail specification of the chart, p1|p2|...|data=. Parameters are separated with the pipe symbol |.
  • Data starts with parameter data=. The data= parameter is mandatory and always the last parameter. Data is entered per line, datasets on a line are comma separated.
  • #pChartType defines the chart type. The options are:
#pBars for bar charts
#pPie for pie charts
#pLines for line charts
#pScatter for scatter diagrams
#pRadar for radar charts
#pBubble for bubble charts
  • Each chart type starts with <pChartType> and ends with </pChartType>.
  • Between the start <pChartType and closing symbol ">" additional parameters can be added. Parameters are optional and are used for detail specification of the chart, p1 p2 p3 etc.... Parameters are separated with a space.
  • Data is entered per line, datasets on a line are comma separated.
  • <pChartType defines the chart type. The options are:
<pBars>...</pBars> for bar charts
<pPie>...</pPie> for pie charts
<pLines>...</pLines> for line charts
<pScatter>...</pScatter> for scatter diagrams
<pRadar>...</pRadar> for radar charts
<pBubble>...</pBubble> for bubble charts

The tag method is the traditional way of adding extra functionality to MediaWiki. The parser function method is added to pChart4mw as of version 1.1. Use the parser function method to integrate pchart4mw's charting capabilities with other MediaWiki functions or extensions.

Sample charts[edit | edit source]

Here are some simple samples of what you can do with pChart for MediaWiki:

Wiki Markup Display
Simple bar chart (histogram) with legend (using tag syntax)
<pbars size=300x150 title="Site Visitors" 
 ymin=0 ymax=10000 legend>
,Europe,United States,Asia
Oct,5345,3110,1291
Nov,3452,3695,1047
Dec,7843,4712,1305
</pbars>
Pchart4mw-sample-01.png
Simple pie chart (using parser function syntax)
{{#pPie: exploded|3d|data=
Sales,43
Marketing,21
Development,56
Customer Support,23
Information Technology,31
Administration,13
}}
Pchart4mw-sample-02.png
Line chart filled and rounded (using tag syntax)
<pLines ymin=0 ymax=10000 axiscolor=888888 cubic filled 
 angle=90 plots legend>
,US,EU
Jan,6748,4301
Feb,3911,5019
Mar,3019,3941
Apr,4810,6412
May,2203,4823
Jun,4510,4110
Jul,3918,5510
Aug,8810,2930
Sep,7182,3504
Oct,6911,3881
Nov,6749,4761
Dec,7184,4918
</pLines>
Pchart4mw-sample-03.png
Radar chart filled (using parser function syntax)
{{#pRadar: size=300x200|striped|filled|data=
,Allocated Budget,Actual Spending
Sales,4,5
Marketing,2,5
Development,6,1
Customer Support,2,1
IT,3,2
Administration,1,1
}}
Pchart4mw-sample-04.png

Installation and configuration[edit | edit source]

These samples got you interested in the extension? Its installation is very straight forward. Here's how to do it:

Installation[edit | edit source]

This installation describes the basic pchart4mw installation using its default settings.

Install this extension

Download the pchart4mw extension from the pchart4mw site[1] and save in the new extension directory

$IP/extensions/pChart4mw

You shoud have the following files and folders after installation:

$IP/extensions/pChart4mw/colorschemes/
                        /colorschemes/*.txt
                        /fonts/
                        /fonts/*.ttf
                        /pChart/
                        /pChart/*.class
                        /pChart4mw.php
                        /pChart4mw.class.php
                        /pChart4mw.bars.class.php
                        /pChart4mw.bubble.class.php
                        /pChart4mw.lines.class.php
                        /pChart4mw.pie.class.php
                        /pChart4mw.radar.php
                        /pChart4mw.scatter.class.php
                        /library.inc.php
                        /0-changes.txt
                        /0-licence.txt

Note: Check the system requirements for pChart4mw, your PHP installation needs to have GD library with freetype extension enabled.

Configuration[edit | edit source]

To configure this extension a few parameters need to be set.

Tell MediaWiki about this extension

Add the following line to the file LocalSettings.php

require_once( "$IP/extensions/pchart4mw/pChart4mw.php" );
Cache directory

The cache directory is the folder where the chart images are saved. The chart image file is loaded on the page to be shown. When pchart4mw's cache option is enabled (this is default), the chart image file is created only once. This saves server processing time when a page is loaded. If anything in the chart's code or data is changed, a new file is created. The default cache directory is:

 $IP/images/pChart4mw

The cache directory must exist and be writeable! Check, and if necessary set, the write permissions. Also read the maintenance instructions of the cache directory.

More optional settings

Note that pchart4mw has several settings to customize its installation and its behaviour to your preferences. The above default installation (choice of folders) and configuration can be modified. For more configuration options and preference settings visit the pchart4mw[1] project site.

How does pchart4mw work?[edit | edit source]

Figure 1: The working of pchart4mw

As a wiki author you create a chart definition within a wiki page. To do this you type simple chart syntax plus the data to be displayed in the chart. pchart4mw processes your chart definition and uses the pChart library to create a chart image. Browsing the wiki page you get your chart image displayed.

Figure 1 gives a simplified overview of the working of pchart4mw.

In more detail:

  • A pchart4mw call is initiated from a wiki page written in wiki markup. A call starts with the <pChartType> start tag or {{#pChartType: function for the graph of your choice. pchart4mw receives a call every time a wiki page with a pchat4mw tag or function is viewed by a user
  • pchart4mw receives the full text from the call between start and end tag
  • From this full text the unique graph image filename is determined (e.g. 4011db...0072995.png)
  • pchart4mw processes the chart definition and the data
  • pchart4mw uses the pChart Library to create an image of the chart
  • pchart4mw uses a cache folder, (default images/pchart4mw), to store the image file.
  • If the graph image already exists in the cache folder, pchart4mw doesn't create it again. If it doesn't exist pchart4mw creates it.
  • The graph image (e.g. 4011db...0072995.png) is then shown on the page.

Maintenance of your site[edit | edit source]

As described in 'how does pchart4mw work', pchart4mw stores chart images in the cache folder (default folder is: images/pchart4mw/*.*). The file names of these images are automatically generated based on the full content of the pchart4mw call. This means that every time the content of a call changes (when a user edits the chart definition and/or the data) the file name of the created image also changes.

A file name is for example: 4011db4213c05eed3f30f6a350072995.png

The consequence is that over time the cache folder becomes populated with unused (orphan) graph images. Periodically the wiki site administrator should do some clean-up in this folder. It is recommended to delete all the files in this cache folder once in a while. Graph images will be (re)created automatically whenever a page is viewed and pchart4mw discovers the graph image doesn't exist.

About pchart4mw...[edit | edit source]

Its origin[edit | edit source]

The creation of this extension was inspired after discovering the excellent PHP Chart library pChart[2] on the internet. The stunning charts this pChart library produces are a great addition in charting functionality for MediaWiki.

The design of pchart4mw is partly inspired by extensions gchart4mw (Google chart for Mediawiki) and gnuplotBasic. (note that neither one of them are actively maintained anymore).

Its development[edit | edit source]

Its development started early 2009. It was first publicly released in July 2009. As of November 2009 its full documentation was finished on the pchart4mw project site[1]. As of version 1.1 - released in June 2010 - pchart4mw supports parser functions to enable integrating pchart4mw's charting capabilities with other MediaWiki functions or extensions.

This extension is developed and tested with pChart 1.27d, MediaWiki 1.12+ and PHP 5.2 on a Windows machine. It should work just as fine on other versions/platforms, as long as PHP 5.x is used with GD Library and freetype extension enabled.

Its design choices[edit | edit source]

The design choices made for pchart4mw.

  • Use of pChart library to create the graphs. This extensions options only go as far as what the pChart library provides.
  • No data files, inline data only. pchart4mw only accepts data that is part of the wiki markup.
  • Unique tag and function for every chart type. This helps keep the syntax as simple and uniform as possible.
  • Simple user syntax. The syntax is kept as simple as possible to make this extension usable for a wide variety of users.
  • Support both tag syntax and parser function syntax for full flexibility and integration with other extensions.

Its security[edit | edit source]

All the data in the wiki page is processed on the MediaWiki server environment by this extension and the installed pChart library. It does not use any online service, your data does not have to be sent elsewhere.

Its name[edit | edit source]

It is called pchart4mw because:

  • It is based on the PHP Chart library (pChart) and it is made for (4) use with MediaWiki (mw)
    (although this extension could be easily be adjusted for another php based wiki)

More on pchart4mw...[edit | edit source]

Please note that this page is only a brief introduction to pchart4mw. Visit the pchart4mw[1] project site for more details and full documentation.

Talk and share[edit | edit source]

Please use the talk page for talking about or sharing on pchart4mw.

References[edit | edit source]

  1. 1.0 1.1 1.2 1.3 1.4 http://code.google.com/p/pchart4mw/ - Project site for this extension
  2. 2.0 2.1 http://pchart.sourceforge.net/ - Project site for the pChart 1.x library