Template:Progress bar evolved/doc

Description
This template is the evolution of the Progress bar template. It adds cool new features and overall simplicity and customizability to the way you call the template. If you have not figured it out yet, 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,  ,   and   parameters to control which text is displayed on the bar and in the tooltip. See examples below.


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


 * min
 * Indicates the value of the lower bound of the range represented by this bar.
 * 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.
 * 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. This number must be contained between  and.
 * ex:
 * default value:
 * note: if the  parameter is used, the   parameter is discarded.


 * title
 * Displays a title on top of the bar.


 * tooltip-text
 * The text displayed in the tooltip. Regarding the value of the  parameter, there may be other text displayed before this one in the tooltip.


 * tooltip-display-mode
 * Controls how text is displayed in the tooltip.
 * Possible values are:
 * : display the percentage of this bar, followed by the value of the  parameter if it not empty.
 * : display the value of the  parameter, followed by the value of the   parameter if it not empty. Choose this option only when using the second calculation method.
 * : display the difference between the  parameter and the   parameter, followed by the value of the   parameter if it not empty. Choose this option only when using the second calculation method.
 * : display the  parameter followed by a slash ("/") and the   parameter, followed by the value of the   parameter if it not empty. Choose this option only when using the second calculation method.
 * anything else means that only the  will be displayed.
 * default value:


 * bar-text
 * The text displayed on the progress bar. Regarding the value of the  parameter, there may be other text displayed before this one on the bar.


 * bar-display-mode
 * Controls how text is displayed on the progress bar.
 * Possible values are:
 * : display the percentage of this bar, followed by the value of the  parameter if it not empty.
 * : display the value of the  parameter, followed by the value of the   parameter if it not empty. Choose this option only when using the second calculation method.
 * : display the difference between the  parameter and the   parameter, followed by the value of the   parameter if it not empty. Choose this option only when using the second calculation method.
 * : display the  parameter followed by a slash ("/") and the   parameter, followed by the value of the   parameter if it not empty. Choose this option only when using the second calculation method.
 * anything else means that only the  will be displayed.
 * default value:


 * bar-background
 * Color used as the background of the progression bar.
 * ex:  or
 * default value:


 * bar-custom-style
 * Any additional values inside the style="" attribute for the bar. Values here overwrite default values.


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


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


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


 * 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 block in which the bar is located.
 * ex:
 * default value:


 * box-custom-style
 * Any additional values inside the style="" attribute for the box. Values here overwrite default values.


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


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


 * text-weight
 * Weight of the title and 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. The first method is by simply specifying the  parameter. You tell the percentage and the bar shows it. Simple. 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:. If both methods are used, the first one takes precedence. The examples below show how to use both methods.

Display options
You can control precisely what is displayed on the bar and in the tooltip using the,  ,   and   parameters. The *-display-mode parameters let you select how the progression is rendered as text, and the *-text parameters let you add custom text behind the progression. See the documentation of these parameters above for further details. The examples below also show how to customize the tooltip and the text on the bar. Just try a few combinations to find which options fit your needs!

Alternate way of passing parameters to the template: using the variables extension
Instead of passing your parameters in the template call, like this: you can define variables which will be used automatically by the template. You can do it this way:

Note that these special variable names all have the pb- prefix. Each parameter of the template has its variable counterpart, except for the,  ,  ,   and   parameters. Just add pb- (as in "Progress Bar") in front of the parameter name to know the variable name. This feature can be extremely useful when you want to display several progression bars in the same page. Just define the appearance of your bars through variables and then all the bars in your page will use the same values, making it unnecessary to provide the associated parameters in each of your template calls. Please note however, that if you define a variable and then provide the associated parameter in a template call, the parameter takes precedence. This way you can override a variable value by using the parameter. This overriding affects only the bar built by the specific template call on which you specified the parameter.

Examples
Simple progress bar, using the first method:

Styled progress bar, using the second method:

Custom style example (here using the CSS3 border-radius attribute):

Defining variables:

The following bars all use the "theme" defined by the variables:

You can override a variable setting by using the corresponding parameter:

Change log
Here is a list of everything that has changed between the original progress bar and this new version:
 * The name of the template has changed (wow!)
 * The,   and   parameters have been removed
 * The,  ,   and   parameters have been added
 * The  parameter has a completely different meaning now
 * The  and   parameters have been renamed into   and   respectively
 * Added support for variables
 * Added new display options for the text in the tooltip and on the bar, such as  and