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

I'm ryan.chappelle a DW 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% />

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

Point the Plugin Manager to this location. That should do. If (note the “if”) the link does not work, navigate your browser th the Demo page below, there you'll find an available link.

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

1. Unpack the plugin file.
2. Navigate to your DokuWiki's plugins directory and create a folder called progrecss.
3. Copy the files syntax.php and style.css from the downloaded archive to the created folder.
4. Check that the permissions of the files and folder match those of other plugins.
5. Just in case, clean your DokuWiki cache.

Huh? Want to get your hands dirty and do everything by-hand? Just leap to the Source Code.

Demo site is now Up:

http://informatica.temuco.udelmar.cl/~lmachuca/dokuwiki-lucho/desarrollo/informatica/dokuwiki/plugin-progrecss

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

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

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

Here come some usage examples:

<progrecss 25% />

will show a two-color, one-quarter progress bar with the default style (block, green-and-purple-ish, full available width²⁾ ).

<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-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. As of 2008-05-12, Firefox 3 Beta is known to support those effects.

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. As of 2008-05-12, Both Firefox 3 Beta and Opera 9.5 Beta are known to support inlining for this element.

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.5 Beta and Firefox 1.5; results may greatly vary depending on your browser. Note that also because of the styles used, using this plugin may :!:report your wikipage breaks with CSS conformance (for example, most CSS validators do not recognize -moz-* keys, text-spacing, or radius properties yet).

A quick test reveals that the styles are handed correctly by the following browsers:

Notes:

1. shows OK, but you may experience layout scrambling such as, for example, the caption showing in a line of its own, or being “trimmed” when it is longer than the gauge itself.
2. the actual block shows correctly, but both the percentage value and the progress gauge will display or not, depending on the DokuWiki theme choice of colours.
3. Internet Explorer 5.5 and 6 only are officially supported. Anything else I just won't care.

Coming Up: pictures of the different browser's display of the plugin.

1. Add option to display either caption or percentage as gauge.
2. Improve visualization of full-width bars.
3. Wait and check for CSS3 rules.

Feel free to point your file navigator to the “plugins” directory of your Dokuwiki installation, create a folder called progrecss, and proceed to copy-paste-save the following contents:

progrecss/syntax.php:

<?php
 
/**
 * Progrecss Plugin: Prints CSS-based progress bars
 * 
 * @file       progrecss/syntax.php
 * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
 * @author     'ryan.chappelle' <visuallucho_plusplus@yahoo.es>
 * @brief      Progress bars with CSS only.
 * @version    1.2
 *
 *   This plugin is intended to follow the same purpose as the
 *  "progressbar" plugin already available in the DW site; 
 *  however, "progrecss"'s inner works are more based on 
 *  CSS code by David Anaxagoras by this URL:
 *   http://www.davidanaxagoras.com/2005/04/16/track-your-progress-or-lack-thereof/
 *
 *   With this plugin, you can create progress bars in your wiki pages, 
 *  using CSS styles only. The PHP side allows for some syntax and parameters
 *  such as bar caption, total width and style used.
 *
 *   For a live demo point your browser to:    http://informatica.temuco.udelmar.cl/~lmachuca/dokuwiki-lucho/desarrollo/informatica/dokuwiki/plugin-progrecss
 *  (in Spanish, neuter enough for online translator to 
 *  provide good translations)
 *
 *  Greetings.
 *        - ryan.chappelle
 */
 
 
if(!defined('DW_LF')) define('DW_LF',"\n");
 
if(!defined('DOKU_INC')) 
define('DOKU_INC',realpath(dirname(__FILE__).'/../../').'/');
if(!defined('DOKU_PLUGIN')) 
define('DOKU_PLUGIN',DOKU_INC.'lib/plugins/');
require_once(DOKU_PLUGIN.'syntax.php');
 
/**
 * All DokuWiki plugins to extend the parser/rendering mechanism
 * need to inherit from this class
 */
class syntax_plugin_progrecss extends DokuWiki_Syntax_Plugin {
 
    /**
     * return some info
     */
    function getInfo(){
        return array(
            'author' => 'ryan.chappelle',
            'email'  => 'visuallucho_plusplus@yahoo.es',
            'date'   => '02/01/2008',
            'name'   => 'Progrecss Plugin',
            'desc'   => 'Prints CSS-based progress bars',
            'url'    => 'http://www.dokuwiki.org/plugin:progrecss',
        );
    }
 
    /**
     * What kind of syntax are we?
     */
    function getType(){
        return 'substition';
    }
 
    /**
     * What can we Do?
     */
    function getAllowedTypes() { 
        return array('formatting', 'substition', 'disabled'); 
    }
 
    /**
     * Where to sort in?
     */
    function getSort(){
        return 149;
        // note: I just came up with a number. I'm still not sure 
        // how to correctly use this thing.
    }
 
    /**
     * What's our code layout?
     */    
    function getPType(){ 
        return 'normal'; 
    }
 
