ProgressFly Function Calls

ProgressFly has three main functions, one for embedding a meter into a post or page, and two for displaying your meters in your templates. The latter two will require you to modify your template, but don't worry, it's very easy.

Embedding A Meter

To embed a progress meter into a post or page, simply drop the following string into the text editor when you create your post or page:

[pfmeter id=# target=# progress=# display=# precision=#]

where:

• id=# (required): The ID number of the meter you wish to display
• target=# progress=# (optional): This part of the string gives you the option of manually specifying the target and progress. If you specify a number for both, the meter will be static, that is, it won't change when you update the database values. This is useful for those of you who like to post daily metrics to chart your progress. If you would prefer the meter to be dynamic, and update accordingly whenever you update the database values, omit this part of the string.
• display=# (optional): This will dictate which kind of meter you wish to display. If this part of the string is omitted, the default meter will be displayed. The options for this variable are:
  • 1: "css" – The default display (title + meter + units and progress in subtext)
  • 2: "cssbare" – A stripped-back version of the meter (title + meter with % progress displayed internall, no subtext)
  • 3: "preview" – The meter, and only the meter (no title or progress text or subtext
• precision=# (optional): This specifies the number of decimal places to display. If omitted, the meter will display according to the default option specified in the database.

Example Code

If you wish to display progress meter with id number 4, which is dynamic, and you're happy with the defaults:

[pfmeter id=4]

If you wish to display progress meter with id number 4, which is currently at 40% and make sure it's static, and you're happy with the defaults:

[pfmeter id=4 target=10 progress=4]

If you wish to display progress meter with id number 4, keep it dynamic, but you want the "cssbare" display with two decimal places:

[pfmeter id=4 display="cssbare" precision=2]

Template Functions

To display any of your progress meters outside of posts or pages, you will need to modify the template where you wish the meters to display.

Navigate to the appropriate template page (most people choose to edit sidebar.php, for example), find the lines in the template where you wish the meters to display, and enter the appropriate function call (see below) into the code.

I am working on widgetising ProgressFly for an upcoming release.

Print A Single Meter

To display a single meter, copy and paste the following code into your template:

<?php pf_specific($wipid, $metertype, $globalprec, $precision); ?>

where:

• $wipid (required): The id number of the meter you wish to display
• $metertype (optional): This will dictate which kind of meter you wish to display. If this part of the string is omitted, the default meter will be displayed. The options for this variable are:
  • "css" – The default display (title + meter + units and progress in subtext)
  • "cssbare" – A stripped-back version of the meter (title + meter with % progress displayed internall, no subtext)
  • "preview" – The meter, and only the meter (no title or progress text or subtext
• $globalprec (optional): Omit or specify "yes" if you want the progress meter to display using the default precision; specify "no" if you wish to manually specify the number of decimal places the meter should display
• $precision (optional): This specifies the number of decimal places to display. If omitted, the meter will display according to the default option. $globalprec must be "no" for this option to work.

Example Code

If you wish to display meter with id number 4, and you're happy with the default options:

<?php pf_specific(4); ?>

If you wish to display meter with id number 4, but you want the "cssbare" display:

<?php pf_specific(4,"cssbare"); ?>

If you wish to display meter with id number 4, and you want the "css" display with one decimal place:

<?php pf_specific(4,"css","no",1); ?>

Print A List Of Meters

To print a list of progress meters, copy and paste the following code into your template:

<?php pf_printprojects($limit, $display, $complete, $category, $orderby, $orderdxn, $visible, $globalprecision, $precision); ?>

where:

where:

• $limit (defaults to -1): The number of meters to display. If you wish to display only 5, stick 5 in there. If you wish to display all meters, specify -1.
• $metertype (optional): This will dictate which kind of meter you wish to display. If this part of the string is omitted, the default meter will be displayed. The options for this variable are:
  • "css" (default) – The default display (title + meter + units and progress in subtext)
  • "cssbare" – A stripped-back version of the meter (title + meter with % progress displayed internall, no subtext)
  • "preview" – The meter, and only the meter (no title or progress text or subtext
• $complete (optional; defaults to "no"): Choose "yes" to display only completed projects, "no" to display only incomplete projects, or "all" to display both complete and incomplete
• $category (optional; defaults to "all"): If you specify a category name here, the function will display only meters tagged with that category. If you omit this variable, or specify "all", the function will display all categories.
• $orderby (optional; defaults to id): Specify the variable on which to sort the meters: "wipid" (the id), "title", "target", "progress", "units", "pfcategory" (the category), "complete"
• $orderdxn (optional; defaults to DESC): Specify ASC or DESC to sort ascending or descending
• $visible (optional; defaults to "yes"): Specify "yes" to display only meters marked as visible, "all" to display all
• $globalprec (optional): Omit or specify "yes" if you want the progress meter to display using the default precision; specify "no" if you wish to manually specify the number of decimal places the meter should display
• $precision (optional): This specifies the number of decimal places to display. If omitted, the meter will display according to the default option. $globalprec must be "no" for this option to work.

Example Code

If you wish to display the last 5 meters of incomplete projects, and you're happy with the defaults:

<?php pf_printprojects(5); ?>

If you wish to display all incomplete projects, and you're happy with the defaults:

<?php pf_printprojects(); ?>

If you wish to display all complete projects, and you're happy with the defaults:

<?php pf_printprojects(-1,"css","yes"); ?>

The Meters

"css" (Default)

Title

units: 4 / 10 (40%)

"cssbare"

Title

"preview"

A Note On CSS

The meters are styled entirely using CSS, which makes them highly customisable. (And also a little bit fiddly. Thus is the joy of the multi-browser internet!)

If you want the progressbar to display as a picture instead of a solid colour, you can do this: simply create a slice of the picture you wish to use as a background tile and, in the "Progress Bar" variable, specify "background: #progresscolor url(path/to/image) top left repeat;" (replace "progresscolor" with whatever color you have specified in the Progress Color variable; it's a good idea to specify a color in case the picture doesn't load properly) and:

Title

Voila! The most boring background picture ever, but it's an example. (Note to those reading this page from inside their zip program: your browser won't be able to find the picture. Extract this page and pfbg.gif to the same directory and the example should load properly.)

So go wild and crazy. Make sure you test the display in a variety of browsers to ensure you know and are happy with what your visitors will be seeing, and make sure you hardcode the image path (ie, use the full url, not any shortcuts or abbreviations, to make sure the browser can always find your image).

I've tried to make ProgressFly user-friendly even for those who know very little CSS, but mucking with the freestyle variables will require a knowledge of CSS. If you want some tips and tricks, the best place to start is W3 Schools tutorials.