progrecss plugin

• Download the Plugin

Welcome to progrecss, a DokuWiki plugin to create CSS-based progress bars. No background images, no transparency dependence, no external files needed. Just CSS.

I'm Luis Machuca, username ryan.chappelle, a DokuWiki fan who's collaborated with some templates and plugins before, making suggestions and the like. This is my first attempt at an actual, more direct, collaboration in the form of a Syntax Plugin.

Feel free to use and comment (see ⇒Discussion).

Just do, either inline or in a line of its own:

<progrecss number% options... />

Or if you are more comfortable with fractions/recipes:

<progrecss x/y options... />

Details:

• note that progrecss is the actual plugin's name, the “c” is intentional as this plugin combines “progress” and “css”.
• number% is an actual percentage value, that is any integer from 0 to 100 followed by the character ”%”. This parameter is mandatory.
• x/y is two integer numbers separated by a literal slash, eg.: “3/5”. This parameter is mandatory.
• The closing /> has to be separated from the last parameter by a space. This is mandatory.
• Parameters are optional and follow the form ”param=value;, where:
  • param is a parameter name as explained in the table below.
  • there is no whitespace surrounding the ”=” (equal) sign.
  • the closing ”;” is mandatory.
  • you can escape ”;”'s in your parameters à-la-C, that is: \;.

Download and install the plugin using the Plugin Manager using the URL given above. Refer to Plugins on how to install plugins manually.

The plugin comes with three (3) default styles included (in the accompanying CSS file). With the use of the “style” parameter you can choose which style do you want: default, inline or gauge¹⁾.

The “default” style is just a default, no big deal, which shows a box containing the percentage display in a colour theme that matches that one used for tables in your template. The “gauge” style shows the same box, with the difference it is made rounded, with another colour scheme, and the caption is shown as a tooltip (hover your mouse over the gauge). The “inline” style is intended for inline display, that is, to run alongside text.

Here come some usage examples:

<progrecss 25% />

Just a progress bar, quarter task done. No big deal.

<progrecss 1/7 />
Another simple progress bar, maybe indicating only one day of the week has passed.

<code>
<progrecss 50% caption=One to go; />

just like before, but this progress bar shows half progress done, and also shows with a caption below.

<progrecss 50% caption=One down\;One to go; />

just like the above, but with a semicolon as part of the parameters. Note that it is escaped in a C-like fashion.

<progrecss 50% caption=One-to-go;style=gauge; />

the same bar, a different style, the caption is shown aside increasing the width of the object. If your browser supports it you'll see a round gauge and a minor shadow effect inside the actual progress indicator.

Some text ... <progrecss 99% style=inline;caption=Almost_Done;width=200px; /> some more text...

will show an almost complete progress bar, which will, depending on browser, display inline (alongside with text). The percentage number has a font size relative to paragraph text size. The caption, however, will not be shown.

Now with limited wikitext supported:

<progrecss 50% caption=If this //doesn't// work, we should [[Google>progrecss plugin|consult Google]]. ;style=gauge; />

Support for wikitext is limited at the moment. Underline, monospace, bold, italics and strikethrough work fine, and both internal and external links do work albeit they render strangely. Other syntax elements are untested. Because of their structure, footnotes, lists, headings, other plugin calls, and macros such as ~~NOCACHE~~ will most probably not be supported.

Style displays of the progrecss plugin, with Firefox 2

No Plugin Manager? Cease screaming and running around in circles! Just download the plugin from the location above and follow these steps:

1. Navigate to the lib/plugins directory in your DokuWiki installation.
2. Unpack the plugin there.
3. That should result in the creation of a progrecss directory with the contents of the plugin.
4. Just in case, clean your DokuWiki cache.

Demo site is up! (as of Dec 24, 2008).

Note language is Spanish but online translators shall do a good job with it.

Depending on the browser used, presentation of the plugin demo may vary. Check Browser Support!

A quick warning before you use this plugin:

Due to the box model used by DokuWiki, enabling use of wikitext inside the progress bar caption now makes the code to output non-W3C conformant code!. In particular, <div>s will be outputted interrupting the normal flow of <p> blocks. Presentation-wise, there is no discernible effect, unless your code depends on selectors like p:first or p:last. But syntactically speaking, code using this plugin no longer conforms to XHTML… You are warned.

Because of the styles used, perfect or at least “acceptable” presentation may be a challenge for some browsers, in particular when using the inline style. My web development tests are based on Opera 9.6 and Firefox 3.0; results may greatly vary depending on your browser. Note that also because of the styles used, using this plugin will report your wikipage breaks with CSS conformance (for example, most CSS validators do not recognize -moz-* keys, text-spacing, or radius properties yet).

1. Add option to display either caption or percentage as gauge.
2. Improve visualization of full-width bars. — already corrected in the 'gauge' style
3. Wait and check for CSS3 rules.
4. Add the actual percentage number as an option (in the works).
5. Modify the inline version so that it doesn't cut through <p>s.
6. Change the location and draw of the caption/percentage.

     To be done

Unzipping the file from the download link above will give you a folder containing two files: syntax.php and style.css.

The stylesheets used are in the available style.css file. You can add your own styles just copying one of the style sets to your userstyle.conf and editing as needed. Be aware, however, about Browser Support. The structure of the elements goes as follows:

• One big container, classed with progrecss_stylename. The box contains the gauge, then the caption. The box itself is given a somewhat unique ID.
  • A classed:“border” container that represents the entire gauge. Runs for the width indicated as parameter. Be aware of using display:inline or float: … attributes here may break the presentation. Do not use width or min-width here as this is provided from the PHP side.
    • A classed:“bar” container that represents the actual progress. Runs for the percentage relative to the width of the border box. This is what you style in order to show progress. Do not use width or min-width here as this is provided from the PHP side.
  • A classed:“caption” <span> element that contains the object's caption. May or may not be visible depending on style used (inline, for example, sets it non-visible).

The original idea I don't know where did it come from, but I got it first from David Anaxagoras's site. He's explicitly given authorization to “do whatever we want” with it. Credits are due in the included syntax.php file.

Also I required a deal of explaining on the current strategies for box rounding and inline background filling with CSS which took me to several CSS forums and pages including A List Apart and Quirksmode.org. Thanks to those people I feel I've advanced since my college CSS class.

Any will be welcome. As well as suggestions.

Please enable WikiSynthax inside captions!

Something like: <progrecss 100% width=5em;caption=✓ - Download {{:todo:presentation.zip|Presentation}}; />

I'm in the process of learning how to use the Plugins “parse modes”. I have had a hard time testing them… but I'll surely keep working on that. Thanks. – — 'Ryan Chappelle' 2008/11/02 21:45

Already implemented, albeit in a limited manner. I would be glad if you can test it. — Luis Machuca B. 2008/12/25 03:55

Thanks, your Plugin is great! No problem, good things take time.

—

OK, I feel like a moron right now. I had not realized there is something very simple called p_render which can be used, apparently, to make the plugin accept wiki syntax inside the caption. So I'm now working on it and I'll have news soon. Before the end of the year. Also I have to correct a bug with Firefox and Safari I was not aware of. Peace. Out. — 'Ryan Chappelle' 2008/12/02 09:53

Uploaded new version 1.4, with limited support for wikisyntax, as of Xmas 2008. Merry that Holiday!