View source for Template:Div col/doc

{{Documentation subpage}}
<!-----------------------------------------------------------------------------
  PLEASE ADD CATEGORIES WHERE INDICATED AT THE BOTTOM OF THIS PAGE
 ------------------------------------------------------------------------------>
{{Ombox|type=notice|text=Columns are not supported by some older browsers, most notably Internet Explorer 9 and earlier and Opera 11.0 and earlier.}}
{{Tl|Div col}} formats a list into columns that wrap properly and in a manner compatible with mobile devices and others with small screens. By default, it creates columns that are [[wikipedia:Em (typography)|30em]] wide.

== Purpose ==
This template enhances utilization of horizontal viewport space by programatically dividing it into equal parts and redistributing content along that axis instead of vertically. In practice this means that it is not necessary to determine the number of columns to use by trial and error and after making that determination then manually allocating equal portions of the content into that many groups. Instead, content can grow organically in aggregate and the underlying HTML functionality behind the use of lists is leveraged to organize it cleanly to suit the viewer's display and minimize the need for more vertical scrolling. To accomplish this, the content is wrapped in a block-style container which has the CSS3 property <code>column-width</code> defined (see [https://www.w3.org/TR/css-multicol-1/ W3C: CSS Multi-column Layout Module Level 1] for precise implementation details).

== Usage ==
The content to be reorganized horizontally is either defined explicitly, by supplying it within this template to the {{Para|content}} parameter (which restricts what content is allowed; e.g., wiki markup such as the pipe/vertical bar character ({{!}}) must somehow be escaped), or left in-place on the page and then terminated by the presence of the {{Tl|Div col end}} template.
* This template family also offers parameters to:
** Display the content using a smaller font ({{Para|small|yes}})
** Place vertical lines between the columns ({{Para|rules}})
** Declare other custom styles regarding the content or the columns themselves ({{Para|style}})

=== Parameters ===
There are six parameters for this template, and the order in which they are defined has no impact on the output it produces.

