KidzSearch Encyclopedia:Advanced Convert coding

This essay, Wikipedia:Advanced Convert coding, describes some ways to improve or expand the use of the Wikipedia unit-converter, Template:Convert. Most of the tips involve setting the parameters.

Some techniques here are beyond the basics described in the Convert docpage ("{{Convert/doc}}") which explains almost all basic options of the parameters, also showing examples of each. The currently supported units are listed under {{Convert/list of units}}. Several options presented here have been discussed under Template_talk:Convert.

Most of the subtemplates used by Template:Convert, on Simple Wikipedia, have been copied from the same name on English Wikipedia.

Option disp=x to customize output separators

24-Sep-2010: Using option "disp=x" (such as "disp=x| << | >>") will insert custom text/separators around the output amount (added: September 2010). Here are some live examples:

• {convert|5|mi|km|disp=x| [ | ] } → 5 miles [ 8.0 km ]
• {convert|5|mi|km|disp=x|; } → 5 miles; 8.0 km
• {convert|88|m|ft|disp=x| {equals |} } → 88 metres {equals 289 ft}
• {convert|3|sqmi|km2|disp=x| (equals |, others likewise) } → 3 square miles (equals 7.8 km², others likewise)
• {convert|9|ft|cm|disp=x| (same as |)} → 9 feet (same as 270 cm)

Any spaces in those parameters will appear in the output. This option disp=x will allow editors to vary the wording, to avoid monotonous repetitions, and perhaps combine live conversions with other hand-coded numbers as the customized text.

More subtemplates must be created to allow the option disp=x to work in ranges or non-abbreviated units. The concept of customizing the output format has been considered for years, but the former stumbling block had been the end-round parameter "|1" which is treated here as parameter 6 when disp=x, and that allows customization to proceed. I have been studying this issue for years, so I don't foresee any major complications, for general usage of disp=x. However, more unit-subtemplates will need to be updated to pass parameters 5/6/7 so that the ending text can be specified for any unit, not just for miles, feet, or metres. Also, we might be able to replace disp=s using disp=x and reduce perhaps a few hundred other subtemplates that are not used very much, as being deprecated, in favor of using disp=x. Note that a semicolon can be specified by "disp=x|; " to separate by semicolon.

Other abbreviation options: abbr=in or abbr=out

29-Oct-09: There are options now to control the input versus the output-abbreviations (similar to linking as options lk=in or lk=out). There are now 5 settings for abbreviation:

• abbr=off, abbr=on, abbr=in, abbr=out & abbr=none.

This is the first time it has been possible to abbreviate just the input units, using abbr=in, and leave full-word form as the output: such as "xx km (xx miles)":

{{convert|16|cm|in|abbr=in}}   gives: 16 cm (6.3 inches)

{{convert|4|kg|lb|abbr=in}}       gives: 4 kg (8.8 pounds)

{{convert|6|ft|3|in|cm}}                 gives: 6 feet 3 inches (191 cm)

{{convert|6|ft|7|in|cm|abbr=in}}      gives: 6 ft 7 in (201 centimetres)

For many conversions, the default has been "abbr=out" so that the km/mi conversions have stated "xx kilometres (xx mi)". The other options (in/out) were added for completeness, to allow anything: in, out, both or none. However, the logical preference seems to be abbr=in, because for most articles where the culture is metric, then "km" would be obvious, but other readers might wonder about "mi". The use of abbr=in gives "xx km (xx miles)" and also avoids the end-spelling of -metre/meter which has been irritating to some readers. Anyway, this is the first time for users to have a choice of abbreviating just the input unit-names.

Rounding the output amounts

When invoking {{convert}}, the end-parameter can be a number to designate the level of rounding, such as "0" for whole numbers, "1" for 1 decimal, "2" for 2 decimals, "-2" for whole hundreds, etc. For example:

• {{convert|741|ft |0}}   gives: 741 feet (226 m)
• {{convert|741|ft |1}}   gives: 741 feet (225.9 m)
• {{convert|741|ft |2}}   gives: 741 feet (225.86 m)
• {{convert|741|ft |-2}}  gives: 741 feet (200 m)

The use of the rounding-parameter can be altered by using sigfig=3 (or similar) to control the precision of the output amounts.

Surrounding conversions to round by 5

04-Nov-2009: In some instances, a converted result should be rounded to the nearest 5 units, rather than the nearest 1 unit. For now, this can be done by using a math-expression outside a conversion. The algorithm is:  round5 = (n/5 round 0) * 5. For example, in metres-to-feet:

• Precise:  80.0 metres (262.467 ft) and 93.0 metres (305.118 ft)
• Round 80 m, {{#expr:({{convert|80|m|ft|3|disp=output number only}}/5 round 0)*5}} for: 260 ft
• Round 93 m, {{#expr:({{convert|93|m|ft|3|disp=output number only}}/5 round 0)*5}} for: 305 ft

In general, for any number rounded to the nearest 5:

• Rounding 13.11 by 5: {{#expr: (13.11/5 round 0) * 5}} gives: 15
• Rounding 19.44 by 5: {{#expr: (19.44/5 round 0) * 5}} gives: 20
• Rounding 32.48 by 5: {{#expr: (32.48/5 round 0) * 5}} gives: 30
• Rounding 32.51 by 5: {{#expr: (32.51/5 round 0) * 5}} gives: 35

Larger numbers will require removing commas by {{formatnum: 1,234|R}}:

• Round 967 m, {{#expr:({{formatnum: {{convert|967|m|ft|3|disp=output number only}}|R}}/5 round 0)*5}} for: 3175 ft

Although the need to round by 5's is rare, similar coding can be used to adjust the results in other ways.

Suppressing commas

04-Nov-2009: To suppress commas, use either option "adj=nocomma" or "abbr=comma" to abbreviate (remove) commas from the display. So, the results would be as follows:

• {{convert|2500|m|ft|adj=nocomma}}    gives: 2500 metres (8200 ft)
• {{convert|1426|C|F}}                        gives: 1,426 °C (2,599 °F)
• {{convert|1426|C|F|adj=nocomma}}   gives: 1426 °C (2599 °F)
• {{convert|3500|F|C}}                        gives: 3,500 °F (1,930 °C)
• {{convert|3500|F|C|adj=nocomma}}   gives: 3500 °F (1930 °C)

The option "adj=nocomma" can also be used when comma is the separator ("disp=comma") to simplify the results, as showing only 1 comma: 3500 °F, 1930 °C.

Customizing the results with output-only

The template {{convert}} has parameters to alter the display-format, such as abbr=on to abbreviate all units, or disp=comma to use a comma-separator. However, there might be a need for a customized display, beyond the formats offered as parameters. For maximum customization, use the options to show only the results:

• disp=output only -  display only the results with units
• disp=output number only -  display only the resulting numbers (no units)

By using those options, all the surrounding text can be customized, with any words or wikilinks, as needed. For example, use:

Single values:

• {{convert|742|ft |disp=output only}}              gives: 226 m
• {{convert|747|ft |disp=output only}}              gives: 228 m
• {{convert|742|ft |disp=output number only}}   gives: 226

Ranges:

• {{convert|742|to|747|ft |disp=or}}                   gives: 742 to 747 feet or 226 to 228 m
• {{convert|742|to|747|ft |disp=output only}}      gives: 226 to 228 m
• {{convert|28|to|31|C |F |disp=output only}}      gives: 82 to 88 °F

Then, the surrounding text can be any wording:

"a 28-to-31 °C temperature range (equivalent 82 to 88 °F) is possible"

With that customization, any extra words can be inserted, such as "equivalent" or "range" or "temperature" (etc.) to surround the result (of "82 to 88 °F").

Displaying result first by disp=flip

10-Nov-2009: The display option disp=flip can be used to flip the result as first in order:
           {{convert|36|ft|6|in |m|abbr=on|disp=flip}}      gives: 11.13 m (36 ft 6 in)
           {{convert|12|lb|8|oz |kg|abbr=on|disp=flip}}   gives: 5.7 kg (12 lb 8 oz)
           {{convert|10|m|ft|abbr=on|disp=flip|lk=on}}   gives: 33 ft (10 m)

So, the option "disp=flip" will flip and reverse the order of the output, inverting the result as first in the text and the input unit as last (in reverse order). To abbreviate as with typical unit symbols, then use abbr=in to abbreviate the input appearing as output.

Displaying unit name by disp=unit

The display type disp=unit will display just the unit name (as singular, plural or hyphenated) for an input-unit symbol:

• {{convert|1 |ft|disp=unit}}           gives: foot
• {{convert|9 |ft|disp=unit}}           gives: feet
• {{convert|7 |m3|disp=unit|abbr=on}}       gives: m³
• {{convert|7 |m3|disp=unit|abbr=off}}       gives: cubic metres
• {{convert|1 |cuyd|disp=unit|lk=on}}       gives: cubic yard
• {{convert|1 |cuyd|disp=unit|adj=on}}      gives: cubic-yard

The option disp=unit can also be used, during article writing, as a means to display a unit name or symbol for a specific unit-code when writing an article.

Template:Convert/3 for cubic or 3 amounts

06-Nov-2009: The subtemplate Template:Convert/3, for 3-amount conversions, allows any mixture of "to" or "by" or "x" or "-" or "and" (etc.) as the range-words; plus the separator can also be a semicolon, using disp=semi:

• {{convert/3 |5|by|6|by|7|m|ft}}     gives: Template:Convert/3
• {{convert/3 |5|x|6|x|7|m|ft}}        gives: Template:Convert/3
• {{convert/3 |7|to|8|to|9|km|mi|abbr=on}}    gives: Template:Convert/3
• {{convert/3 |7|to|8|to|9|km|mi|adj=on}}      gives: Template:Convert/3
• {{convert/3 |5|to|6|by|7|m|ft}}     gives: Template:Convert/3
• {{convert/3 |5|by|6|x|7|m|ft}}      gives: Template:Convert/3
• {{convert/3 |11|-|22|-|33|°C|F|disp=semi|lk=on}}     gives: Template:Convert/3

The input units (like "metre") can be abbreviated or linked, using parameters abbr=in, abbr=on, lk=on or lk=in.

Plan to reduce subtemplates

08-Nov-2009: It is becoming far more difficult to implement new options, as the number of Convert-subtemplates grows by hundreds each time. Recently, over 650 new subtemplates were added, but we should prepare to reduce those in the next few months. See essay: "en:Wikipedia:A plan to reduce Convert subtemplates". It would be easier to control commas by: comma=off, comma=in, comma=out, comma=on. Plus, some people want to round the input amount, such as round=in, round=out (current default), or round=on. Unless the current design is condensed, those new options could require modifying hundreds of subtemplates.

Category for recent Convert subtemplates

Before October 2009, the talk-page Template_talk:Convert had been the only notice of new Convert subtemplates. However, the "Category:2009 Convert unit subtemplates" is a separate category for newer subtemplates. It can be listed, to see new subtemplate names. Insert that category-link at the bottom of new templates.

Defining new conversion subtemplates

Just like with creating new article-pages, users are allowed to create new unit-conversion subtemplates. For example, someone might want to use "kilograms-per-centimetre" (kg/cm) as a variation of the typical per-metre conversion (using "kg/m"):

Template:Convert/kg/m
{{convert/{{{d}}}|{{{1}}}|{{{2|}}}|{{{3|}}}|{{{4|}}}|{{{5|}}}|{{{6|}}}|{{{7|}}}|s={{{s|}}}
| r={{{r}}}
| u=kg/m
| n=kilogram per met{{{r}}}
| h=kilogram-per-met{{{r}}}
| l=kilograms per met{{{r}}}
| t=linear density
| o=lb/yd
| b=1
| j=0-{{{j|0}}}<!--end-->}}

The new subtemplate would be named "Template:Convert/kg/cm" with the coding copied and altered from viewing the template {{Convert/kg/m}}:

Template:Convert/kg/cm
{{convert/{{{d}}}|{{{1}}}|{{{2|}}}|{{{3|}}}|{{{4|}}}|{{{5|}}}|{{{6|}}}|{{{7|}}}|s={{{s|}}}
| r={{{r}}}
| u=kg/cm
| n=kilogram per centimet{{{r}}}
| h=kilogram-per-centimet{{{r}}}
| l=kilograms per centimet{{{r}}}
| t=linear density
| o=lb/yd
| b=100
| j=0-{{{j|0}}}<!--end-->}}

Note that the new conversion factor is b=100, as the multiplier from kg/m to kg/cm, based on 1 m = 100 cm.  When editing a conversion-subtemplate, be very careful to match the exact nesting of braces (pairing the "{{{ }}}"); otherwise, the parameters might be treated as literal text and listed across the page instead (such as string of "...| t=linear density | o=lb/yd | b=100...").

The numbered parameters, {{{1}}}, {{{2}}}, {{{3}}}, {{{4}}}, {{{5}}}, {{{6}}} & {{{7}}}, are the first 7 positional parameters passed from using: {{convert|{1}|{2}|{3}|{4}|{5}|{6}|{7}|...}}.

The other parameters are:

• u = unit symbol, n = unit name, l = plural unit name (lowercase L),
• h = hyphenated name (singular, such as: mile-per-gallon)
• t = text linked (such as article "Miles per gallon" for "mpg")
• b = conversion factor relative to base units (base = 1 m)
• j = conversion-precision (putting "5" shows result as 5 digits)
• s = combined rounding for sigfig=x plus end-parameter "0" etc.
• r = end-spelling as either r=er (American) or r=re
• y = unit-code for 4-part unit names (view: {{Convert/mpgus}})

Using the new template {{Convert/kg/cm}}, the result would be:

• {{Convert|9|kg/m|kg/cm}}          gives: 9 kilograms per metre (0.090 kg/cm)
• {{Convert|4|kg/m|kg/cm}}          gives: 4 kilograms per metre (0.040 kg/cm)
• {{Convert|7.3|kg/m|kg/cm}}       gives: 7.3 kilograms per metre (0.073 kg/cm)
• {{Convert|7.4|kg/m|kg/cm|5}}    gives: 7.4 kilograms per metre (0.07400 kg/cm)

Re-converting:

• {{Convert|0.09|kg/cm|kg/m}}          gives: 0.09 kilograms per centimetre (9.0 kg/m)
• {{Convert|0.15|kg/cm|kg/m}}          gives: 0.15 kilograms per centimetre (15 kg/m)
• {{Convert|18|kg/cm|kg/m|adj=on}}   gives: 18-kilogram-per-centimetre (1,800 kg/m)

There is no limit to the number of conversion-subtemplates that can be created. Again, when editing, be very careful to match the nested-braces (pairing "{{{" and "}}}"). Each unit-conversion subtemplate is really the coding to invoke another subtemplate (typically invoking {{Convert/LoffAoffDbSoff}} for output), so that is the reason why the pairing of braces is critical.

Defining new display-subtemplates

With the option-name parts of subtemplate naming, an option value could be added to quickly connect to a particular variation subtemplate, but there would be hundreds of total variations. For example, using abbr=xyz, the related custom variations can be coded as more than 800 subtemplates named with option-name part "Axyz". However, in general, when a variation is created, only a few dozen of the possible combinations are implemented, and the remaining hundreds are omitted, as future subtemplates "under construction" to complete the particular option.

For option abbr=xyz, the 800 subtemplates would be named as follows:

• regular units with "( )": Template:Convert/LoffAxyzDbSoff, /LoffAxyzDbSon, /LonAxyzDbSoff, /LonAxyzDbSon,
  /LinAxyzDbSoff, /LinAxyzDbSon, /LoutAxyzDbSoff, /LoutAxyzDbSon, etc.
• regular units with slash "/": Template:Convert/LoffAxyzDsSoff, /LoffAxyzDsSon, /LonAxyzDsSoff, /LonAxyzDsSon,
  /LinAxyzDsSoff, /LinAxyzDsSon, /LoutAxyzDsSoff, /LoutAxyzDsSon, etc.
• regular units with "or": Template:Convert/LoffAxyzDorSoff, /LoffAxyzDorSon, /LonAxyzDorSoff, /LonAxyzDorSon,
  /LinAxyzDorSoff, /LinAxyzDorSon, /LoutAxyzDorSoff, /LoutAxyzDorSon, etc.

(...and 24 similar, with Dcomma, D/, Doutput only...)

• 2-unit groups with "( )": Template:Convert/LoffAxyzDbSoff2, /LoffAxyzDbSon2, /LonAxyzDbSoff2, /LonAxyzDbSon2,
  /LinAxyzDbSoff2, /LinAxyzDbSon2, /LoutAxyzDbSoff2, /LoutAxyzDbSon2, etc.
• 2-unit groups with slash "/": Template:Convert/LoffAxyzDsSoff2, /LoffAxyzDsSon2, /LonAxyzDsSoff2, /LonAxyzDsSon2,
  /LinAxyzDsSoff2, /LinAxyzDsSon2, /LoutAxyzDsSoff2, /LoutAxyzDsSon2, etc.
• 2-unit groups with "or": Template:Convert/LoffAxyzDorSoff2, /LoffAxyzDorSon2, /LonAxyzDorSoff2, /LonAxyzDorSon2,
  /LinAxyzDorSoff2, /LinAxyzDorSon2, /LoutAxyzDorSoff2, /LoutAxyzDorSon2, etc.

(...and 24 similar, with Dcomma, D/, Doutput only...)

• temperature units with "( )": Template:Convert/LoffAxyzDbSoffT, /LoffAxyzDbSonT, /LonAxyzDbSoffT, /LonAxyzDbSonT,
  /LinAxyzDbSoffT, /LinAxyzDbSonT, /LoutAxyzDbSoffT, /LoutAxyzDbSonT, etc.
• temperature units with slash "/": Template:Convert/LoffAxyzDsSoffT, /LoffAxyzDsSonT, /LonAxyzDsSoffT, /LonAxyzDsSonT,
  /LinAxyzDsSoffT, /LinAxyzDsSonT, /LoutAxyzDsSoffT, /LoutAxyzDsSonT, etc.
• temperature units with "or": Template:Convert/LoffAxyzDorSoffT, /LoffAxyzDorSonT, /LonAxyzDorSoffT, /LonAxyzDorSonT,
  /LinAxyzDorSoffT, /LinAxyzDorSonT, /LoutAxyzDorSoffT, /LoutAxyzDorSonT, etc.

(...and 24 similar, with Dcomma, D/, Doutput only...)

• regular unit-ranges with "( )": Template:Convert/Dual/LoffAxyzDbSoff, /Dual/LoffAxyzDbSon, /Dual/LonAxyzDbSoff,
  /Dual/LonAxyzDbSon, /Dual/LinAxyzDbSoff, /Dual/LinAxyzDbSon,
  /Dual/LoutAxyzDbSoff, /Dual/LoutAxyzDbSon.

(...and 40 similar, with Ds, Dor, Dcomma, D/, Doutput only...)

• 2-unit-ranges with "( )": Template:Convert/Dual/LoffAxyzDbSoff2, /Dual/LoffAxyzDbSon2, /Dual/LonAxyzDbSoff2,
  /Dual/LonAxyzDbSon2, /Dual/LinAxyzDbSoff2, /Dual/LinAxyzDbSon2,
  /Dual/LoutAxyzDbSoff2, /Dual/LoutAxyzDbSon2.

(...and 40 similar, with Ds, Dor, Dcomma, D/, Doutput only...)

• temperature unit-ranges with "( )": Template:Convert/Dual/LoffAxyzDbSoffT, /Dual/LoffAxyzDbSonT, /Dual/LonAxyzDbSoffT,
  /Dual/LonAxyzDbSonT, /Dual/LinAxyzDbSoffT, /Dual/LinAxyzDbSonT,
  /Dual/LoutAxyzDbSoffT, /Dual/LoutAxyzDbSonT.

(...and 40 similar, with Ds, Dor, Dcomma, D/, Doutput only...)

• (...and 100 for 2-unit results, with Ds, Dor, Dcomma, D/,...)

• (...and 100 for imperial-units, with Ds, Dor, Dcomma, D/,...)

• (...and 100 for USre-units, with Ds, Dor, Dcomma, D/,...)

• (...and 100 for USer-units, with Ds, Dor, Dcomma, D/,...)

• (...and 100 for engineering-units, with Ds, Dor, Dcomma, D/,...)

Due to the vast number of subtemplates, many of the possible combinations are omitted, which could appear as missing templates, someday, when those combinations are selected by a user on a rare occasion.

Related pages

WP:Advanced article editing WP:Advanced footnote formatting WP:Advanced table formatting WP:Advanced text formatting WP:Advanced template coding

WP:Thinking outside the infobox WP:Pruning article revisions WP:Alert WP:Authors of Wikipedia WP:Avoiding difficult users

Notes

                                         [ This essay is a draft to be expanded later. ]