Table of Contents
progrecss Plugin
Compatible with DokuWiki
- 2024-02-06 "Kaos" unknown
- 2023-04-04 "Jack Jackrum" unknown
- 2022-07-31 "Igor" no
- 2020-07-29 "Hogfather" unknown
Similar to progressbar
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).
Syntax
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
Parameter Name | Structure | Effect |
---|---|---|
percentage | [0..100]% | Progress in percentage form, where it is an integer number from 0 to 100 inclusive, followed by the percent sign (for example, 32%). |
fraction | <number>/<number> | Progress in fraction form n/d, where n≤d (for example, 15/21). |
Caption | caption=text | The progress bar caption. Beginning from version 1.4, it accepts some limited forms of wiki syntax (in particular, text formatting modes are supported). This may or may not be displayed in accordance with the “style” parameter, though. |
Style | style=<stylename> | The CSS style used to present the progress bar. This style must exist in a valid DokuWiki CSS file (including userstyle.conf if available) in the form .progrecss_stylename . |
Width | width=<widthvalue> | Any valid CSS width value, including measures in pixels (px ) or ems (em ).This sets up the total progress bar width. Depending on the actual “style” parameter used, this may effect the progress bar positioning. |
PDisplay | pdisplay=mask | The format in which the percentage number is shown, as a sprintf mask. Defaults to ”%u“, and a percentage symbol is added automatically. |
Order | Reserved for future use (as of 2010.12) | |
Marker | Reserved for future use (as of 2010.12) |
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 Installation
Search and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually.
Usage
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
1).
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.
Demo
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!
Details
Things to Be Done
- Add option to display either caption or percentage as gauge.
- Modify the inline version so that it doesn't cut through
<p>
s. - Change the location and draw of the caption/percentage.
Customization
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 usingdisplay:inline
orfloat: …
attributes here may break the presentation. Do not usewidth
ormin-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 usewidth
ormin-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).
Example 1: — florious 2020-01-20 15:06
Internationalization
As of 1.8 RC, the plugin includes localized strings for the Configuration Manager and Plugin Manager2). 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.
Afterwords
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.
ChangeLog
See the repository for a copy of the Changelog.
Legalese
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.
Discussion
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:45Already 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