; {{Para|content}} : The content to divide into columns.
; {{Para|colwidth}} : Specifies the minimum width of the columns so that the number of columns is automatically based on screen width (that is, more columns will be shown on wider displays) and must be specified as a numeric value in a valid [[wikipedia:CSS#Length units|CSS unit of measure]]. For instance, the [[wikipedia:Em (typography)|em]] (about the width of the capital "M" of the typeface in use) is commonly used, e.g. {{Para|colwidth|20em}}. If undefined, the template uses a default of 30em.
; {{Para|rules}} : Adds vertical lines ("rules") between the columns when set to <code>yes</code> or a valid value for the CSS [https://www.w3.org/TR/css-multicol-1/#cr <code>column-rule</code>] shorthand property in the form of '<var>width style color</var>', though the width and color elements are optional (e.g. <code>medium double black</code>). The default style set by {{Para|rules|yes}} is defined as <code>1px solid #aaa</code>.
; {{Para|gap}} : Specifies the space between the content of adjacent columns and must be specified as a quantity of a valid CSS unit, e.g. {{Para|gap|2em}}. The default spacing applied by most modern web browsers is 1em.
; {{Para|small|<var>yes</var>}} : Sets the content to be shown using a typeface 10% smaller than normal.
; {{Para|style}} : Any valid custom [[wikipedia:CSS|CSS]] properties to apply to the container block, influencing the content, columns or container itself.

== Examples ==
Each example will first present the wikitext used to generate the example and its parsed output directly below, <span style="background-color: Moccasin; border: thin outset Goldenrod; padding: 1px 4px;">highlighted thusly</span>. Example list items courtesy of American singer-songwriter Jackson Browne's inimitable masterpiece ''Late for the Sky'', from the 1972 album of the same name.

=== Using rules &equals; yes ===
<syntaxhighlight lang="text" style="font-size: 0.75rem; width: 30vw;">
{{Div col|rules=yes}}
* All the words had all been spoken
* And somehow the feeling still wasn't right
* And still we continued on through the night
* Tracing our steps from the beginning
* Until they vanished into the air
* Trying to understand how our lives had led us there
* Looking hard into your eyes
* There was nobody I'd ever known
* Such an empty surprise to feel so alone
{{Div col end}}
</syntaxhighlight>
{{Div col|rules=yes|style=background-color: Moccasin; border: thin outset Goldenrod; padding: 0.5em;|content=<ul style="margin: 0 0 0 1.6em;">
<li>All the words had all been spoken</li>
<li>And somehow the feeling still wasn't right</li>
<li>And still we continued on through the night</li>
<li>Tracing our steps from the beginning</li>
<li>Until they vanished into the air</li>
<li>Trying to understand how our lives had led us there</li>
<li>Looking hard into your eyes</li>
<li>There was nobody I'd ever known</li>
<li>Such an empty surprise to feel so alone</li>
</ul>
}}

=== Using content parameter ===
<syntaxhighlight lang="text" style="font-size: 0.75rem; width: 30vw;">
{{Div col|content=
* All the words had all been spoken
* And somehow the feeling still wasn't right
* And still we continued on through the night
* Tracing our steps from the beginning
* Until they vanished into the air
* Trying to understand how our lives had led us there
* Looking hard into your eyes
* There was nobody I'd ever known
* Such an empty surprise to feel so alone
}}
</syntaxhighlight>
{{Div col|style=background-color: Moccasin; border: thin outset Goldenrod; padding: 0.5em;|content=<ul style="margin: 0 0 0 1.6em;">
<li>All the words had all been spoken</li>
<li>And somehow the feeling still wasn't right</li>
<li>And still we continued on through the night</li>
<li>Tracing our steps from the beginning</li>
<li>Until they vanished into the air</li>
<li>Trying to understand how our lives had led us there</li>
<li>Looking hard into your eyes</li>
<li>There was nobody I'd ever known</li>
<li>Such an empty surprise to feel so alone</li>
</ul>
}}

=== Using colwidth &equals; 15em ===
<syntaxhighlight lang="text" style="font-size: 0.75rem; width: 30vw;">
{{Div col|colwidth=15em}}
* All the words had all been spoken
* And somehow the feeling still wasn't right
* And still we continued on through the night
* Tracing our steps from the beginning
* Until they vanished into the air
* Trying to understand how our lives had led us there
* Looking hard into your eyes
* There was nobody I'd ever known
* Such an empty surprise to feel so alone
{{Div col end}}
</syntaxhighlight>
{{Div col|colwidth=15em|style=background-color: Moccasin; border: thin outset Goldenrod; padding: 0.5em;|content=<ul style="margin: 0 0 0 1.6em;">
<li>All the words had all been spoken</li>
<li>And somehow the feeling still wasn't right</li>
<li>And still we continued on through the night</li>
<li>Tracing our steps from the beginning</li>
<li>Until they vanished into the air</li>
<li>Trying to understand how our lives had led us there</li>
<li>Looking hard into your eyes</li>
<li>There was nobody I'd ever known</li>
<li>Such an empty surprise to feel so alone</li>
</ul>
}}

==== With small &equals; yes ====
<syntaxhighlight lang="text" style="font-size: 0.75rem; width: 30vw;">
{{Div col|colwidth=15em|small=yes}}
* All the words had all been spoken
* And somehow the feeling still wasn't right
* And still we continued on through the night
* Tracing our steps from the beginning
* Until they vanished into the air
* Trying to understand how our lives had led us there
* Looking hard into your eyes
* There was nobody I'd ever known
* Such an empty surprise to feel so alone
{{Div col end}}
</syntaxhighlight>
{{Div col|colwidth=15em|small=yes|style=background-color: Moccasin; border: thin outset Goldenrod; padding: 0.5em;|content=<ul style="margin: 0 0 0 1.6em;">
<li>All the words had all been spoken</li>
<li>And somehow the feeling still wasn't right</li>
<li>And still we continued on through the night</li>
<li>Tracing our steps from the beginning</li>
<li>Until they vanished into the air</li>
<li>Trying to understand how our lives had led us there</li>
<li>Looking hard into your eyes</li>
<li>There was nobody I'd ever known</li>
<li>Such an empty surprise to feel so alone</li>
</ul>
}}

==== With gap &equals; 3em ====
<syntaxhighlight lang="text" style="font-size: 0.75rem; width: 30vw;">
{{Div col|colwidth=15em|gap=3em}}
* All the words had all been spoken
* And somehow the feeling still wasn't right
* And still we continued on through the night
* Tracing our steps from the beginning
* Until they vanished into the air
* Trying to understand how our lives had led us there
* Looking hard into your eyes
* There was nobody I'd ever known
* Such an empty surprise to feel so alone
{{Div col end}}
</syntaxhighlight>
{{Div col|colwidth=15em|gap=3em|style=background-color: Moccasin; border: thin outset Goldenrod; padding: 0.5em;|content=<ul style="margin: 0 0 0 1.6em;">
<li>All the words had all been spoken</li>
<li>And somehow the feeling still wasn't right</li>
<li>And still we continued on through the night</li>
<li>Tracing our steps from the beginning</li>
<li>Until they vanished into the air</li>
<li>Trying to understand how our lives had led us there</li>
<li>Looking hard into your eyes</li>
<li>There was nobody I'd ever known</li>
<li>Such an empty surprise to feel so alone</li>
</ul>
}}

=== Other content besides lists ===
<syntaxhighlight lang="text" style="font-size: 0.75rem; width: 30vw;">
{{Div col|colwidth=20em}}
[[File:Osm-london-paper-1024x768.png|thumb]]
[[File:Josm-screen-full.png|thumb]]
[[File:Osmdbstats2.jpg|thumb]]
{{Div col end}}
</syntaxhighlight>
{{Div col|colwidth=20em}}
[[File:Osm-london-paper-1024x768.png|thumb]]
[[File:Josm-screen-full.png|thumb]]
[[File:Osmdbstats2.jpg|thumb]]
{{Div col end}}

== TemplateData ==
{{TemplateDataHeader}}
{{#switch:{{BASEPAGENAME}}
 | Div col = <templatedata>{
	"description": "Breaks a list into columns. It automatically breaks each column to an equal space, so you do not manually have to find the half way point on two columns. The list is provided by |content= or closed with {{div col end}}.",
	"paramOrder": [
		"content",
		"colwidth",
		"rules",
		"gap",
		"small",
		"style"
	],
	"params": {
		"colwidth": {
			"label": "Column width",
			"description": "Specifies the width of columns, determining their number based on screen width (i.e. more columns will be shown on wider displays)",
			"type": "line",
			"example": "25em",
			"default": "30em"
		},
		"rules": {
			"label": "Rules",
			"description": "Produces vertical lines between the columns; if set to 'yes' the default style definition of '1px solid #aaa' is used, other values are passed through to the container's column-rule CSS property as is and should take the form 'width style color'.",
			"type": "line",
			"example": "'yes' or any valid CSS value for column-rule property, such as 'medium double DarkSlateGray'"
		},
		"gap": {
			"label": "Gap width",
			"description": "Specifies the space between the content of adjacent columns; value is passed through to container's column-gap CSS property directly and thus must be a numeric value followed by a valid CSS unit of measure.",
			"type": "line",
			"example": "2em",
			"default": "1em"
		},
		"style": {
			"label": "Custom CSS",
			"description": "Specifies any custom styling.",
			"type": "line",
			"example": "border: thin solid black; font-family: serif; margin: 1em; text-align: center;"
		},
		"content": {
			"label": "Content",
			"description": "Specifies the content to divide into columns",
			"type": "content",
			"suggested": true
		},
		"small": {
			"label": "Small font",
			"description": "Use a smaller font size (90%)",
			"example": "yes",
			"type": "boolean",
			"default": "no"
		}
	}
}</templatedata>
 | Div col end = <templatedata>{
    "description": "Ends a multi-column list started by {{div col}}. It takes no parameters.",
    "params": {
    }
}</templatedata>
}}

== See also ==
* {{Tl|Div col end}}
* '''Built using'''
** {{Tl|Column-width}}
** {{Tl|Column-gap}}
** {{Tl|Column-rule}}
* '''Tracking categories'''
** [[:Category:Pages using div col with small parameter|Pages using div col with small parameter]]<includeonly>

{{#ifeq:{{SUBPAGENAME}}|sandbox||<!-- CATEGORIES BELOW THIS LINE, PLEASE: -->
[[Category:Multi-column templates]]
[[Category:Templates for formatting]]
}}</includeonly>