Pasi.fi

This page documents the simple graph plugin for the great WordPress blogging platform.

NB. Take a sneakpeek at the next version here.

Got problems? Take a look at the troubleshooting section further down this page!

Description

The plugin displays a small graph or chart of single set of data, which is essentially any values associated with dates. On my homepage's sidebar I use the graph for weight control (hoping that it won't climb to three digits), but it could be used for displaying many other kinds of data, e.g. a child's height, amount of waterfall in your backyard, etc. It is not necessary to mark a value every day, but it is possible.

Download

The plugin is now hosted on WordPress Extend and you can download it from there. If you don't like zip archives, you can also access the subversion repository.

Compatibility / Requirements

Works in WordPress 2.0.1 or newer because earlier versions don't implement all the hooks required. Tested up to WordPress 2.3.1.

Graph generation (except Google Chart API graphs) also requires that you have GD library installed and enabled in your PHP installation. Please refer to the Image section in PHP documentation for more information.

If GD2 library is available, graphs will be true color PNG images. However, depending on the capabilities of your installed GD library, graph will fall back to 8-bit palette images, and GIF and JPEG formats as necessary. (GIF if PNG is not available, and JPEG if GIF is not available.)

Google Chart API support

As of version 1.0.5, the plugin supports Google Chart API. It makes the widget graph a lot more pretty than my original renderer ever could. However, there are some drawbacks, which are listed below. Also note that the implementation is actually a quick hack, and there might be additional quirks that I'm not yet aware of. Thus, treat the feature as experimental. It is disabled by default and can be enabled in widget control pane.

1. Google Chart API Usage Policy states that "Use of the Google Chart API is subject to a query limit of 50,000 queries per user per day. If you go over this 24-hour limit, the Chart API may stop working for you temporarily. If you continue to exceed this limit, your access to the Chart API may be blocked." I assume that the limit is per site and accounted for via HTTP referrer headers. Most blogs won't be affected by this, but if yours has high traffic, please do not enable Google Chart API rendering on your site until I implement cache for this thing.
2. Number of values in a graph is limited due to URL length limitations. The graph image is loaded each time from Google's servers and the values are sent there as HTTP GET parameters in the URL. As the protocol limits the length of this string, there's a limit either to the level of accuracy or the length of the graph. As of version 1.0.5, the level of accuracy is not limited too much (values are used to first decimal precision, ie. a value is of the form 99.9), which consequently limits the amount of values. To counter this, the current implementation forces the use of weekly averages instead of daily values. For very long sets of data, this will still produce an empty or broken graph. In such case, try disabling the trend graph. If that doesn't help, disable Google Chart API rendering and wait for future updates, which will introduce new ways to avert this, such as option to limit the accuracy.
3. Not all graph features work because I haven't implemented them for Google Chart API yet. These include foreground and background colors, for instance. Data line and trend line colors are used properly though. There's a drawback to customizing graph colors however, as they take space from actual data in the URL, reducing the number of values that can be included. Nevertheless, they'll be included in the future versions, probably with an option to leave them out.

Aside from graphs being now more pretty, there's another benefit: GD library is not required any more if you use only Google Chart API rendering.

Installation

First of all, backup your WordPress files and database! Installation of this plugin shouldn't do any harm, but since I've done absolutely no testing besides actively using it myself, I cannot guarantee it's entirely bug free. Also, this is my first ever WP plugin, which I created both for fun and to learn the art of making plugins. So, this plugin is provided AS IS, and installation and usage of this plugin is entirely at your own risk. I will not assume any responsibility for any possible damages. (Although it still isn't supposed to cause any damages.)

Extract the plugin archive in your WordPress plugins folder (wp-content/plugins/) and then activate the plugin through your WordPress administration. The activation sets up initial configuration options and creates the database table for the plugin data.

