Admin: 1 revision

2014-03-27T06:48:54Z

1 revision

Mors Principium Est at 07:17, 27 May 2013

2013-05-27T07:17:39Z

New page

{{Documentation subpage}}
{{TOCright}}
==Function==
===Purpose===
{{[[Template:Colevel|colevel]]}} is a set of templates which allow a list of single items or a list of coupled items to be displayed in one or more columns and be automatically column depth balanced.

The templates are not designed to be called directly from an article, but are designed to be incorporated into other templates which are presenting tables of many items.

There are six entry point templates:
*{{[[Template:colevel/item set|colevel/item set]]}}
:Item set produces a row for a table consisting of one or more "columns" of items or coupled items. It must always be enclosed within a table declaration.
:This is used or linked to by [[Special:WhatLinksHere/Template:Colevel/item set|pages]]
*{{[[Template:colevel/headings|colevel/headings]]}}
:Headings places a set of headings above the "columns" produced by item set. It must always be enclosed within a table declaration, the same table as item set.
:This is used or linked to by [[Special:WhatLinksHere/Template:Colevel/headings|pages]]
*{{[[Template:colevel/find first|colevel/find first]]}}
:Find first returns the positional number of the first instantiated item in an optionally populated list of items. If there are no items it returns 51.
:This is used or linked to by [[Special:WhatLinksHere/Template:Colevel/find first|pages]]
*{{[[Template:colevel/find last|colevel/find last]]}}
:Find last returns the positional number of the last set item in an optionally populated list of items. If there are no items it returns 0.
:This is used or linked to by [[Special:WhatLinksHere/Template:Colevel/find last|pages]]
*{{[[Template:colevel/count params|colevel/count params]]}}
:Count params returns the number of the set parameters in an optionally populated list of items.
:This is used or linked to by [[Special:WhatLinksHere/Template:Colevel/count params|pages]]
*{{[[Template:colevel/count items|colevel/count items]]}}
:Count items returns the number of set items in an optionally populated list of items, between and including a start item and an end item.
:This is used or linked to by [[Special:WhatLinksHere/Template:Colevel/count items|pages]]

See templates {{[[Template:Event list|event list]]}}, {{[[Template:Overlay|overlay]]}}, and {{[[Template:Balanced columns list|Balanced columns list]]}} for typical applications.

===Rationale===
Often articles have tables of many items spread over multiple columns, and an editor has spent a non trivial amount of time getting the columns balanced and the table looking good.

One more item or several items are then required to be inserted in to the table, requiring the editing of the whole table to move items around and across and down columns. Or, the number of columns in the table needs to be changed to either allow it to better fit into the article or as more and more values are added. Not all editors are as good at editing tables as others and mistakes are made, or the potential content editor is put off altogether, or editors avoid constructing the table in the first place because it will be difficult to maintain.

These templates allow other templates which generate tables to be constructed to allow the table to be kept in the article as a simple list of items, allowing editors to be concerned only with content and article layout, and not with either table syntax or laborious table reconfiguration as the article grows.

===Limitations===
====Number of items====
The maximum number of single items or number of coupled items is 50, that is for coupled items a total of 100 items.

====Column balancing====
Column balancing does not allow for inconsistent text wrap of items, and text wrap can disturb column depth balancing.

If there is an equivalent number of text wrap new lines in each column then the columns will remain balanced.

====Missing items====
Items missing from within the list of items are treated as items and a blank position will be displayed in the column where the missing item would otherwise appear.

==Usage==
The main entry point template is <nowiki>{{</nowiki>'''colevel/item set'''<nowiki>}}</nowiki>

===Item set===
====Skeleton====
<pre>
{{colevel/item set
|alpha1 = |beta1 =
(...up to 50...)
|firstitem =
|lastitem =
|columns =
|alphawidth =
}}
</pre>
Item set uses named parameters:
*alpha1, optional, text for an item, or for the first item of two coupled items, in a list of up to 50 items, optionally linked text
*beta1, optional, text for the second item of two coupled items, optionally linked text
*firstitem, mandatory, the positional number of the first item to be displayed from the list, number from 1 to 50
*lastitem, mandatory, the positional number of the last item to be displayed from the list, number from 1 to 50
*columns, mandatory, the number of columns to be displayed, number from 1
*alphawidth, mandatory, the percentage width for the first item of two coupled items. If 100 then only the first item in the couple is displayed. If 0 then only the second item in the couple is displayed, number from 0 to 100

