progrecss plugin

The progrecss plugin (pro·gre·css plug·in) allows one to create progress bars in DokuWiki which use CSS only. No images, no backgrounds, no transparency, no javascript needed. Just CSS.

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

Include the following, either inline or in a line of its own:

<progrecss number% options... />

The following format is more suitable for tasks or recipes:

<progrecss x/y options... />

Details:

• the “number” or “x/y” parameters are mandatory and are the only parameters required for the plugin to function; everything else defaults to sane values.
• number% is an actual percentage value, that is any integer from 0 to 100 followed by the character ”%”. Only integer percentages are allowed.
• x/y is two integer numbers separated by a literal slash, eg.: “3/5”.
• 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;.

Parameters are separated by a semicolon ”;”, and the last parameter must have an ending semicolon too. If you need to include a literal semicolon inside a parameter value, just escape it à-la-C (ie.: “\;”).

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 style.css file. With the use of the “style” parameter you can choose which style do you want: default, inline or gauge¹⁾.

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.

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

Now with overrideable percentage format:

<progrecss 78% caption=At least we're almost done with this one. ;pdisplay=%03u; />

Will show the percentage value as “078%”. This should ease compatibility with plugins and tools such as sortablejs, in particular if the caption is left blank. Thanks to Gunnar Gorges for suggestions.

Want to see the plugin in action?

(Neo) Demo site is up! (as of Sep 01, 2010).

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!

The progrecss plugin in action

	Style displays of the progrecss plugin, with Firefox 2
	A better look of the three base styles, under Opera 10.0.

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.

This plugin was developed for the 2008-05-05 release, where it worked at an acceptable level. It has been tested by me (and thus caveat emptor) with every major version of DokuWiki since, up to and including the “Anteater” release. If you experience any troubles with this particular plugin in a recent DW version, drop me a word to see if I can test and replicate the issue.

A quick warning before you use this plugin:

The styles use features from CSS version 2 in order to attain both layout and presentation; thus, any browser which does not correctly implement the standard may be challenged by this plugin, in particular when using the “inline” style. My web development tests for this plugin are done in both Opera 9.6 and Firefox 3.0, with results being satisfactory with these browsers and later versions. Results may greatly vary according to 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).

The most recent versions of the plugin also include a print-view stylesheet; however, since browsers interpret printing CSS differently for such matters as colors and backgrounds, which this plugin relies on for representation, these stylesheet only imitate the most basic features of the provided progressbar styles.

1. Add option to display either caption or percentage as gauge.
2. Wait and check for CSS3 rules.
3. Add the actual percentage number as an option (in the works). Done in 1.8 RC.
4. Modify the inline version so that it doesn't cut through <p>s.
5. Change the location and draw of the caption/percentage.

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

As of 1.8 RC, the plugin includes localized strings for the Configuration Manager and Plugin Manager²⁾. The included languages are:

• English (duh…).
• Spanish by The Author.
• German by Gunnar Gorges.
• Russian by Ksenia Glushak.

If you want to collaborate by translating this plugin, just pick one of the language folder sitting at lang/, modify to suit your language and write me a line. You will be fully credited as the above authors are.

I'm Luis Machuca, 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.

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.

Luis Machuca Bezzaza³⁾ is a Chilean Developer who has released plugins for DokuWiki ever since 2008. He takes somewhat-active participation in the DokuWiki User Forums, where he moderates the somewhat-active-as-well Spanish Discussion. He can be sometimes found at the DokuWiki IRC channel as well, shamelessly promoting his plugins. In his spare time he functions as the Secretary (S) of his city's LUG, Gulix as well as trying to contribute to the overall internet culture.

Other DokuWiki Plugins by Luis Machuca Bezzaza (a.k.a ryan.chappelle@DW Forums)Luis Machuca Bezzaza ryan.chappelle Temuco, Chile
progrecss	…you are here now
tooltip	add tooltips (info balloons) to text or special words
clock	display the time in DokuWiki
countdown	show the remaining time to an event
divalign2	align your paragraphs for better reading
gil	display currency conversions from Yahoo services
hide	hide text from immediate view
noiewarning	warn users that they are using the shitty IE browser
coming soon	control the formatting and properties of external links
coming soon	use Mediawiki-style template substitution in wiki pages

Unzipping the file from the download link above will give you the source code. It is free, in the GPL definition of the word.

The Demo page holds a changelog for the latest release.

This plugin (“progrecss”) © The Author.

“progrecss” is developed part-for-fun, part-for-learning, of my own free will and during my spare time. It is released “as-is” under the terms of the GPL 2 License. I am not affiliated to the core DokuWiki staff, I just know the guys and like them (er… their work). I take no responsibility for damages caused by inadequate use of “progrecss”, but I try to be available for a nice chat in case particular issues related to “progrecss”'s domain are presented. Insert standard lorem-ipsum like legal disclaimer and/or waiver of warranties here and you know the drill.

Credits are given to David Anaxagoras for his implementation of CSS-based inline progress bars, for which he gave consent of use and are the basis of this plugin's workings.

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!

“width” won't work for me, using DW 2009-12-25-c. winky, 2010-06-02 11:17

Haven't had problems yet (that's the release I use for development) but I'll check the issue. Are you sure the width parameter is a full unit (not just a number)? – — Luis 2010/09/01 22:57