Please make sure that you upload/extract the simple-graph folder (or pjm_graph if you're using 0.9.6 or older version) entirely in your plugin folder, and not just the contents of it! Your folder structure should look like this:

• wp-content/plugins/
• simple-graph/
• pjm_graph.php
• grapher/
• graph.php
• gchart.php (since version 1.0.5)

Finally, insert a code similar to the one below to your WordPress theme, for example in the sidebar.php file. The essential part is calling the pjm_graph() function. Note! If your theme is widget enabled, you don't have to edit any files, just use the widget instead!

Installation is now complete!

Advanced parameters

You can override width and height of the graph with function parameters. See the function declaration below.

void pjm_graph($WIDTH, $HEIGHT, $TREND, $TARGET, $YTD, $MTD, $WKLY);

Zero (0) values for WIDTH and HEIGHT preserve the default width and height that are specified in the admin panel. Any other values override the default.

TREND, TARGET, YTD, MTD and WKLY parameters expect a boolean value, which is either TRUE or FALSE. By default they're all FALSE. If TREND is TRUE, gliding trend graph appears. If YTD is TRUE, only the values from last year are used in the graph. If MTD is TRUE, only the values from last month are used. (If YTD is TRUE, value of MTD is irrelevant.) If WKLY is TRUE, rough weekly average values will be calculated instead of daily values where possible. TARGET is not fully implemented yet and thus its value has no meaning.

Trend graph

Trend is exponential sliding average of the actual data. Its value is calculated like this: $new_trend = round( $new_value - $old_trend ) / 10 + $old_trend; like explained by Painoarvokas in his blog comments.

Usage

You can change the appearance of the graph in the WordPress administration. Click on Plugins menu and then on Simple Graph Configuration submenu.

To add and delete the datapoints in the graph, go to Manage menu and then to Simple Graph submenu.

License

GNU General Public License. Also, I'd be happy to hear if someone uses this plugin and also any comments are welcome. I also welcome all links to this page from your blog if you're using the plugin. I collect links to sites that use the plugin, the list is here. If your site is missing, please let me know.

To do

• More configuration options, such as separate background colours for inside and outside of the graph.
• Make the graph clickable for a larger version. Add configuration options for the larger version (size, etc.).
• Add configuration option to limit the amount of data that is displayed, for example "show only X most recent days," where zero value for X would mean all data. (Now all data is displayed.) Of course, separate option for the larger graph.
• Add caption for the graph and for the Y-axis.

Known issues

• The plugin is everything but robust. Bad input won't be rejected, error situations are not handled properly, etc. I'm not sure if these will be fixed for this plugin.
• At least two values have to be inserted in the database, or the graph generation will fail. The values may be bogus and deleted later when enough real data exists. Graph now displays an error message about this, as of v0.9.2.

Troubleshooting

• If nothing is displayed where the graph is supposed to be, make sure that you enter the proper PHP code in a theme file, such as sidebar.php. PHP code doesn't generally work when entered in blog post or page, if another plugin making this possible isn't installed as well.
• If a broken image is displayed, or just text "Graph", in the place of the graph, make sure you uploaded the entire simple-graph folder in your plugin directory and not just the contents of that folder.
• If text similar to "Fatal error: Call to undefined function: pjm_graph() in.." is shown instead of the graph, the simple graph plugin isn't activated in your wordpress plugins screen. If you want to occasionally deactivate the plugin, you can use function_exists('pjm_graph') code to alleviate this problem, as shown in the code example on this page.
• If everything else seems to be in order, and you still get a broken image, please note that you need to have at least two values inserted in the database! With zero or only one data point the graph will fail. This is a bug. Hat tip to Dominic for pointing this out. New in v0.9.2: This now produces an error message.
• When the plugin is activated, a database table is created. If you get errors at this point or the plugin just does not work, check if your WordPress can create database tables, i.e. if CREATE SQL clause is enabled for the database account. If you are unable to allow CREATE clauses for your WordPress, you can create the database table manually. Check pjm_graph.php file for table details... Hat tip to Dominic for this one too.