close
Sayahna Sayahna
Search

Difference between revisions of "Template:Autocol/doc"


(removed parent category)
 
m (1 revision)
 
(No difference)

Latest revision as of 07:26, 22 August 2014

The table formatter Template:Autocol can auto-columnize n items into ncols=2 or more columns, with or without item numbers, on any type of web browser. The number of items, such as n=46, must be specified, but if n is set larger, then the exact count is shown by later numbered items extending beyond the actual items. Option "wrap=y" will wrap entries to separate lines when not dot-bullets. Option "num=y" will auto-number the entries, with a count number across all columns.

Usage:  {{Autocol/doc|n=8|ncols=4|wrap=y|colgap=7|aa|bb|cc|dd|ee|ff|gg|hh}}
Result: 
     
Bullets: {{autocol|n=8|ncols=4|*aa|*bb|*cc|*dd|*ee|*ff|*gg|*hh}}
Result: 
     

The default is ncols=3, but can be any number which will fit the table, such as ncols=12 for small items. Due to being separate parameters, each asterisk bullet must end with a slash, as "*aa|" or "* Words |".

In practice the template is very easy to use, with the exact count of items shown by setting higher, such as n=64, and it allows setting the inter-column spacing as colgap=9 spaces, or colgap=5 (default), or such.

Parameters

Template {Autocol/doc} allows several parameters (default: n=60) as follows:

  • ncols: the number of columns, any number (default: ncols=3)
  • n          : the total number of items, can be 1 larger (default: 60)
  • wrap=y: option to wrap the entries as 1 per line, else fill (default: off)
  • num=y: option to number the items, 1 to n (default: off)
  • colgap: the number of spaces between columns (default: 5)

When num=y, then also set wrap=y to put each entry onto a separate line.

Setting count n=64

Setting the exact count of "n" items might seem a bother, so empty items can be placed in a list to allow easier expansion. The final bar "|" always allows adding one more item (anywhere) for the same count n. To prepare for adding future items, then "empty" items can be placed at the end of the template, such as "*enditem| | | |}}" to allow 4 more items, for a given "n=" count. As items are added, anywhere in the list, then the empty items at the end are ignored, falling beyond count n. For those reasons, setting the count of items, in practice, is not actually a major problem, mostly an imagined fear. When many new items are expected, then pad the end of the list with more bars "| | | |}}" and set n a few items higher. When in doubt, a note could be inserted, at the end of the list, to "<!--Be sure to set n higher when more in list-->". In any event, if the count is too low, then the template will warn when non-empty items exceed the list (such as: "{Autocol/doc} - Found item "xx" beyond count n=32").

Column alignment tactics

To better balance the columns, then items of similar width should be placed in the same column, such as long phrases in column 1 or 2; otherwise, the long phrases would wrap on narrow windows, with a conflict for space in adjacent columns. Individual long phrases can be force-wrapped by placing a "<br>" in the middle, to narrow that column, such as "[[Very long wordy phrase|Very long<br>wordy phrase]]".

With option "wrap=y", then {Autocol} can display several columns of short words. However, for long phrases, then the bullet-style items are preferred, with a lead asterisk and end-bar (such as "* phrase |"). In fact, some editors prefer the bullet-style items for all lists, and might insist on their use in some articles. When not using {Autocol}, then long lists of words can be very tedious, because {Autocol} inserts the "<br>" break at each word and pads the spacing between items. For those reasons, most multi-column lists in articles use bullet-style items.

Examples

Auto-numbering: Option "num=y" can auto-number items in all columns, used with option "wrap=y".

Numbers: {{autocol|n=8|ncols=4|num=y|wrap=y|aa|bb|cc|dd|ee|ff|gg|hh}}
Result: 
          

Option "num=y" numbers all items, counted across all columns, but prefixing each item with "#" would number each column, separately, with "1." at the top of each column.

Blank items in short columns: In some cases, a column can be "shortened" by placing blank items at the bottom of some columns. That would allow some columns to be longer than the others. The following example shows 10 items arranged in 4 columns, where 12 items would fit.

Short columns: {{autocol|n=12|ncols=4|*aa|*bb|*cc|*dd|*ee|*ff|*gg|*hh| |*ii|*jj| }}
Result: 
          

Although the 4 columns could fit 12 items, only 10 are present, so the table is set with n=12, but blank items are placed at the end of columns 3 and 4.

Groups of bullets: When bullets must be separated into groups, then bolded names can be placed at the start of each group of bullets in the same table.

Bullet groups: {{autocol|n=15|ncols=3
|'''First set'''|*aa|*bb|*cc|*dd|*ee|*ff|
'''Second set'''|*gg|*hh|*ii|*jj|*kk|*ll|*mm}}
Result: 
          

Note each bullet must end with a bar pipe "*ff |" to avoid an extra newline. Although each group could be formatted as a separate table, in many cases, it is shorter to combine groups into one table, with the group names set in triple-apostrophe bold font. Because each bullet is indented, then the group names stand out as separators between the groups of bullets. To better align the groups, some blank items ("| |") could be added between groups, increasing the count n for each blank item.

Performance considerations

Because {Autocol} is limited to 64 items, it runs very quickly, and can format a list of 64 items within 1/8 second. The larger template, {Autocol_big} runs 2x slower, using 1/4 second. For both, the expansion depth has been kept to a minimum, as only 4 levels of the 41-level MediaWiki wp:expansion depth limit. Spacing for colgap=5, between columns, consists of &nbsp's, repeated by function {{padleft:|{{#expr:{{{colgap}}}*6}} |&nbsp;}}, which runs at 1,200 per second, so the colgap size does not affect the speed of formatting the table. For that reason, an article could have 2 full tables of {Autocol} items and use only 1/4 second.

See also