Installation
- If you have a previous version installed, first deactivate it.
- Download the latest version (see http://www.deborahmcdonnell.com/damselfly/wordpress-plugins/progressfly/)
- Upload progressfly.php into your plugins directory (usually /wp-content/plugins)
- Navigate to the Plugins page in your administration panel and activate the plugin ProgressFly
- Add a function call where you want the meter to appear, eg the sidebar. (Functions are explained below.) Alternatively, embed functions as needed in your posts and pages.
That's it! The plugin should automatically create the table it needs and after that you can manage your project meters through your wordpress administration panel, under the Manage tab. (If you had a previous version installed and you can't see any new fields with this version, de-activate ProgressFly and then re-activate it. This should prompt ProgressFly to modify its database tables.)
Upgrading to 0.50
Version 0.50 involves some extensive changes to progressfly's database. The plugin will make these changes for you, automatically adding the new fields.
However, some of the new fields contain CSS information, and are in fact subsets of the old fields. This means the old fields will need some editing to remove duplicate (and potentially meter-breaking) data, and you'll need to check the new fields contain the data you want. The changes were necessary both to make the CSS control simpler, and also to fix a tricksy bug in the display of the "cssbare" progress meter.
Yes, it's very, very annoying to have to re-key all your data. I'm very sorry. If it makes you feel any better, I had to do it for all of my projects, too — multiple times, actually, because I had to keep testing and re-keying and testing and re-keying while I was developing the new version. Trust me, if I knew how to get around that, I would have!
Right, on to the changed fields:
- "Background": this was a freestyle field, and the default install specified the meter height and width in this field. If any of your meters have height and width specified here, remove them, since these variables are now specified elsewhere. (The default values of 15px and 100px respectively haven't changed, and will be uploaded into the new variables for you.)
- "Progress Bar": A freestyle variable to allow users extra control over the appearance of the progress bar. If you specified the height and internal margin of the progress bar in this variable, remove them. The height is now calculated automatically, and the internal margin specified elsewhere.
- "Border Style": This was a freestyle variable allowing users to specify border width and the style (solid/dashed etc). It is now deprecated entirely, as it's been split into "Border Width" and "Border Style" (yes, I know the name is the same; yes, I know that's bad). If you didn't change the default for this one, you don't need to worry: the old defaults will be uploaded into the new variables, and this variable will quietly vanish with the next version of ProgressFly.
Style Classes
From version 0.31 of ProgressFly, style classes are customised in the admin panel, and those values are then hard-coded into the progress meter each time the function is called. This isn't ideal, in one way, but it overcomes problems with browser inheritability and also means that any meters embedded in your posts (should) display correctly in your feeds.
It does mean that you need confidence with CSS if you're going to muck about with anything in the "freestyle" section. If your tinkering appears to break something, go to ProgressFly's options submenu; down the bottom you'll find a list of the default CSS so you can revert to a 'clean' install and check if that fixes the problem.
Embeddable Functions
Embed Meter
[pfmeter id=# target=# progress=# display=# precision=#]
Inserted into a wordpress post or page, the above code will embed the specified progress meter into the page. The parameter options are as follows:
- id (Required)
- The ProjectID of the progress meter you want to display.
- target=# progress=# (Optional)
- If you specify a number for both target and progress, the function will display a static progress meter (useful if you like to post daily metrics). If you omit one or both, the function will call the project target/progress figures from the database, and will therefore produce a dynamic meter which updates as you update the database
- display=# (Optional)
- Controls how the progress meter is displayed:
- 1: the default (title + meter + subtext)
- 2: the minimal (title + meter with internal text)
- 3: the preview (meter only, no text or title)
If omitted, the function will assume you have chosen display=1 - precision=# (Optional)
- Controls the number of digits to be displayed after the decimal point. (If you want no decimal point, ie integers, enter 0.) If omitted, the function will use the global default (set to 0 on installation; changeable through the options panel).
Template Functions
Print Specific Meter:
<?php pf_specific($id, $metertype, $globalprec, $precision); ?>
Outputs the progress meter for the project with id number equal to '$id'.
$metertype can be:
- "css" - this is the default, and what will be used if $metertype is omitted in the function call. It displays the original configuration of title + meter + subtext (see the demo above)
- "cssbare" - this will remove the subtext and display a title + meter configuration. Note the percent complete will be displayed inside the meter, so make sure your progress text is a sufficiently different colour from your background and progress colours for it to be readable.
- "preview" - this is a meter-only display (no title, no text at all), probably of very little use to anyone. But it's there if you want it. This is the function used to display the preview on the management page.
$globalprec, $precision (optional) — defaults to "yes" (and the default precision) if omitted. If you wish to override the default precision for this display, enter "no", and then specify the precision in $precision. Note these variables must be specified or omitted as a pair: you can leave out both, or enter both, but you should not enter only one, at risk of breaking your meter.
Print Projects:
<?php pf_printprojects($limit, $metertype, $complete, $pfcategory, $orderby, $orderdxn, $visible, $globalprec, $precision); ?>
This function will print out your projects in a list, according to the variables you specify:
- $limit: The maximum number of projects you wish to display. If unspecified, defaults to -1 (ie, all projects)
- $metertype can be:
- "css" - this is the default, and what will be used if $metertype is omitted in the function call. It displays the original configuration of title + meter + subtext (see the demo above)
- "cssbare" - this will remove the subtext and display a title + meter configuration. Note the percent complete will be displayed inside the meter, so make sure your progress text is a sufficiently different colour from your background and progress colours for it to be readable.
- "preview" - this is a meter-only display (no title, no text at all), probably of very little use to anyone. But it's there if you want it. This is the function used to display the preview on the management page.
- $complete: yes, no or all. If yes, the function will only fetch and display completed projects. If no, the function will fetch and display incomplete projects. If all, you guessed it, it will fetch everything. Defaults to no.
- $pfcategory: specify a category name if you want the function to fetch meters only belonging to that category. Otherwise, specify "all".
- $orderby: this is the attribute you want to order the project list by. Can be "wipid", "title", "titlelink", "progress", "target", "pfcategory", "complete", "visible". Defaults to "wipid".
- $orderdxn: you've picked what you want to sort by, now pick whether you want to sort in ascending ("ASC") or descending ("DESC"). Defaults to DESC.
- $visible: yes, no, or all. Grabs visible, invisible, or all projects, respectively. Defaults to no. I don't imagine many people will use this one (why mark a project invisible if you want it to be seen by your readers, after all?), but I do believe in the end-user having control where possible, so here it is. Control for you. Enjoy. Don't let it go to your head!
- $globalprec, $precision (optional) — defaults to "yes" (and the default precision) if omitted. If you wish to override the default precision for this display, enter "no", and then specify the precision in $precision. Note these variables must be specified or omitted as a pair: you can leave out both, or enter both, but you should not enter only one, at risk of breaking your meter.
Disclaimer
I am far from an expert in PHP. You can rest assured that all care was taken with this code, because I don't want to break my site (and because I based it on other peoples' code, so it should be stable enough). But I can't guarantee it won't break yours. If you have any questions or queries or suggestions, I'll do my best to answer them.