Asnath: Created page with "== Description == This template is the evolution of the Progress bar template. It adds cool new features and overall simplicity and customizability to t..."

2016-04-02T05:34:23Z

Created page with "== Description == This template is the evolution of the Progress bar template. It adds cool new features and overall simplicity and customizability to t..."

New page

== Description ==
This template is the evolution of the [[Template:Progress bar|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:
<pre>{{Progress bar evolved
| param1 = value1
| param2 = value2
| etc.
}}</pre>

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

; min
: Indicates the value of the lower bound of the range represented by this bar.
:* ex: <code>10</code>
:* default value: <code>0</code>
:* note: if the <code>progression</code> parameter is used, the <code>min</code> parameter is discarded.

; max
: Indicates the value of the upper bound of the range represented by this bar.
:* ex: <code>15</code>
:* default value: <code>100</code>
:* note: if the <code>progression</code> parameter is used, the <code>max</code> parameter is discarded.

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

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

; bar-background
: Color used as the background of the progression bar.
:* ex: <code>red</code> or <code>#328A9C</code>
:* default value: <code>#AAD5FF</code>

; 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: <code>red</code> or <code>#328A9C</code>
:* default value: <code>white</code>

; box-border
: Style of the border of the block in which the bar is located.
:* ex: <code>2px dotted red</code>
:* default value: <code>1px solid black</code>

; box-margin
: Indicates how far the block in which the bar is located must be from the text around it.
:* ex: <code>5px</code>
:* default value: <code>1px</code>

; box-padding
: Indicates the width of the space between the progression bar and the border of the block around it.
:* ex: <code>0</code>
:* default value: <code>1px</code>

; box-width
: Indicates the width of the block in which the bar is located.
:* ex: <code>15em</code>
:* default value: <code>100%</code>

; 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: <code>black</code>

; text-size
: Size of the title and the text written in the center of the bar.
:* default value: <code>small</code>

; text-weight
: Weight of the title and the text written in the center of the bar.
:* default value: <code>bold</code>

=== Calculation methods ===
There are two methods you can use to make your bar represent a progression.
The first method is by simply specifying the <code>progression</code> 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 <code>min</code>, <code>max</code> and <code>current</code> parameters, and the percentage is calculated with the following formula: <code>((current - min) / (max - min)) * 100</code>.
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 <code>tooltip-text</code>, <code>tooltip-display-mode</code>, <code>bar-text</code> and <code>bar-display-mode</code> 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:
<pre>{{Progress bar evolved
| param1 = value1
| param2 = value2
| etc.
}}</pre>
you can define variables which will be used automatically by the template. You can do it this way:
<pre>{{#vardefine:pb-param1|value1}}
{{#vardefine:pb-param2|value2}}
{{Progress bar evolved
| other parameters
}}</pre>
Note that these special variable names all have the ''pb-'' prefix. Each parameter of the template has its variable counterpart, except for the <code>percentage</code>, <code>min</code>, <code>max</code>, <code>current</code> and <code>title</code> 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:'''
<pre>{{Progress bar evolved
| progression = 52.4%
| bar-text = explored
| tooltip-text = explored
}}</pre>
{{Progress bar evolved
| progression = 52.4%
| bar-text = explored
| tooltip-text = explored
}}

'''Styled progress bar, using the second method:'''
<pre>{{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
}}</pre>
{{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
}}

'''Custom style example (here using the CSS3 border-radius attribute):'''
<pre>{{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
}}</pre>
{{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
}}

'''Defining variables:'''
<pre>{{#vardefine:pb-box-width|25em}}
{{#vardefine:pb-text-size|8pt}}
{{#vardefine:pb-bar-background|#FFD5AA}}</pre>
{{#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:'''
<pre>{{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)]]
}}</pre>
{{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)]]
}}

'''You can override a variable setting by using the corresponding parameter:'''
<pre>{{Progress bar evolved
| progression = 52.4%
| bar-text = explored
| tooltip-text = explored
| bar-background = #AAFFD5
}}</pre>
{{Progress bar evolved
| progression = 52.4%
| bar-text = explored
| tooltip-text = explored
| bar-background = #AAFFD5
}}

== 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 [http://www.w3.org/TR/CSS21/ CSS documentation on the W3C website].
* To learn CSS in a more friendly fashion, you can try the [http://www.w3schools.com/css/default.asp CSS tutorial on w3schools].
* Unfortunately, the <code>url</code> CSS attribute is not supported by mediawiki, so you can't set <code>bar-background=url(path/to/image)</code>.

== Change log ==
Here is a list of everything that has changed between [[Template:Progress bar|the original progress bar]] and this new version:
* The name of the template has changed (wow!)
* The <code>progression-text</code>, <code>mode</code> and <code>desc</code> parameters have been removed
* The <code>tooltip-text</code>, <code>tooltip-display-mode</code>, <code>bar-text</code> and <code>bar-display-mode</code> parameters have been added
* The <code>title</code> parameter has a completely different meaning now
* The <code>box-style</code> and <code>bar-style</code> parameters have been renamed into <code>box-custom-style</code> and <code>bar-custom-style</code> respectively
* Added support for variables
* Added new display options for the text in the tooltip and on the bar, such as <code>remaining</code> and <code>ratio</code>

Template:Progress bar evolved/doc - Revision history

Asnath: Created page with "== Description == This template is the evolution of the Progress bar template. It adds cool new features and overall simplicity and customizability to t..."