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
2010-12-08
Provides
Syntax

This extension has not been updated in over 2 years. It may no longer be maintained or supported and may have compatibility issues.

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

Quick Questions:
So you want to…
…install this plugin? Instructions
…check the syntax? Syntax
…check the support? Support
…see the plugin in action? Demo
…customize the styles? Customization
…read a legal disclaimer? Legalese
…read about the author? The Author

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

Download and install the plugin using the Plugin Manager using the URL given above. 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

Manual Install

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.

DokuWiki Support

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.

Browser Support

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.

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.

The Author

Luis Machuca Bezzaza3) 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

progrecss …you are here now LOL
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

Source Code

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

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
3)
yes, that's my name, and I'm going to talk in third person now
plugin/progrecss.txt · Last modified: 2017-09-18 00:13 by 2001:464a:6a6b:0:19b7:14f8:6b4b:abae