Template:Progress Bar/doc

Description
This template allows you to create a highly customizable progress bar anywhere in a wiki page. Just call it this way:

Parameters
Here is the list of accepted parameters and their effect on the progress bar. There are two ways of indicating the value (percentage) represented by the bar. The first method uses the  parameter, while the second uses the ,   and   parameters. Whatever method you use, you can use the  parameter to display any text on the bar, or use the   parameter which writes down the percentage represented by the bar before the text contained in this parameter. See examples below.

Gauge value parameters

 * progression-text
 * Indicates the text written on the progression bar. If not specified, the text is determined automatically. See explanations below.
 * ex:
 * default value: none


 * desc
 * Indicates the text to be displayed on the bar, behind the progress percentage or current value represented by the bar.
 * ex:
 * default value: none
 * note: if the  parameter is used, the   parameter is discarded.


 * progression
 * Indicates the percentage represented by the progression bar.
 * ex:
 * default value: none


 * mode
 * Indicates which of the percentage or the current value is to be displayed on the bar. Used only if the second method is used.
 * specify  to make the text display the value of the   parameter instead of the calculated percentage
 * default value: none; to get the default behavior, simply don't use this parameter.
 * note: if the  or   parameter is used, the   parameter is discarded.


 * min
 * Indicates the value of the lower bound of the range represented by this bar. Used to compute the percentage.
 * ex:
 * default value:
 * note: if the  parameter is used, the   parameter is discarded.


 * max
 * Indicates the value of the upper bound of the range represented by this bar. Used to compute the percentage. This number must be higher than the  value, otherwise no percentage will be computed and no bar will be shown.
 * ex:
 * default value:
 * note: if the  parameter is used, the   parameter is discarded.


 * current
 * Indicates the value of the position into the range represented by this bar. Used to compute the percentage. This number must be contained between  and , otherwise the value will be clamped when computing the bar size (it will still be displayed as is if  , but will be displayed as   when the effective percentage cannot be computed).
 * ex:
 * default value: same value as
 * note: if the  parameter is used, the   parameter is discarded.

Optional styling parameters

 * title
 * Indicates the text displayed in the optional tooltip.
 * ex:
 * default value: none


 * box-margin
 * Indicates how far the block in which the bar is located must be from the text around it.
 * ex:
 * default value:


 * box-background
 * Color used as the background of the block in which the bar is located.
 * ex:  or
 * default value:  (white)


 * box-border
 * Style of the border of the block in which the bar is located.
 * ex:
 * default value:  (light gray)


 * box-padding
 * Indicates the width of the space between the progression bar and the border of the block around it.
 * ex:
 * default value:


 * box-width
 * Indicates the width of the inner box in which the bar and the central text is located. That box will autoadjust to a minimum width of 5em for the content, it may be set to a larger value if there's a longer description displayed and can it fit in the container block between lateral margins and paddings (that description text may still have wrapped lines below the first line where the colored bar is drawn in the background). You may set it to 100% to fit the progress bar to the width of a table cell.
 * ex:
 * default value: none


 * bar-background
 * Color used as the background of the progression bar when it's visible.
 * ex:  or
 * default value: none; color determined from the clamped percentage converted linearily between #F33 (red, when progress <= 0%) and #0F0 (green when progress >= 100%)


 * text-size
 * Size of the text written in the center of the bar.
 * default value:


 * text-weight
 * Weight of the text written in the center of the bar.
 * default value:


 * text-color
 * Color of the text written in the center of the bar.
 * default value:

Calculation methods
There are two methods you can use to make your bar represent a progression. If both methods are used, the first one takes precedence: ,, , , , , . The examples below show how to use both methods.
 * The first method is by simply specifying the  parameter. You tell the value in percentage and the bar simply shows it.
 * The second method can be used when you want to display a bar showing progression through a finite set of values. You give the,   and   parameters, and the percentage is calculated with the following formula:  . Also the filling color of the gauge will be autocomputed from the same percentage in a linear range:

How the text displayed on the bar is determined
The tooltip and the bar are the two "zones" where text is displayed on the progression bar. Each one has its own "master parameter",  for the tooltip and   for the bar. If you provide one of these parameters, you will see the text you entered in the corresponding area. If you skip one of these parameters (or both), the text which is displayed is determined automatically. It consists of the percentage represented by the bar (whether given directly through the first method or calculated through the second), followed by the content of the  parameter if specified. However, if you used the second calculation method, then you can force the text to show the content of the  parameter instead of the percentage, by adding the   parameter to your template call. Note: to see the tooltip, just put your mouse over the bar. A little box containing the tooltip text should appear.

Examples
Simple progress bar, using the first method with a static bar color:

(note: desc is ignored because progression-text is used)

Simple progress bar, using the second method with default min=0 and max=100, and computed color for the bar:

Styled progress bar, using the second method with computed percentage, and computed color for the bar:

Simple progress bar, using the second method with computed percentage, computed color for the bar, and a tooltip title: