Difference between revisions of "Template:Bartable/doc"

From blackwiki
Jump to navigation Jump to search
imported>Timwi
m (→‎Usage: improve explanation a bit)
imported>Timwi
(some more improvements)
Line 2: Line 2:
 
<!-- Categories and interwikis go at the bottom of this page. -->
 
<!-- Categories and interwikis go at the bottom of this page. -->
  
This template adds an inline bar graph to tables with numeric (including negative) values that a reader may wish to compare. It takes up either 2 or 3 columns &mdash; determined by the sign of the third (''scale'') parameter &mdash; of a table, so headers should have '''colspan="2"''' or '''colspan="3"''' (or similar combinations), respectively, to correctly span the columns.
+
This template adds an inline bar graph to tables with numeric (including negative) values that a reader may wish to compare.
 +
 
 +
Use this template inside a table. The template generates either two table cells (for cases in which all values are positive) or three (to accomodate negative bars going off to the left). Thus, your table headers should have '''colspan="2"''' or '''colspan="3"''' (or similar combinations), respectively, to correctly span the columns.
 +
 
 +
The template generates two cells if the ''scale'' parameter is positive and three if it is negative.
  
 
== Usage ==
 
== Usage ==
Line 8: Line 12:
 
  <nowiki>{{</nowiki>bartable|''value''|''unit''|''scale''|''height''|''style''<nowiki>}}</nowiki>
 
  <nowiki>{{</nowiki>bartable|''value''|''unit''|''scale''|''height''|''style''<nowiki>}}</nowiki>
  
* ''value'' (mandatory) is any real number or math expression that evaluates to a number. Commas can be used to [[Digit_grouping|group digits]]. See [[Help:Calculation]] for the syntax for math expressions.
+
; ''value'' (mandatory) : any real number or math expression that evaluates to a number. Commas can be used to [[Digit_grouping|group digits]]. See [[Help:Calculation]] for the syntax for math expressions.
* ''unit'' (default: empty string) is the unit (to be appended to ''value''). Add a space if you want a space between the value and the unit. If ''unit'' starts with "''/''", the value is converted between units (using the '''[[Template:Convert|convert]]''' template) as follows:
+
; ''unit'' (default = empty string) : the unit, e.g. "m" for metres. Add a space if you want a space between the value and the unit. If ''unit'' starts with "''/''", the value is converted between units (using the '''[[Template:Convert|convert]]''' template) as follows:
:"''/unit1/unit2/round''" converts the value from ''unit1'' to ''unit2'' and rounds it to ''round'' decimal places (using <code><nowiki>{{</nowiki>convert|''value''|''unit1''|''unit2''|''round''|abbr=on<nowiki>}}</nowiki></code>). Unfortunately ''unit1'', ''unit2'' or ''round'' cannot contain a "''/''" or a "=" — if anyone knows how to allow it (or translate other characters to it), please help.
+
:: "''/unit1/unit2/round''" converts the value from ''unit1'' to ''unit2'' and rounds it to ''round'' decimal places (using <code><nowiki>{{</nowiki>convert|''value''|''unit1''|''unit2''|''round''|abbr=on<nowiki>}}</nowiki></code>). Unfortunately ''unit1'', ''unit2'' or ''round'' cannot contain a "''/''" or a "=" — if anyone knows how to allow it (or translate other characters to it), please help.
* ''scale'' (default: "1") is a factor multiplied by ''value'' to give the width of the bar in pixels.
+
; ''scale'' (default = 1) : a factor multiplied by ''value'' to give the width of the bar in pixels. Use the same scale in every row, as otherwise the bar chart won’t be to scale!
:Note: If ''scale'' is negative, an additional column (for showing negative values) is created. See [[#3-column (positive and negative values)|example below]].
+
: ''scale'' can be negative, in which case an additional column (for showing negative values) is created. See [[#3-column (positive and negative values)|example below]].
* ''height'' (default: "2ex") is the height of the bar as a [[cascading style sheet|CSS]] measurement e.g. "1em" or "16px".
+
; ''height'' (default = "2ex") : the height of the bar as a [[cascading style sheet|CSS]] measurement e.g. "1em" or "16px".
* ''style'' (default: empty string) is the content of a CSS style string to apply to the bar e.g. "background:red;".
+
; ''style'' (default = empty string) : a CSS style string to apply to the bar, e.g. "background:red;".
  
 
== Examples ==
 
== Examples ==

Revision as of 14:41, 5 June 2011

This template adds an inline bar graph to tables with numeric (including negative) values that a reader may wish to compare.

Use this template inside a table. The template generates either two table cells (for cases in which all values are positive) or three (to accomodate negative bars going off to the left). Thus, your table headers should have colspan="2" or colspan="3" (or similar combinations), respectively, to correctly span the columns.

The template generates two cells if the scale parameter is positive and three if it is negative.

Usage

{{bartable|value|unit|scale|height|style}}
value (mandatory) 
any real number or math expression that evaluates to a number. Commas can be used to group digits. See Help:Calculation for the syntax for math expressions.
unit (default = empty string) 
the unit, e.g. "m" for metres. Add a space if you want a space between the value and the unit. If unit starts with "/", the value is converted between units (using the convert template) as follows:
"/unit1/unit2/round" converts the value from unit1 to unit2 and rounds it to round decimal places (using {{convert|value|unit1|unit2|round|abbr=on}}). Unfortunately unit1, unit2 or round cannot contain a "/" or a "=" — if anyone knows how to allow it (or translate other characters to it), please help.
scale (default = 1) 
a factor multiplied by value to give the width of the bar in pixels. Use the same scale in every row, as otherwise the bar chart won’t be to scale!
scale can be negative, in which case an additional column (for showing negative values) is created. See example below.
height (default = "2ex") 
the height of the bar as a CSS measurement e.g. "1em" or "16px".
style (default = empty string) 
a CSS style string to apply to the bar, e.g. "background:red;".

Examples

Real-world example

{| class="wikitable"
|+ Melting point at 1 atmosphere
! Substance  !! Temperature !! colspan="2" | Relative size
|-
| Mercury    || {{bartable| -38.72|/C/F|-2|1em|background:silver}}
|-
| Bromine    || {{bartable|  -7.10|/C/F|-2|1em|background:brown}}
|-
| Water      || {{bartable|      0|/C/F|-2|1em}}
|-
| Phosphorus || {{bartable|  44.10|/C/F|-2|1em|background:red}}
|-
| Iodine     || {{bartable| 113.50|/C/F|-2|1em|background:indigo}}
|-
| Sulphur    || {{bartable| 115.36|/C/F|-2|1em|background:yellow}}
|}
Melting point at 1 atmosphere
Substance Temperature Relative size
Mercury −38.72 °C (−37.70 °F)
 
Bromine −7.10 °C (19.22 °F)
 
Water 0 °C (32 °F)
Phosphorus 44.10 °C (111.38 °F) 44.1
 
Iodine 113.50 °C (236.30 °F) 113.5
 
Sulphur 115.36 °C (239.65 °F) 115.36
 

2-column (only positive values)

{| class="wikitable"
! Example                     || colspan="2" | Rendering
|-
| Only value                  || {{subst:Hidden/sandbox|272}}
|-
| Negative value              || {{subst:Hidden/sandbox|-72}}
|-
| Math expression             || {{subst:Hidden/sandbox|exp(1)*1e2}}
|-
| Value and ordinary unit     || {{subst:Hidden/sandbox|272| km/h}}
|-
| Value and convert unit      || {{subst:Hidden/sandbox|272|/km/nmi}}
|-
| Value and scale             || {{subst:Hidden/sandbox|272||1/(2^0.5)}}
|-
| Value and height            || {{subst:Hidden/sandbox|272|||4px}}
|-
| Value and style             || {{subst:Hidden/sandbox|272||||background:blue;}}
|-
| Value with commas and scale || {{subst:Hidden/sandbox|2,720||.1}}
|-
| The full monty              || {{subst:Hidden/sandbox|18^2|%|sin(1)|2em|border:ridge red;}}
|-
|}
Example Rendering
Only value 272
Negative value -72
Math expression exp(1)*1e2
Value and ordinary unit 272 km/h
Value and convert unit 272 km (147 nmi)
Value and scale 272
Value and height 272
Value and style 272
Value with commas and scale 2,720
The full monty 18^2%

3-column (positive and negative values)

{| class="wikitable"
! Example                     || colspan="3" | Rendering
|-
| Only value                  || {{subst:Hidden/sandbox|272||-1}}
|-
| Negative value              || {{subst:Hidden/sandbox|-72||-1}}
|-
| Math expression             || {{subst:Hidden/sandbox|exp(1)*1e2||-1}}
|-
| Value and ordinary unit     || {{subst:Hidden/sandbox|272| km/h|-1}}
|-
| Value and convert unit      || {{subst:Hidden/sandbox|272|/km/mi|-1}}
|-
| Value and scale             || {{subst:Hidden/sandbox|272||-1/(2^0.5)}}
|-
| Value and height            || {{subst:Hidden/sandbox|272||-1|4px}}
|-
| Value and style             || {{subst:Hidden/sandbox|272||-1||background:blue;}}
|-
| Value with commas and scale || {{subst:Hidden/sandbox|2,720||-.1}}
|-
| The full monty              || {{subst:Hidden/sandbox|18^2|%|sin(-1)|2em|border:ridge red;}}
|-
|}
Example Rendering
Only value 272
Negative value -72
Math expression exp(1)*1e2
Value and ordinary unit 272 km/h
Value and convert unit 272 km (169 mi)
Value and scale 272
Value and height 272
Value and style 272
Value with commas and scale 2,720
The full monty 18^2%