    /**
     * How do we get to the lexer?
     */
    function connectTo($mode) {
         $p_param= ".*?";
 
/** Probably I have a bug in my PHP implementation (compiled source code) 
 *  which prevents me from using a single regex to catch percentages.
 *  Momentarily I am providing two regexes, they should be fine.
 */
 
         $this->Lexer->addSpecialPattern ("<progrecss [0-9]{1,2}% $p_param/>", $mode, 'plugin_progrecss');
         $this->Lexer->addSpecialPattern ("<progrecss 100% $p_param/>", $mode, 'plugin_progrecss');
 
    }
 
    /**
     * Handle the match
     */
    function handle($match, $state, $pos, &$handler){
 
        /* The syntax is expected as follows:
          ppp% [param1=value1; [param2=value2; [...]]] 
         */
        $data= array();
        $expected_params= array(
          "caption", // the progrecss bar item caption
          "style",   // the CSS style used, as in 'progrecss_<stylename>'
          "width",   // the CSS width value for the block
          "order",   // --- reserved for future use ---
          "marker",  // --- reserved for future use ---
          "pdisplay" // --- reserved for future use ---
          );
        /* OK, so let's strip the markup, taking first the precentage%
           value which is _mandatory_. */
        $match = substr($match,11,-2); // Strip markup
        $match= explode(' ', $match, 2);
        $data['p']= $match[0];
        /* That already done, let's split all other elements, which are 
           expected to be in the 'param=value;' format.*/
        $elems= explode(';',$match[1]);
        foreach ($elems as $pair) {
           list($key,$value)= explode('=', $pair, 2);
           trim($key); trim($value);
           /* we check if the param is valid (exists in 'expected_params'), 
              otherwise we just choose to ignore it.
              (yes, something better could've been done) */
           if  (in_array($key, $expected_params) ) { //accept parameter
              $data[$key]= $value;
           } else { //refuse parameter
           }
        }
        /* At this point, if any of the available parameters was 
           not found, let's apply some sane default. */
        if (empty($data['caption']))   $data['caption']= "Caption";
        if (empty($data['style'])  )   $data['style']= "default";
        if (empty($data['width'])  )   $data['width']= "200px";
 
        $data['style']= "progrecss_". $data['style'];
 
        /* In order to somewhat uniquely IDfy each p-bar, let's mix and 
           spice using some of the available parameters. */
        $temp_ID= "p-bar_";
        if (strlen($data['caption'] > 6)) {
           $IDcap= substr($data['caption'], 6, 0);
        } else {
           $IDcap= "cap". rand(1,9);
           }
        $IDnum= sprintf("w%02ds%02xr%04d", 
                (int)substr($data['width'], 2, 0), 
                (int)substr($data['style'], -1, 1), 
                rand(1000,9999) );
        /* Did I already warn you that this futile effort is NOT guaranteed 
           to generate a fully unique ID? */
 
        $data['id']= $temp_ID. $IDcap. $IDnum;
 
        /* Are we ready yet? */
        return $data;
 
    }  
 
    /**
     * Create output
     */
    function render($mode, &$renderer, $data) {
        if($mode == 'xhtml'){
            $percentage=  $data['p'];
            $id= $data['id'];
            $fullwidth=   $data['width'];
            $caption= $data['caption'];
            $style= $data['style']; 
 
            /* each progrecssbar is enclosed in a DIV of its own, 
               classed according to "style" parameter,
               and IDed in a somewhat-unique manner using both caption
               and random binary toughts. */
            $renderer->doc .= DW_LF. '<div class="'. $style. '" ';
            $renderer->doc .= 'id="'. $id. '">'. DW_LF;
            $renderer->doc .= '  <div class="border" style="width: '. $fullwidth. ';">'. DW_LF;
            /* The next 2-liner contains the actual "intelligence" behind 
               the plugin. The rest is simply "ability".*/
            $renderer->doc .= '  <div class="bar" style="width: '. $percentage. ';">';
            $renderer->doc .= $percentage. '</div>'. DW_LF;
            /* See? A PHP+CSS is as powerful as... */
            $renderer->doc .= '  </div>'. DW_LF;
            $renderer->doc .= '  <span class="caption">'. $caption. '</span>';
            $renderer->doc .= DW_LF;
            $renderer->doc .= '</div>';
            return true;
        }
        /* That's all about rendering that needs to be done, at the moment */
        /* edit 2008-06-01: maybe in the futur I may try some ODT support,
           guess it would be REALLY nice for printed documents.
        */
        return false;
    }
 
}

progrecss/style.css:

/** @file     progrecss/style.css
 *  @brief    Default stylesheets for progrecss plugin
 *  @author   'ryan.chappelle' <visuallucho_plusplus@yahoo.es>
 *  @version  1.2
 *  @license  GPL v2
 */
 
/** This file provides three (3) default styles for the "progrecss"
 *  (CSS-based progress bars) plugin for Dokuwiki.
 */
 
 
 
