Editing Template:Navboxdl/doc

{{documentation subpage}}
{{lua|Module:Navboxdl}}
This is a simplified version of {{tl|Navbox}} that uses a definition list to display its data. It lacks some of the features of the full navbox template, but outputs cleaner markup that is easier to style and control. Using this template, or one of its "Navbox suite" sister templates, is highly recommended for standardization of navigational templates, and for ease of use.

== Usage ==

Please remove the parameters that are left blank.

<pre style="overflow:auto;">{{Navboxdl
|bodyclass  = 
|title      = 

|group1     = 
|list1      = 

|group2     = 
|list2      = 
 ...
|group20    = 
|list20     =  
}}</pre>

== Parameter list ==
{{Navboxdl
|state = uncollapsed
|title = {{{title}}}
|group1 = {{{group1}}}
|list1 = {{{list1}}}
|group2 = {{{group2}}}
|list2 = {{{list2}}}
|list3 = {{{list3}}} ''without {{{group3}}}''
|group4 = {{{group4}}}
|list4 = {{{list4}}}
}}
The navbox uses lowercase parameter names, as shown in the box (''at right'').  The mandatory ''title'' will create a one-line box if other parameters are omitted.
<br/>

Notice "group1" (etc.) is optional, as are sections named "above/below".
{{-}}
The basic and most common parameters are as follows (see below for the full list):

:<code>bodyclass -</code> applies an HTML <code>class</code> attribute to the entire navbox.
:<code>title -</code> text in the title bar, such as: <nowiki>[[Widget stuff]]</nowiki>.
:<code>titleclass -</code> applies an HTML <code>class</code> attribute to the title bar.
:<code>state - autocollapse, uncollapsed, collapsed</code>: the status of box expansion, where "autocollapse" hides stacked navboxes automatically.

:<code>group<sub>n</sub> - </code>the left-side text before list-n (if group-n omitted, list-n starts at left of box).
:<code>list<sub>n</sub> - </code>text listing wikilinks, often separated by middot templates, such as: [<font/>[A]]<code>{<font/>{·}}</code> [<font/>[B]]

