DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:progrecss

progrecss Plugin

Compatible with DokuWiki

No compatibility info given!

plugin Create CSS-based progress bars.

Last updated on
2018-03-27
Provides
Syntax

Similar to progressbar

Tagged with chart, diagram

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 nd (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 gauge1).

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!

The progrecss plugin in action
files.myopera.com_ryan.chappelle_albums_469908_thumbs_progrecss-pics-firefox1.png_thumb.jpg Style displays of the progrecss plugin, with Firefox 2
A better look of the three base styles, under Opera 10.0.

Details

Things to Be Done

  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.

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

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

The Demo page holds a changelog for the latest release.

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: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
1)
I could not come with better names
2)
expecting discussion on internationalization of plugin manager as per the mailing list
plugin/progrecss.txt · Last modified: 2018-06-05 22:12 by Klap-in