Extension:Pchart4mw

From MediaWiki.org

Jump to: navigation, search

           

Manual on MediaWiki Extensions
List of MediaWiki Extensions
Crystal Clear action run.png
pChart4mw

Release status: beta
Pchart4mw-sample-00.png
Implementation  Tag
Description Create professional charts for MediaWiki
Author(s)  Robert Horlings & (Gérard de SmaeleTalk)
Last Version  1.0.5 (2009-11-21)
MediaWiki  1.12 ... 1.15
License GPL
Download http://code.google.com/p/pchart4mw/

check usage (experimental)

Contents

[edit] Purpose

The 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.

[edit] Use

Structure of a pchart4mw call is:

 <pChartType p1 p2 p3 ...>
 data...
 </pChartType>
  • With <pChartType> you define the chart type you want. Possible values 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
  • Parameters p1 p2 p3 ... can be added within the charttype tag to customize the chart. Note that the parameters are separated by a space, and they can be written on multiple lines for readability. Visit the pchart4mw[1] project site for details on parameters.
  • The data... is comma separated on multiple lines

[edit] Sample charts

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

Wiki Markup Display
Simple bar chart (histogram) with legend 
<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 
<pPie exploded 3d>
Sales,43
Marketing,21
Development,56
Customer Support,23
Information Technology,31
Administration,13
</pPie>
Pchart4mw-sample-02.png
Line chart filled and rounded 
<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 
<pRadar size=300x200 striped filled>
,Allocated Budget,Actual Spending
Sales,4,5
Marketing,2,5
Development,6,1
Customer Support,2,1
IT,3,2
Administration,1,1
</pRadar>
Pchart4mw-sample-04.png

[edit] Installation and configuration

Got you interested in these samples? Its installation is very straight forward. Here's how to do it:

[edit] Installation

Install the pChart library
The first thing you need is a copy of the pChart library. Download the latest version from the pChart website[2]. Follow the instructions for pChart installation. The location where pChart is installed must be specified later on in LocalSettings.php. Remember this location. Check the system requirements for the pChart library, your PHP installation needs to have GD library with freetype extension enabled.
Possible locations for the pChart library are, for example:
Option 1: pChart library installed in [documentroot]/pChart/pChart.class
Option 2: pChart library installed in $IP/extensions/pChart4mw/pChart/pChart.class (sub-directory of pchart4mw extension)
Install this extension
Download the pchart4mw extension from the pchart4mw site[1] and save in the directory
$IP/extensions/pChart4mw

[edit] Configuration

To configure this extension, several parameters need to be set. A few options are needed for the extension to function properly. Other settings are optional:

Tell MediaWiki about this extension
Add the following line to the file LocalSettings.php
require_once( "$IP/extensions/pChart4mw/pChart4mw.php" );
Set pChart library location
Defines the location where the pChart library is installed. The variable $wgPChart4mwPChartPath contains the absolute path to the directory where the pChart class resides. Add the following line to LocalSettings.php
Option 1: pChart library installed in [documentroot]/pchart/pChart.class
$wgPChart4mwPChartPath = $_SERVER["DOCUMENT_ROOT"] . "/pChart";
Option 2: pChart library installed in $IP/extensions/pChart4mw/pChart/pChart.class (sub-folder of pchart4mw extension)
$wgPChart4mwPChartPath = $_SERVER["DOCUMENT_ROOT"] . "/wiki/extensions/pChart4mw/pChart";
Set pChart font location (optional)
Determines the truetype font file to write text into the graph. This variable contains the absolute path to the .ttf file. The pChart installation contains some font files by default in the Fonts subdirectory. Add the following line to LocalSettings.php:
$wgPChart4mwFont = $wgPChart4mwPChartPath . "/Fonts/tahoma.ttf";
to use the tahoma.ttf font from the Fonts subdirectory in the pChart directory.
Set cache directory (optional)
Directory where the created images are saved. The images are saved to this directory when created, and the saved file is loaded on the page where it should be shown. When the cache is enabled, the file is created only once, saving a lot of processing time when a page is loaded frequently. If anything in the chart code is changed, a new file is created. When the cache is disabled, the file is created again every time a page is loaded.
The directory must be specified as a subdirectory of the $wgUploadPath directory. The directory must exist and be writable. By default, the cache directory is $wgUploadPath/pChart4mw ([wiki]/images/pChart4mw).
Add the following line to LocalSettings.php
$wgPChart4mwCacheDir = "pChart4mw";
More optional settings
For more (optional) configuration options and default settings visit the pchart4mw[1] project site.

[edit] How does pchart4mw work?

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 of the graph of your choice. pchart4mw receives a call every time a wiki page with this tag is viewed by a user
  • pchart4mw receives the full text from the call between start end end tag
  • From this full text the unique graph image filename is determined (e.g. 4011db...0072995.png)
  • 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.

[edit] Maintenance of your site

As described in 'how does pchart4mw work', pchart4mw stores chart images in the cache folder (default images/pchart4mw/*.*). The filenames 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 the filename of the created image also changes.

A filename 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 cleanup in this folder. It is recommended to delete all the files in this directory once in a while. Graph images will be (re)created whenever a page is viewed and pchart4mw discovers the graph image doesn't exist.

[edit] About pchart4mw...

[edit] Its origin

The creation of this extension was inspired after discovering the excellent PHP Chart library pChart[2] on the internet. The stunning charts the pChart library produces are a great extension to be able to make charts for MediaWiki.

The design of pchart4mw is partly inspired by extensions gchart4mw (Google chart for Mediawiki) and gnuplotBasic.

[edit] Its development

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.

[edit] Its design choices

The design choices made for pchart4mw.

  • Use of pChart library to create the graphs. This extensions options go as far as what this library provides.
  • No files, inline data only. pchart4mw only accepts data that is part of the wiki markup.
  • Unique tag 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.

[edit] Its security

All the data in the wiki page is processed on the MediaWiki server environment by this extension and the installed pChart library. Your data does not have to be sent elsewhere.

[edit] Its name

It is called pchart4mw because:

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

[edit] More on pchart4mw...

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

[edit] References

  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 2.2 http://pchart.sourceforge.net/ - Project site for the pChart library
Retrieved from "http://www.mediawiki.org/wiki/Extension:Pchart4mw"