/** 
 * -------------------------------------------------------
 *   PROGRECSS_DEFAULT: default bar model
 * -------------------------------------------------------
 *
 *
 * Features: theme-aware box (non rounded) with background color
 *      matching the background options, green gauge (or the same 
 *      color available links have) and black borders.
 * Support : pretty much all browsers since 2005 should 
 *      display this correctly.
 */
 
.progrecss_default {
	display: block; 
	margin-top: 10px;
	margin-right: 20px;
	margin-bottom: 10px;
	border-bottom: 1px dotted black;
	}
 
 
.progrecss_default .border {
	display: block;
	height: 1.2em;
	border: 2px solid __text__;
	background-color: __text_alt__;
	padding: 0;
	}
 
.progrecss_default .border .bar {
	display: block;
	height: 0.5em;
	margin: 0;
	padding: 0;
	border-bottom: 4px solid __existing__;
	border-right: 1px solid __background_alt__;
	background-color: __existing__;
	color: #ffffff;
	text-align: center;
	font-size: 75%;
	}
 
.progrecss_default .caption {
	display: inline-block;
	font-family: Helvetica, Arial;
	font-size: 75%;
	text-align: center;
	margin-left: 10px;
	}
 
/**
 * -------------------------------------------------------
 *   PROGRECSS_INLINE: inline bar model
 * -------------------------------------------------------
 *
 * Features: inline-block display model, gauge is located "on top" of the 
 *     bar itself , allowing flow of text (percentage) below. 
 *     Caption is _not_ visible. Color set uses red/"missing link"
 *     for the gauge and green/"existing link" for the progress.
 * Support : Opera 9.2 and later seem to be OK with this style, albeit 
 *     breaking lines strangely when an inline-block is last element of 
 *     the line. Firefox prior to 2.0 require a CSS fix but otherwise 
 *     seem to be OK. IE's support is untested but we all _know_ it is 
 *     completely broken (if any).
 */
 
.progrecss_inline {
	display: -moz-inline-box; /* Firefox < 2.0 seems to require this*/	
	display: inline-block;
	margin-left: 5px;
	margin-right: 5px;
	min-width: 50px; /* to prevent inline misoffsetting when % is too low */
	}
 
 
.progrecss_inline .border {
	display: -moz-inline-box; /* Firefox < 2.0 seems to require this*/
	display: inline-block; /* Opera 9.2+ and Firefox 2.0+ seem to be OK here*/
	height: 0.25em;
	margin-top: -0.1em; /* this will break with very packed paragraphs */
	margin-bottom: 0;
	background-color: __missing__;
	}
 
.progrecss_inline .border .bar {
	display: inline-block; /* Opera 9.2+ and Firefox 2.0+ seem to be OK here*/
	height: 0.1em;
	background-color: __existing__;
	border: 0;
	text-align: center;
	font-size: 75%;
	color: gray;
	}
 
.progrecss_inline .caption {
	display: none;
	}
 
/**
 * -------------------------------------------------------
 *   PROGRECSS_GAUGE: rounder bar with label model
 * -------------------------------------------------------
 *
 * Features: this one makes use of a rounded box, with the gauge block 
 *     running inside, and the caption as a label aside/below
 *     (depends on browser implementation). Works wonders when floated. 
 *     Color theme is black gauge and caption over a
 *     red/"missing link" border rounded box.
 *     bar itself using background and rounded attributes; caption 
 *     is shown aside (may break on long lines).
 * Support : Firefox will support this flawlessly at least from
 *     version 2.0 onwards. Other browsers (except IE) may have 
 *     minor presentation variances, such as Opera not supporting
 *     "rounded" or IE displaying the caption below the gauge 
 *     and in a block of its own.
 */
 
.progrecss_gauge {
	display: block; 
	margin-top: 0;
	margin-bottom: 0;
	border: 2px solid __missing__;
	padding-left: 4px;
	padding-right: 4px;
	-moz-border-radius: 10px;
	-khtml-border-radius: 10px;
	border-radius: 10px;
	}
 
 
.progrecss_gauge .border {
	display: -moz-inline-block;
	display: inline-block;
	height: 1.2em;
	margin: 0;
	padding: 2px;
	background-color: white;
	-moz-border-radius: 4px;
	-khtml-border-radius: 4px;
	border-radius: 4px;
	}
 
.progrecss_gauge .border .bar {
	display: block;
	height: 1.4em;
	margin-top: -0.2em;
	padding: 0;
	background-color: black;
	text-align: center;
	font-size: 0.75em;
	color: white;
	-moz-border-radius: 4px;
	-khtml-border-radius: 4px;
	border-radius: 4px;
	}
 
.progrecss_gauge .caption {
	display: inline;
	font-family: Helvetica, Arial;
	font-size: 75%;
	text-spacing: 0.1em;
	text-align: center;
	margin-left: 0;
	margin-right: 1em;
	padding-left: 5px;
	border-left: 1px dotted black;
	}
 

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 edit 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 collegue 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

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