====== progrecss plugin ======
---- plugin ----
description: Create CSS-based progress bars.
author     : Luis Machuca Bezzaza
email      : luis.machuca [at] gulix.cl
type       : syntax
lastupdate : 2010-12-08
compatible :
depends    :
conflicts  :
similar    : progressbar
tags       : diagram, chart

downloadurl: http://ryan.gulix.cl/dw/_media/desarrollo/dokuwiki/dw-plugin-progrecss-latest.zip
bugtracker : # eg. http://github.com/ryan.chappelle/dokuwiki-plugin-noiewarning/issues
sourcerepo : # eg. http://github.com/ryan.chappelle/dokuwiki-plugin-noiewarning/
donationurl: # unavailable ATM

----

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?     | → [[#Download and Installation|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 "''[[#Parameters|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 [[phpfn>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:plugin|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 ''gauge''((I could not come with better names)).

Here come some usage examples:

<code>
<progrecss 25% />
</code>
Just a progress bar, quarter task done. No big deal.

<code>
<progrecss 1/7 />
</code>
Another simple progress bar, maybe indicating only one day of the week has passed.

<code>
<progrecss 50% caption=One to go; />
</code>
just like before, but this progress bar shows half progress done, and also shows with a caption below.

<code>
<progrecss 50% caption=One down\;One to go; />
</code>
just like the above, but with a semicolon as part of the parameters. Note that it is escaped in a C-like fashion.

<code>
<progrecss 50% caption=One-to-go;style=gauge; />
</code>
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.

<code>
Some text ... <progrecss 99% style=inline;caption=Almost_Done;width=200px; /> some more text...
</code>
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**:
<code>
<progrecss 50% caption=If this //doesn't// work, we should [[Google>progrecss plugin|consult Google]]. ;style=gauge; />
</code>

Support for wikitext is limited at the moment. __Underline__, ''monospace'', **bold**, //italics// and <del>strikethrough</del> work fine, and both [[:|internal]] and [[wp>Link|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 <nowiki>~~NOCACHE~~</nowiki> will most probably not be supported.

:!: Now with overrideable **percentage format**:
<code>
<progrecss 78% caption=At least we're almost done with this one. ;pdisplay=%03u; />
</code>
Will show the percentage value as "078%". This should ease compatibility with plugins and tools such as [[plugin:sortablejs]], in particular if the caption is left blank. Thanks to Gunnar Gorges for suggestions.

====Demo====

**Want to see the plugin in action?**

:!: [[http://ryan.gulix.cl/dw/desarrollo/dokuwiki/plugin-progrecss|(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]]!

^  {{http://ryan.gulix.cl/archivos/dokuwiki/scr-plugin-progrecss-01.png?direct}}  ^
|  The progrecss plugin in action   |

^  [[http://files.myopera.com/ryan.chappelle/albums/469908/progrecss-pics-firefox1.png|{{http://files.myopera.com/ryan.chappelle/albums/469908/thumbs/progrecss-pics-firefox1.png_thumb.jpg}}]]  |  Style displays of the **progrecss** plugin, with Firefox 2  |
^  {{http://ryan.gulix.cl/archivos/dokuwiki/scr-plugin-progrecss-02.png?direct}}  |  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:

  - Navigate to the ''lib/plugins'' directory in your DokuWiki installation.
  - Unpack the plugin there.
  - That should result in the creation of a ''progrecss'' directory with the contents of the plugin.
  - 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 ====

  - Add option to display either caption or percentage as gauge.
  - <del>Wait and</del> check for CSS3 rules.
  - <del>Add the actual percentage number as an option (in the works).</del> Done in 1.8 RC.
  - 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 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 Manager((expecting discussion on internationalization of plugin manager [[http://www.freelists.org/post/dokuwiki/Internationalization-in-plugin-descriptions-via-plugininfotxt|as per the mailing list]])). 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 Bezzaza((yes, that's my name, and I'm going to talk in third person now)) is a Chilean Developer who has released plugins for DokuWiki ever since 2008. He takes somewhat-active participation in the [[http://forum.dokuwiki.org/|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 [[wp>LUG]], [[http://www.gulix.cl/|Gulix]] as well as trying to contribute to the overall internet culture.

^    Other DokuWiki Plugins by\\ [[user>ryan.chappelle|Luis Machuca Bezzaza (a.k.a ryan.chappelle@DW Forums)]]   ^^
| [[plugin:progrecss]]      | ...you are here now LOL  |
| [[plugin:tooltip]]        | add tooltips (info balloons) to text or special words   |
| [[plugin:clock]]          | display the time in DokuWiki          |
| [[plugin:countdown]]      | show the remaining time to an event       |
| [[plugin:divalign2]]      | align your paragraphs for better reading      |
| [[plugin:gil]]            | display currency conversions from Yahoo services         |
| [[plugin:hide]]           | hide text from immediate view   |
| [[plugin: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}}; />%%
><del>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. --  --- //[[visuallucho_plusplus@yahoo.es|'Ryan Chappelle']] 2008/11/02 21:45// </del>
>>Already implemented, albeit in a limited manner. I would be glad if you can test it.  --- //[[luis.machuca@gulix.cl|Luis Machuca B.]] 2008/12/25 03:55//

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

----

<del>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.  --- //[[visuallucho_plusplus@yahoo.es|'Ryan Chappelle']] 2008/12/02 09:53//</del>
>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.machuca@gulix.cl|Luis]] 2010/09/01 22:57//