===Headings===
====Skeleton====
<pre>
{{colevel/headings
|alphaheading =
|betaheading =
|columns =
|alphawidth =
}}
</pre>
Headings uses named parameters:
*alphaheading, optional, text for the heading above the first item of two coupled items, optionally linked text
*betaheading, optional, text for the heading above the second item of two coupled items, optionally linked text
*columns, mandatory, the number of columns to be displayed, number from 1
*alphawidth, mandatory, the percentage width for the alpha heading. If 100 then only the alphaheadin is displayed. If 0 then only the betaheading is displayed, number from 0 to 100.

===Find first===
====Skeleton====
<pre>
{{colevel/find first
|item1
(...up to 50...)
}}
</pre>
Find first uses positional parameters:
*1, optional, an item in a list, up to 50, any content

===Find last===
====Skeleton====
<pre>
{{colevel/find last
|item1
(...up to 50...)
}}
</pre>
Find last uses positional parameters:
*1, optional, an item in a list, up to 50, any content

===Count params===
====Skeleton====
<pre>
{{colevel/count params
|item1
(...up to 50...)
}}
</pre>
Count params uses positional parameters:
*1, optional, an item in a list, up to 50, any content

===Count items===
====Skeleton====
<pre>
{{colevel/count items
|item1
(...up to 50...)
|firstitem =
|lastitem =
}}
</pre>
Count item uses positional parameters and named parameters:
*1, optional, an item in a list, up to 50, any content
*firstitem, mandatory, items with a position before firstitem are ignored, number
*lastitem, mandatory, items with a position after lastitem are ignored, number

==Examples==
===Headings===
====Headings for four columns====
<pre>
{|
{{colevel/headings
|alphaheading = [[Letter (alphabet)|Letter]]s
|betaheading = [[Word]]s
|columns = 4
|alphawidth = 25
}}
|}
</pre>
{|
{{colevel/headings
|alphaheading = [[Letter (alphabet)|Letter]]s
|betaheading = [[Word]]s
|columns = 4
|alphawidth = 25
}}
|}
===Item set===
====Ten items in four columns====
<pre>
{|
{{colevel/item set
|alpha1 = A |beta1 = One. Numero uno prima.
|alpha2 = BB |beta2 = Two. Seconda mondo.
|alpha3 = CC C |beta3 = Three. Triplet gamma.
|alpha4 = D DDD |beta4 = Four. Quinella equina.
|alpha5 = EE EE E |beta5 = Five. Cinque torri.
|alpha6 = FFF FFF |beta6 = Six. Sex before zeben.
|alpha7 = GG GG GG G |beta7 = Seven. Heptagonaloid.
|alpha8 = HHHH HHHH |beta8 = Eight. Octapussy bond.
|alpha9 = III III III |beta9 = Nine. El nina deci.
|alpha10 = J JJ JJJ JJJJ |beta10 = Ten. Decimal dextra.
|firstitem = 1
|lastitem = 10
|columns = 4
|alphawidth = 25
}}
|}
</pre>
{|
{{colevel/item set
|alpha1 = A |beta1 = One. Numero uno prima.
|alpha2 = BB |beta2 = Two. Seconda mondo.
|alpha3 = CC C |beta3 = Three. Triplet gamma.
|alpha4 = D DDD |beta4 = Four. Quinella equina.
|alpha5 = EE EE E |beta5 = Five. Cinque torri.
|alpha6 = FFF FFF |beta6 = Six. Sex before zeben.
|alpha7 = GG GG GG G |beta7 = Seven. Heptagonaloid.
|alpha8 = HHHH HHHH |beta8 = Eight. Octapussy bond.
|alpha9 = III III III |beta9 = Nine. El nina deci.
|alpha10 = J JJ JJJ JJJJ |beta10 = Ten. Decimal dextra.
|firstitem = 1
|lastitem = 10
|columns = 4
|alphawidth = 25
}}
|}

====Combined headings and item set====
{|
{{colevel/headings
|alphaheading = [[Letter (alphabet)|Letter]]s
|betaheading = [[Word]]s
|columns = 4
|alphawidth = 25
}}
{{colevel/item set
|alpha1 = A |beta1 = One. Numero uno prima.
|alpha2 = BB |beta2 = Two. Seconda mondo.
|alpha3 = CC C |beta3 = Three. Triplet gamma.
|alpha4 = D DDD |beta4 = Four. Quinella equina.
|alpha5 = EE EE E |beta5 = Five. Cinque torri.
|alpha6 = FFF FFF |beta6 = Six. Sex before zeben.
|alpha7 = GG GG GG G |beta7 = Seven. Heptagonaloid.
|alpha8 = HHHH HHHH |beta8 = Eight. Octapussy bond.
|alpha9 = III III III |beta9 = Nine. El nina deci.
|alpha10 = J JJ JJJ JJJJ |beta10 = Ten. Decimal dextra.
|firstitem = 1
|lastitem = 10
|columns = 4
|alphawidth = 25
}}
|}

====Nine items in six columns====
<pre>
{|
{{colevel/item set
|alpha1 = A |beta1 = One. Numero uno prima.
|alpha2 = B |beta2 = Two. Seconda mondo.
|alpha3 = C |beta3 = Three. Triplet gamma.
|alpha4 = D |beta4 = Four. Quinella equina.
|alpha5 = E |beta5 = Five. Cinque torri.
|alpha6 = F |beta6 = Six. Sex before zeben.
|alpha7 = G |beta7 = Seven. Heptagonaloid.
|alpha8 = H |beta8 = Eight. Octapussy bond.
|alpha9 = I |beta9 = Nine. El nina deci.
|alpha10 = J |beta10 = Ten. Decimal dextra.
|firstitem = 1
|lastitem = 9
|columns = 6
|alphawidth = 15
}}
|}
</pre>
{|
{{colevel/item set
|alpha1 = A |beta1 = One. Numero uno prima.
|alpha2 = B |beta2 = Two. Seconda mondo.
|alpha3 = C |beta3 = Three. Triplet gamma.
|alpha4 = D |beta4 = Four. Quinella equina.
|alpha5 = E |beta5 = Five. Cinque torri.
|alpha6 = F |beta6 = Six. Sex before zeben.
|alpha7 = G |beta7 = Seven. Heptagonaloid.
|alpha8 = H |beta8 = Eight. Octapussy bond.
|alpha9 = I |beta9 = Nine. El nina deci.
|alpha10 = J |beta10 = Ten. Decimal dextra.
|firstitem = 1
|lastitem = 9
|columns = 6
|alphawidth = 15
}}
|}

====Seven items in three columns====
<pre>
{|
{{colevel/item set
|alpha1 = A A A |beta1 = One. Numero uno prima.
|alpha2 = B B B |beta2 = Two. Seconda mondo.
|alpha3 = C C C |beta3 = Three. Triplet gamma.
|alpha4 = D D D |beta4 = Four. Quinella equina.
|alpha5 = E E E |beta5 = Five. Cinque torri.
|alpha6 = F F F |beta6 = Six. Sex before zeben.
|alpha7 = G G G |beta7 = Seven. Heptagonaloid.
|alpha8 = H H H |beta8 = Eight. Octapussy bond.
|alpha9 = I I I |beta9 = Nine. El nina deci.
|alpha10 = J J J |beta10 = Ten. Decimal dextra.
|firstitem = 2
|lastitem = 8
|columns = 3
|alphawidth = 5
}}
|}
</pre>
{|
{{colevel/item set
|alpha1 = A A A |beta1 = One. Numero uno prima.
|alpha2 = B B B |beta2 = Two. Seconda mondo.
|alpha3 = C C C |beta3 = Three. Triplet gamma.
|alpha4 = D D D |beta4 = Four. Quinella equina.
|alpha5 = E E E |beta5 = Five. Cinque torri.
|alpha6 = F F F |beta6 = Six. Sex before zeben.
|alpha7 = G G G |beta7 = Seven. Heptagonaloid.
|alpha8 = H H H |beta8 = Eight. Octapussy bond.
|alpha9 = I I I |beta9 = Nine. El nina deci.
|alpha10 = J J J |beta10 = Ten. Decimal dextra.
|firstitem = 2
|lastitem = 8
|columns = 3
|alphawidth = 5
}}
|}
====Full item set test - 50 items in 6 columns====
{|
{{colevel/item set
|firstitem = 1
|lastitem = 50
|columns = 6
|alphawidth = 20
|alpha1 = 1 |beta1 = One
|alpha2 = 2 |beta2 = Two
|alpha3 = 3 |beta3 = Three
|alpha4 = 4 |beta4 = Four
|alpha5 = 5 |beta5 = Five
|alpha6 = 6 |beta6 = Six
|alpha7 = 7 |beta7 = Seven
|alpha8 = 8 |beta8 = Eight
|alpha9 = 9 |beta9 = Nine
|alpha10 = 10 |beta10 = 10
|alpha11 = 11 |beta11 = 11
|alpha12 = 12 |beta12 = 12
|alpha13 = 13 |beta13 = 13
|alpha14 = 14 |beta14 = 14
|alpha15 = 15 |beta15 = 15
|alpha16 = 16 |beta16 = 16
|alpha17 = 17 |beta17 = 17
|alpha18 = 18 |beta18 = 18
|alpha19 = 19 |beta19 = 19
|alpha20 = 20 |beta20 = 20
|alpha21 = 21 |beta21 = 21
|alpha22 = 22 |beta22 = 22
|alpha23 = 23 |beta23 = 23
|alpha24 = 24 |beta24 = 24
|alpha25 = 25 |beta25 = 25
|alpha26 = 26 |beta26 = 26
|alpha27 = 27 |beta27 = 27
|alpha28 = 28 |beta28 = 28
|alpha29 = 29 |beta29 = 29
|alpha30 = 30 |beta30 = 30
|alpha31 = 31 |beta31 = 31
|alpha32 = 32 |beta32 = 32
|alpha33 = 33 |beta33 = 33
|alpha34 = 34 |beta34 = 34
|alpha35 = 35 |beta35 = 35
|alpha36 = 36 |beta36 = 36
|alpha37 = 37 |beta37 = 37
|alpha38 = 38 |beta38 = 38
|alpha39 = 39 |beta39 = 39
|alpha40 = 40 |beta40 = 40
|alpha41 = 41 |beta41 = 41
|alpha42 = 42 |beta42 = 42
|alpha43 = 43 |beta43 = 43
|alpha44 = 44 |beta44 = 44
|alpha45 = 45 |beta45 = 45
|alpha46 = 46 |beta46 = 46
|alpha47 = 47 |beta47 = 47
|alpha48 = 48 |beta48 = 48
|alpha49 = 49 |beta49 = 49
|alpha50 = 50 |beta50 = 50
}}
|}

===Find first===

====Full list====
<pre>
{{colevel/find first |A|BB|CCC|DDDD|E E E E E|f f f f|g g g|h h|i|JjJjJjJj}}
</pre>
First item is: {{colevel/find first |A|BB|CCC|DDDD|E E E E E|f f f f|g g g|h h|i|JjJjJjJj}}

====List with gaps====
<pre>
{{colevel/find first ||BB|CCC|DDDD||f f f f|g g g|h h|i|}}
</pre>
First item is: {{colevel/find first ||BB|CCC|DDDD||f f f f|g g g|h h|i|}}

====Empty list====
<pre>
{{colevel/find first ||||||||||}}
</pre>
First item is: {{colevel/find first ||||||||||}}

===Find last===

====Full list====
<pre>
{{colevel/find last |A|BB|CCC|DDDD|E E E E E|f f f f|g g g|h h|i|JjJjJjJj}}
</pre>
Last item is: {{colevel/find last |A|BB|CCC|DDDD|E E E E E|f f f f|g g g|h h|i|JjJjJjJj}}

====List with gaps====
<pre>
{{colevel/find last ||BB|CCC|DDDD||f f f f|g g g|h h|i|}}
</pre>
Last item is: {{colevel/find last ||BB|CCC|DDDD||f f f f|g g g|h h|i|}}

====Empty list====
<pre>
{{colevel/find last ||||||||||}}
</pre>
Last item is: {{colevel/find last ||||||||||}}

===Count items===

====Full list====
<pre>
{{colevel/count items |firstitem = 3|lastitem = 7|A|BB|CCC|DDDD|E E E E E|f f f f|g g g|h h|i|JjJjJjJj}}
</pre>
Item count is: {{colevel/count items |firstitem = 3|lastitem = 7|A|BB|CCC|DDDD|E E E E E|f f f f|g g g|h h|i|JjJjJjJj}}

====List with gaps====
<pre>
{{colevel/count items |firstitem = 3|lastitem = 7||BB|CCC|DDDD||f f f f|g g g|h h|i|}}
</pre>
Item count is: {{colevel/count items |firstitem = 3|lastitem = 7||BB|CCC|DDDD||f f f f|g g g|h h|i|}}

====Empty list====
<pre>
{{colevel/count items |firstitem = 3|lastitem = 7 ||||||||||}}
</pre>
Item count is: {{colevel/count items |firstitem = 3|lastitem = 7||||||||||}}

===Count parameters===

====Full list====
<pre>
{{colevel/count params |A|BB|CCC|DDDD|E E E E E|f f f f|g g g|h h|i|JjJjJjJj}}
</pre>
Paameter count is: {{colevel/count params |firstitem = 3|lastitem = 7|A|BB|CCC|DDDD|E E E E E|f f f f|g g g|h h|i|JjJjJjJj}}

====List with gaps====
<pre>
{{colevel/count params ||BB|CCC|DDDD||f f f f|g g g|h h|i|}}
</pre>
Parameter count is: {{colevel/count params ||BB|CCC|DDDD||f f f f|g g g|h h|i|}}

====Empty list====
<pre>
{{colevel/count params ||||||||||}}
</pre>
Parameter count is: {{colevel/count params ||||||||||}}

==Notes for template editors==
A "column" in the row produced by the template <nowiki>{{</nowiki>'''colevel/item set'''<nowiki>}}</nowiki> is actually a group of items or coupled items with each item placed on a new line.

===Algorithm===
The algorithms for this set of templates are:

====Item set====
The main challenge to be overcome to achieve depth blanced columns is that HTML tables and hence Wiki tables are "row major", that is rows are defined, not columns; the table is constructed row by row. Cells in rows are then aligned to make cells look like they are in columns.

This alogorithm emulates a rudimentrary "column major" table column by column and balances the depth of the columns so that no column is more than one item shorter than any other column, that is when there is a short fall of more than one item, instead of the last column being shorter than all other columns, the shortfall is evened out over multiple columns.

A "column" is a cell in a row with items separated by line breaks to emulate a column.
<pre>
numberofitems := lastitem - firstitem + 1
rows := 1 + (numberofitems - 1 ) intdiv columns
fullcolumns := if numberofitems mod columns = 0
then columns
else numberofitems mod columns
itemsinfullcolumns := fullcolumns x rows
start a row of columns
for item := firstitem to lastitem
eachitem := item - firstitem + 1
if eachitem <= itemsinfullcolumns
then if rows == 1
then start column
display list(item)
else itemmodrows := eachitem mod rows
if itemmodrows == 1
then start column
display list(item)
continue column
else display list(item)
if itemmodrows != 0
then continue column
else if (rows - 1) == 1
then start column
display list(item)
else itemmodrows := (eachitem - itemsinfullcolumns) mod (rows - 1)
if itemmodrows == 1
then start column
display list(item)
continue column
else display list(item)
if itemmodrows != 0
then continue column
</pre>
=====Other templates within colevel=====
'''{{[[Template:Colevel/all items|colevel/all items]]}}'''

'''{{[[Template:Colevel/each item|colevel/each item]]}}'''

'''{{[[Template:Colevel/process item|colevel/process item]]}}:'''
<pre>
if rows == 1
then start column
display item
else if itemmodrows == 1
then start column
display item
continue column
else display item
if itemmodrows != 0
then continue column
</pre>
'''{{[[Template:Colevel/start column|colevel/start column]]}}'''

'''{{[[Template:Colevel/display item|colevel/display item]]}}'''

====Find first====
<pre>
item := 1
while item <= maxitem and list(item) is empty
item := item + 1
firstitem := item
</pre>

====Find last====
<pre>
lastitem := maxitem + 1 - firstitem( reverse( list ) )
</pre>

===Structure===
Two key factors have influenced the way the algorithms have been structured into templates:
#There is no looping or recursion available. This has required a loop to be simulated by expressing each iteration of the loop as a separate but incremented instantantion of the loop control and content.
#To reduce server load a bit, calculated values which are required multiple times within a template (module) (and some module as are called for evey item) and would otherwise be calculated there once and stored as a working variable, are calculated once by a template calling the template and passed as a parameter.



===To increase number of items===
The current maximum number of items is 50.

To increase the maximum number of items from 50 to MaxItem the following need to be done:
*Template:Colevel/item set
:Update the last item check from 51 to MaxItem + 1.
:Add parameter passing from 51 to MaxItem.
*Template:Colevel/all items
:Add loop instantiations for each value from 51 to MaxItem.
*Template:Colevel/find first
:Add loop instantiations for each value from 51 to MaxItem.
:Update 51 to MaxItem + 1.
*Template:Colevel/find last
:Update 51 to Maxitem + 1.
:Add parameter passing from 51 to MaxItem.
*Update this documentation wherever 50 or 51 appears to be MaxItem and MaxItem + 1 respectively.

While '''count items''' and '''count parameters''' are not currently used by '''item set''', they should also be updated if MaxItem is updated:
*Template:Colevel/count parameters
:Add loop instantiations for each value from 51 to MaxItem.
*Template:Colevel/count items
:Add loop instantiations for each value from 51 to MaxItem.
<includeonly>

[[Category:Wikipedia list formatting templates]]
</includeonly>

← Older revision	Revision as of 06:48, 27 March 2014
(No difference)

Template:Colevel/doc - Revision history

Admin: 1 revision

Mors Principium Est at 07:17, 27 May 2013