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:

{{Progress bar evolved
| param1 = value1
| param2 = value2
| etc.
}}

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 progression parameter, while the second uses the min, max and current parameters. Whatever method you use, you can use the barDisplayMode, barText, tooltipDisplayMode and tooltipText 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: 74.2%
• default value: 0%

min

Indicates the value of the lower bound of the range represented by this bar.

• ex: 10
• default value: 0
• note: if the progression parameter is used, the min parameter is discarded.

max

Indicates the value of the upper bound of the range represented by this bar.

• ex: 15
• default value: 100
• note: if the progression parameter is used, the max parameter is discarded.

current

Indicates the value of the position into the range represented by this bar. This number must be contained between min and max.

• ex: 13
• default value: 0
• note: if the progression parameter is used, the current 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 tooltip-display-mode 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:
  • percentage: display the percentage of this bar, followed by the value of the tooltip-text parameter if it not empty.
  • current: display the value of the current parameter, followed by the value of the tooltip-text parameter if it not empty. Choose this option only when using the second calculation method.
  • remaining: display the difference between the max parameter and the current parameter, followed by the value of the tooltip-text parameter if it not empty. Choose this option only when using the second calculation method.
  • ratio: display the current parameter followed by a slash ("/") and the max parameter, followed by the value of the tooltip-text parameter if it not empty. Choose this option only when using the second calculation method.
  • anything else means that only the tooltip-text will be displayed.
• default value: percentage

bar-text

The text displayed on the progress bar. Regarding the value of the bar-display-mode 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:
  • percentage: display the percentage of this bar, followed by the value of the bar-text parameter if it not empty.
  • current: display the value of the current parameter, followed by the value of the bar-text parameter if it not empty. Choose this option only when using the second calculation method.
  • remaining: display the difference between the max parameter and the current parameter, followed by the value of the bar-text parameter if it not empty. Choose this option only when using the second calculation method.
  • ratio: display the current parameter followed by a slash ("/") and the max parameter, followed by the value of the bar-text parameter if it not empty. Choose this option only when using the second calculation method.
  • anything else means that only the bar-text will be displayed.
• default value: percentage

bar-background

Color used as the background of the progression bar.

• ex: red or #328A9C
• default value: #AAD5FF

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: red or #328A9C
• default value: white

box-border

Style of the border of the block in which the bar is located.

• ex: 2px dotted red
• default value: 1px solid black

box-margin

Indicates how far the block in which the bar is located must be from the text around it.

• ex: 5px
• default value: 1px

box-padding

Indicates the width of the space between the progression bar and the border of the block around it.

• ex: 0
• default value: 1px

box-width

Indicates the width of the block in which the bar is located.

• ex: 15em
• default value: 100%

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: black

text-size

Size of the title and the text written in the center of the bar.

• default value: small

text-weight

Weight of the title and the text written in the center of the bar.

• default value: bold

Calculation methods

There are two methods you can use to make your bar represent a progression. The first method is by simply specifying the progression 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 min, max and current parameters, and the percentage is calculated with the following formula: ((current - min) / (max - min)) * 100. 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 tooltip-text, tooltip-display-mode, bar-text and bar-display-mode 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:

{{Progress bar evolved
| param1 = value1
| param2 = value2
| etc.
}}

you can define variables which will be used automatically by the template. You can do it this way:

{{#vardefine:pb-param1|value1}}
{{#vardefine:pb-param2|value2}}
{{Progress bar evolved
| other parameters
}}

Note that these special variable names all have the pb- prefix. Each parameter of the template has its variable counterpart, except for the percentage, min, max, current and title 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:

{{Progress bar evolved
| progression = 52.4%
| bar-text = explored
| tooltip-text = explored
}}

[[{{{1}}}]] / [[{{{2}}}]]

7777 / 10000 (2223)

77%

Styled progress bar, using the second method:

{{Progress bar evolved
| min = 10
| max = 15
| current = 13
| tooltip-text = maxed titles
| tooltip-display-mode = current
| bar-text = [[People Know Me]] (2)
| bar-display-mode = text
| box-width = 15em
| box-border = 1px dotted black
| bar-background = #99CC66
| text-size = 8pt
}}

[[{{{1}}}]] / [[{{{2}}}]]

7777 / 10000 (2223)

77%

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

{{Progress bar evolved
| min = 0
| max = 700
| current = 550
| bar-text = days before GW2 is released
| bar-display-mode = remaining
| tooltip-text = days have past since we started waiting for GW2
| tooltip-display-mode = current
| box-width = 25em
| bar-background = #328A9C
| bar-custom-style = border-radius:9px
| box-custom-style = border-radius:10px
}}

[[{{{1}}}]] / [[{{{2}}}]]

7777 / 10000 (2223)

77%

Defining variables:

{{#vardefine:pb-box-width|25em}}
{{#vardefine:pb-text-size|8pt}}
{{#vardefine:pb-bar-background|#FFD5AA}}

{{#vardefine:pb-box-width|25em}}{{#vardefine:pb-text-size|8pt}}{{#vardefine:pb-bar-background|#FFD5AA}}

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

{{Progress bar evolved
| min = 0
| max = 25
| current = 14
| tooltip-display-mode = remaining
| tooltip-text = missions left
| bar-display-mode = ratio
| bar-text = missions
| title = [[Protector|Protector of Tyria (1)]]
}}

[[{{{1}}}]] / [[{{{2}}}]]

7777 / 10000 (2223)

77%

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

{{Progress bar evolved
| progression = 52.4%
| bar-text = explored
| tooltip-text = explored
| bar-background = #AAFFD5
}}

[[{{{1}}}]] / [[{{{2}}}]]

7777 / 10000 (2223)

77%

Notes

• Don't put the same value for the bar-background and the box-background parameters, or else you won't see the progression bar!
• If you want more information regarding authorized values for each parameter, please consult the CSS documentation on the W3C website.
• To learn CSS in a more friendly fashion, you can try the CSS tutorial on w3schools.
• Unfortunately, the url CSS attribute is not supported by mediawiki, so you can't set bar-background=url(path/to/image).

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 progression-text, mode and desc parameters have been removed
• The tooltip-text, tooltip-display-mode, bar-text and bar-display-mode parameters have been added
• The title parameter has a completely different meaning now
• The box-style and bar-style parameters have been renamed into box-custom-style and bar-custom-style respectively
• Added support for variables
• Added new display options for the text in the tooltip and on the bar, such as remaining and ratio