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:

{{Progress bar
| 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 progression-text parameter to display any text on the bar, or use the desc 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: People know me
• 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: explored
• default value: none
• note: if the progression-text parameter is used, the desc parameter is discarded.

progression

Indicates the percentage represented by the progression bar.

• ex: 74.2%
• 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 mode=value to make the text display the value of the current parameter instead of the calculated percentage
• default value: none; to get the default behavior, simply don't use this parameter.
• note: if the progression or progression-text parameter is used, the mode parameter is discarded.

min

Indicates the value of the lower bound of the range represented by this bar. Used to compute the percentage.

• 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. Used to compute the percentage. This number must be higher than the min value, otherwise no percentage will be computed and no bar will be shown.

• 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. Used to compute the percentage. This number must be contained between min and max, otherwise the value will be clamped when computing the bar size (it will still be displayed as is if mode=value, but will be displayed as ? when the effective percentage cannot be computed).

• ex: 13
• default value: same value as min
• note: if the progression parameter is used, the current parameter is discarded.

Optional styling parameters

title

Indicates the text displayed in the optional tooltip.

• ex: People know me
• default value: none

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-background

Color used as the background of the block in which the bar is located.

• ex: red or #328A9C
• default value: #FFF (white)

box-border

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

• ex: 2px dotted red
• default value: 1px solid #AAA (light gray)

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 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: 15em
• default value: none

bar-background

Color used as the background of the progression bar when it's visible.

• ex: red or #328A9C
• 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: 90%

text-weight

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

• default value: bold

text-color

Color of the text written in the center of the bar.

• default value: #222

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 first method is by simply specifying the progression 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 min, max and current parameters, and the percentage is calculated with the following formula: (current-min)/(max-min)*100%. Also the filling color of the gauge will be autocomputed from the same percentage in a linear range:
  
   

  0 %
  ,
   

  10 %
  ,
   

  25 %
  ,
   

  50 %
  ,
   

  75 %
  ,
   

  90 %
  ,
   

  100 %
  .

The examples below show how to use both methods.

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", title for the tooltip and progression-text 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 desc parameter if specified. However, if you used the second calculation method, then you can force the text to show the content of the current parameter instead of the percentage, by adding the mode=value 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:

{{Progress Bar
| progression = 52.4%
| desc = explored
}}

 

52.4% explored

{{Progress Bar
| progression = 52.4%
| desc = explored
| box-width = 15em
}}

 

52.4% explored

{{Progress Bar
| progression = 14.7%
| desc = explored
| title = exploration
| box-width = 15em
| text-size = 8pt
}}

 

14.7% explored

{{Progress Bar
| progression = 14.7%
| desc = explored
| progression-text = exploration
| box-width = 15em
| text-size = 8pt
}}

 

exploration

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

{{Progress Bar
| current = 52.4
}}

 

52.4 %

{{Progress Bar
| current = 52.4
| desc = complete
| box-width = 15em
}}

 

52.4 % complete

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

{{Progress Bar
| min = 10 | max = 15 | current = 13 | mode = value
| desc = maxed titles
| box-width = 15em
| box-border = 1px dotted black
| bar-background = #99CC66
| text-size = 8pt
}}

 

13 maxed titles

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

{{Progress Bar
| current = 131 | max = 250
| title = 131 / 250
}}

 

52.4 %

{{Progress Bar
| min = 10 | max = 15 | current = 13
| desc = maxed titles
| title = People Know Me (2)
| box-width = 15em
| text-size = 8pt
}}

 

60 % maxed titles

{{Progress Bar
| min = 10 | max = 15 | current = 13 | mode = value
| desc = maxed titles
| title = People Know Me (2)
| box-width = 15em
| text-size = 8pt
}}

 

13 maxed titles

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.
• Unfortunately, the url css attribute is not supported by mediawiki, so you can't set bar-background=url(path/to/image)