Further details, and complex restrictions, are explained below under section ''[[#Parameter descriptions|Parameter descriptions]]''. See some alternate navbox formats under: [[#Layout of table|''Layout of table'']].

== Parameter descriptions ==
The following is a complete list of parameters for using {{tl|Navbox}}.  In most cases, the only required parameters are <code>name</code>, <code>title</code>, and <code>list1</code>, though [[Template:Navbox/doc#Child navboxes|child navboxes]] do not even require those to be set.

{{tl|Navbox}} shares numerous common parameter names as its sister templates {{tl|Navbox with columns}} and {{tl|Navbox with collapsible groups}} for consistency and ease of use.  Parameters marked with an asterisk <nowiki>*</nowiki> are common to all three master templates.

=== Setup parameters ===

:; ''state''<nowiki>*</nowiki> <span style="font-weight:normal;">[<code>autocollapse, uncollapsed, collapsed, plain, off</code>]</span>
:* Defaults to <code>autocollapse</code>. A navbox with <code>autocollapse</code> will start out collapsed if there are two or more tables on the same page that use other collapsible tables. Otherwise, the navbox will be expanded. For the technically minded, see [[MediaWiki:Common.js]].
:* If set to <code>collapsed</code>, the navbox will always start out in a collapsed state.
:* If set to <code>plain</code>, the navbox will always be expanded with no [hide] link on the right, and the title will remain centered (by using padding to offset the <small>v • d • e</small> links).
:* If set to <code>off</code>, the navbox will always be expanded with no [hide] link on the right, but no padding will be used to keep the title centered.  This is for advanced use only; the "plain" option should suffice for most applications where the [show]/[hide] button needs to be hidden.
:*If set to anything other than <code>autocollapse</code>, <code>collapsed</code>, <code>plain</code>, or <code>off</code> (such as "uncollapsed"), the navbox will always start out in an expanded state, but have the "hide" button.

: To show the box when standalone (non-included) but then auto-hide contents when in an article, put "uncollapsed" inside &lt;noinclude> tags:
:* <code>state = </code><nowiki><noinclude>uncollapsed</noinclude></nowiki>
:* That setting will force the box visible when standalone (even when followed by other boxes), displaying "[hide]" but then auto-collapse the box when stacked inside an article.

: Often times, editors will want a default initial state for a navbox, which may be overridden in an article. Here is the trick to do this:
:*In your intermediate template, create a parameter also named "state" as a pass-through like this:
:*<tt><nowiki>| state = {{{state<includeonly>|your_desired_initial_state</includeonly>}}}</nowiki></tt>
:*The <nowiki><includeonly>|</nowiki> will make the template expanded when viewing the template page by itself.

:; ''border''<nowiki>*</nowiki>
:: ''See section below on using navboxes within one another for examples and a more complete description.''  If set to <code>child</code> or <code>subgroup</code>, then the navbox can be used as a borderless child that fits snuggly in another navbox.  The border is hidden and there is no padding on the sides of the table, so it fits into the ''list'' area of its parent navbox.  If set to <code>none</code>, then the border is hidden and padding is removed, and the navbox may be used as a child of another container (do not use the <code>none</code> option inside of another navbox; similarly, only use the <code>child</code>/<code>subgroup</code> option inside of another navbox).  If set to anything else (default), then a regular navbox is displayed with a 1px border.  An alternate way to specify the border to be a subgroup style is like this (i.e. use the first unnamed parameter instead of the named ''border'' parameter):
:::<code><nowiki>{{Navbox|child</nowiki></code>
::::<code>...
:::<code><nowiki>}}</nowiki></code>

=== Cells ===
:; ''title''<nowiki>*</nowiki>
:: Text that appears centered in the top row of the table. It is usually the template's topic, i.e. a succinct description of the body contents. This should be a single line, but if a second line is needed, use <code><nowiki>{{-}}</nowiki></code> to ensure proper centering.  This parameter is technically not mandatory, but using {{tl|Navbox}} is rather pointless without a title.

:; ''group<sub>n</sub>''<nowiki>*</nowiki>
:: (i.e. ''group1'', ''group2'', etc.) If specified, text appears in a header cell displayed to the left of ''list<sub>n</sub>''. If omitted, ''list<sub>n</sub>'' uses the full width of the table.

:; ''list<sub>n</sub>''<nowiki>*</nowiki>
::  (i.e. ''list1'', ''list2'', etc.) The body of the template, usually a list of links. Format is inline, although the text can be entered on separate lines if the entire list is enclosed within <code><nowiki><div> </div></nowiki></code>.  At least one ''list'' parameter is required; each additional ''list'' is displayed in a separate row of the table.  Each ''list<sub>n</sub>'' may be preceded by a corresponding ''group<sub>n</sub>'' parameter, if provided (see below).

====Style classes====
;bodyclass : This parameter is inserted into the "class" attribute for the infobox as a whole.
;titleclass : This parameter is inserted into the "class" attribute for the infobox's title caption.

== Layout of table ==
Table generated by {{tl|Navboxdl}} '''without''' ''image'', ''above'' and ''below'' parameters (gray list background color added for illustration only):
{{Navboxdl
|state = uncollapsed
|title = {{{title}}}
|group1 = {{{group1}}}
|list1 = {{{list1}}}
|group2 = {{{group2}}}
|list2 = {{{list2}}}
|list3 = {{{list3}}} ''without {{{group3}}}''
|group4 = {{{group4}}}
|list4 = {{{list4}}}
}}

== Technical details ==

*This template uses CSS classes for most of its looks, thus it is fully skinnable.
*Internally this meta template uses HTML markup instead of wiki markup for the table code. That is the usual way we make meta templates since wiki markup has several drawbacks. For instance it makes it harder to use [[m:Help:ParserFunctions|parser functions]] and special characters in parameters.
*For more technical details see the CSS classes in [[MediaWiki:common.css]] and the collapsible table used to hide the box in [[MediaWiki:common.js]].

=== Intricacies ===

*The default margin-left and margin-right of the outer navbox table are set to "auto;".  If you wish to use navbox as a float, you need to manually set the margin-left and margin-right values, because the auto margins interfere with the float option.  For example, add the following code to use the navbox as a float:
::<code>style = width:22em;float:right;margin-left:1em;margin-right:0em;</code>

<includeonly>
<!--Categories-->
[[Category:Formatting templates| ]]
[[Category:Exclude in print|{{PAGENAME}}]]

<!--Other languages-->
</includeonly>
@@ Line 75: / Line 75: @@
 :; ''border''<nowiki>*</nowiki>
 :: ''See section below on using navboxes within one another for examples and a more complete description.''  If set to <code>child</code> or <code>subgroup</code>, then the navbox can be used as a borderless child that fits snuggly in another navbox.  The border is hidden and there is no padding on the sides of the table, so it fits into the ''list'' area of its parent navbox.  If set to <code>none</code>, then the border is hidden and padding is removed, and the navbox may be used as a child of another container (do not use the <code>none</code> option inside of another navbox; similarly, only use the <code>child</code>/<code>subgroup</code> option inside of another navbox).  If set to anything else (default), then a regular navbox is displayed with a 1px border.  An alternate way to specify the border to be a subgroup style is like this (i.e. use the first unnamed parameter instead of the named ''border'' parameter):
-:::<code><nowiki>{{Navboxdl|child</nowiki></code>
+:::<code><nowiki>{{Navbox|child</nowiki></code>
-::::<code>…</code>
+::::<code>...
 :::<code><nowiki>}}</nowiki></code>
-=== Sections ===
+=== Cells ===
 :; ''title''<nowiki>*</nowiki>
-:: Text that appears centered in the top row of the navbox. It is usually the template's topic, i.e. a succinct description of the body contents. This should be a single line, but if a second line is needed, use <code><nowiki>{{-}}</nowiki></code> to ensure proper centering.  This parameter is technically not mandatory, but using {{tl|Navboxdl}} is rather pointless without a title.
+:: Text that appears centered in the top row of the table. It is usually the template's topic, i.e. a succinct description of the body contents. This should be a single line, but if a second line is needed, use <code><nowiki>{{-}}</nowiki></code> to ensure proper centering.  This parameter is technically not mandatory, but using {{tl|Navbox}} is rather pointless without a title.
 :; ''group<sub>n</sub>''<nowiki>*</nowiki>
@@ Line 93: / Line 93: @@
 ;titleclass : This parameter is inserted into the "class" attribute for the infobox's title caption.
-===== Available classes =====
+== Layout of table ==
-{{tl|Navboxdl}} can be styled to use the colors of any of the D'ni [[:Category:Guilds|Guilds]]. Simply put the guild's name in lowercase as the <code>bodyclass</code> parameter. Examples of each available style are available below:
-{{Navboxdl |bodyclass=analysts |title=analysts |group1=Lorem ipsum |list1=Dolor sit amet}}
-{{Navboxdl |bodyclass=archivists |title=archivists |group1=Lorem ipsum |list1=Dolor sit amet}}
-{{Navboxdl |bodyclass=books |title=books |group1=Lorem ipsum |list1=Dolor sit amet}}
-{{Navboxdl |bodyclass=caterers |title=caterers |group1=Lorem ipsum |list1=Dolor sit amet}}
-{{Navboxdl |bodyclass=chemists |title=chemists |group1=Lorem ipsum |list1=Dolor sit amet}}
-{{Navboxdl |bodyclass=engineers |title=engineers |group1=Lorem ipsum |list1=Dolor sit amet}}
-{{Navboxdl |bodyclass=greeters |title=greeters |group1=Lorem ipsum |list1=Dolor sit amet}}
-{{Navboxdl |bodyclass=healers |title=healers |group1=Lorem ipsum |list1=Dolor sit amet}}
-{{Navboxdl |bodyclass=inkmakers |title=inkmakers |group1=Lorem ipsum |list1=Dolor sit amet}}
-{{Navboxdl |bodyclass=legislators |title=legislators |group1=Lorem ipsum |list1=Dolor sit amet}}
-{{Navboxdl |bodyclass=linguists |title=linguists |group1=Lorem ipsum |list1=Dolor sit amet}}
-{{Navboxdl |bodyclass=maintainers |title=maintainers |group1=Lorem ipsum |list1=Dolor sit amet}}
-{{Navboxdl |bodyclass=mechanists |title=mechanists |group1=Lorem ipsum |list1=Dolor sit amet}}
-{{Navboxdl |bodyclass=messengers |title=messengers |group1=Lorem ipsum |list1=Dolor sit amet}}
-{{Navboxdl |bodyclass=miners |title=miners |group1=Lorem ipsum |list1=Dolor sit amet}}
-{{Navboxdl |bodyclass=stonemasons |title=stonemasons |group1=Lorem ipsum |list1=Dolor sit amet}}
-{{Navboxdl |bodyclass=surveyors |title=surveyors |group1=Lorem ipsum |list1=Dolor sit amet}}
-{{Navboxdl |bodyclass=writers |title=writers |group1=Lorem ipsum |list1=Dolor sit amet}}
-By default, this navbox will use the styles defined in the "archivists" class.
-== Layout of navbox ==
 Table generated by {{tl|Navboxdl}} '''without''' ''image'', ''above'' and ''below'' parameters (gray list background color added for illustration only):
 {{Navboxdl
@@ Line 152: / Line 111: @@
 *This template uses CSS classes for most of its looks, thus it is fully skinnable.
 *Internally this meta template uses HTML markup instead of wiki markup for the table code. That is the usual way we make meta templates since wiki markup has several drawbacks. For instance it makes it harder to use [[m:Help:ParserFunctions|parser functions]] and special characters in parameters.
-*For more technical details see the CSS classes in [[MediaWiki:common.css]].
+*For more technical details see the CSS classes in [[MediaWiki:common.css]] and the collapsible table used to hide the box in [[MediaWiki:common.js]].
+=== Intricacies ===
+*The default margin-left and margin-right of the outer navbox table are set to "auto;".  If you wish to use navbox as a float, you need to manually set the margin-left and margin-right values, because the auto margins interfere with the float option.  For example, add the following code to use the navbox as a float:
+::<code>style = width:22em;float:right;margin-left:1em;margin-right:0em;</code>
 <includeonly>