Template:Buckets/doc

create use count

This template is for illustrating structured categories. It generates a nested set structure and styles it as a css grid that renders horizontally on wider screens but on narrower screens automatically collapses into a single column list.

Usage

Buckets consist of pairs of values, a category label followed by content for that category. Multiple pairs can be included in the same template.

{{Buckets
	|Fish
	|Salmon, Tuna, Cod
	|Whales
	|Blue whale, Orca, Dolphin
	}}

creates

Fish

Salmon, Tuna, Cod

Whales

Blue whale, Orca, Dolphin

(whitespace is for ease of reading and not functionally necessary). Buckets can be nested to show subgroups.

{{Buckets
	|Sea creatures
	|{{Buckets
		|Fish
		|Salmon, Tuna, Cod
		|Whales
		|Blue whale, Orca, Dolphin
		}}
	|Land creatures
	|Dog, cat, elephant
	}}

creates

Sea creatures

Fish

Salmon, Tuna, Cod

Whales

Blue whale, Orca, Dolphin

Land creatures

Dog, cat, elephant

It is possible to use wikicode and other templates within a Buckets content, e.g. {{hlist}}.

It is also possible to manually adjust styles for labels using |stylen=, where n corresponds to the number of the label or content box you want to modify.

{{Buckets
	|Sea creatures
	|{{Buckets
		|style1=background-color:seagreen;
		|Fish
		|style2=background-color:cornflowerblue;
		|Salmon, Tuna, Cod
		|Whales
		|Blue whale, Orca, Dolphin
		}}
	|style3=text-decoration:underline;|Land creatures
	|Dog, cat, elephant
	}}

Sea creatures

Fish

Salmon, Tuna, Cod

Whales

Blue whale, Orca, Dolphin

Land creatures

Dog, cat, elephant

On narrow screens, the horizontal structure automatically collapses into a vertical structure and automatic colour coding helps distinguish levels of nesting.

Limits

Conceptual

Buckets can illustrate subsets but not intersections. That is, something can be contained by its parents and grandparent categories but not shared between two different parent sets, and all of its siblings must also appear in the same set. This means it is not suitable for illustrating all real life relationships--it's just a crude approximation. That's why it's called "Buckets"!

So, to add a creature like a seal, both a land and a sea creature, to these buckets, you would either need to add it to both the land creatures and sea creatures buckets, or make a new bucket for land-and-sea creatures.

All creatures great and small

Sea creatures

Fish

Salmon, Tuna, Cod

Whales

Blue whale, Orca, Dolphin

Land creatures

Dog, cat, elephant

Indeterminate

Seal, frog, albatross

Technological

Very high levels of nesting could run into the expansion depth limit. The template is likely to be impractical before that occurs however.

Under the hood

The template builds a DOM tree like this

<div class="bucket-branch">
	<div class="bucket-label">Label</div>
	<div class="bucket-label">Corresponding content</div>
</div>

There are two types of nodes. bucket-label class divs are leaf nodes: they show their contents, either the label or the things that belong to that bucket, on the page. bucket-branch class divs are structural. They are the branch nodes which contain other branches or leaves.

The HTML for nested buckets looks like this:

<div class="bucket-branch">
	<div class="bucket-label">Category A</div>
	<div class="bucket-label">Things in category A</div>
	<div class="bucket-label">Category B</div>
	<div class="bucket-branch">
		<div class="bucket-label">Category B.1</div>
		<div class="bucket-label">Things in category B.1</div>
		<div class="bucket-label">Category B.2</div>
		<div class="bucket-label">Things in category B.2</div>
	</div>
</div>

Buckets invokes a Lua module that interprets all the parameters that are passed to the template. Excepting stylen parameters, it takes interprets pairs of parameters as label-content pairs. The module builds the DOM tree and inserts the values of the parameters (the labels or the content, the things in that category) into the right place.

The mediawiki parser expands inside-out, so it parses the innermost nested template first. There is a special check in the Lua module to see if the content of the parameter begins with a <div class="bucket-branch"> already. If so, it doesn't wrap these in a bucket-leaf class div, otherwise they would appear nested in the final page, rather than branching.

The visual styling is accomplished by CSS. bucket-branch divs are CSS grids. The grid causes the child elements (bucket-leaf divs and other bucket-branches) to sort themselves into two columns and specifies the width of those columns. Which divs are labels and which are content is accomplished by the CSS counting child elements.

The CSS also handles the dynamic behaviour relative to screen size.

The bucket-branch div of any Template:Buckets is specified in the Template itself and not generated by the Lua module. This is so that templatestyles can be included inside that div, after all the child elements are generated. This prevents the CSS counting the objects in the outermost Buckets differently to nested Buckets (templatestyles is parsed to create a <style></style> object that itself counts as one of the child elements).