Template:Dfn/doc

__EXPECTED_UNCONNECTED_PAGE__

This template applies the HTML phrase element <dfn>...</dfn> around the text given as the first parameter, the term, and, if the optional second definition parameter is present, applies a dotted underline (a common style throughout the Web for indicating a term with a definition feature) and a definition pop-up "tool tip" when cursor focus is on the term.

Without the second parameter, it does not do anything user-facing, and is just a form of meta-data that can be detected and acted upon by internal and external software (statistics-gathering bots, rich Web 2.0 applications, etc.), and can provide valuable contextual information to editors.

Usage

This template is used as a meta-template by some other templates. When used by itself, its most common purpose would be around a term italicized in an article and immediately defined there, such as a key piece of terminology introduced after the lead section. Wikipedia is not a dictionary, so this template should not be used to draw metadata attention to everyday words, and is best suited in spots where there is a short definition or clarification of jargon that is important in the context.

(Tech detail: By using an internal <span>...</span> with its own independent title attribute for tool tip fun, it sets this up in a way that does not violate the HTML 5 specification on the handing of the title attribute of <dfn>, which is the exact term defined, not its definition.)

Purpose and application

This markup indicates that the text is the defining instance of that term (word, phrase, name, etc.) on the page in which it appears. Thus, it should be used only once per term per page.

Wikipedia is not a dictionary, so this template should not be used to provide definitions for everyday words at all, and is best suited for a short definition or clarification of jargon that is important in the context but unlikely to be fully understood by all of our general readership. The template can be adapted to most directly editable cases in which the <dfn> element would be useful.

Because the definition parameter's content is not readily accessible to users of most if not all screen reader software, text-only browsers, mobile phone browsers, etc., the second parameter should never be used to provide information vital to understanding the article subject, only convenient or augmenting for those who can access it; vital information belongs in the main article prose.

This template should not be used for marking up glossary entries or links to them; see {{term}} and {{glossary link}} instead, respectively. Likewise, this template should not be used to mark up the bold-faced article subject in the lead.

This is semantic markup, not simply presentational style, and has a particular, pre-defined meaning; do not misuse this template just to get its display effects. If the content being marked up is not suitable for the <dfn> element as defined by the W3C HTML specifications, then you should not use this template.

Parameters

There are two basic parameters, the mandatory first parameter, the term, and the optional second one, the definition:

{{dfn|term}}

{{dfn|term|definition}}

If the definition parameter is supplied and the reader's browser supports the functionality, moving browser focus to the term (e.g., hovering the mouse cursor over it, or in some browsers using keyboard navigation to tab to it) will change the cursor to the "help" version (usually a question mark) and bring up the definition text in a pop-up tool tip (or some other interface, as provided by the browser in question). Without a second parameter, no such underlining and tool tip effects occur.

It is safest to explicitly number them, but this is only absolutely required if the content contains an equals sign somewhere:

{{dfn|1=term|2=definition}}

{{dfn|term|2=definition}} – this works if only the definition has a "=" in it.

{{dfn|1=term|definition}} – this fails; if parameter 1 is numbered, so must be parameter 2

If no definition is provided, the template is invisible:

{{dfn|ecdysis|moulting of the exoskeleton}}  results in:  ecdysis

{{dfn|ecdysis}}, the moulting of the exoskeleton  results in:  ecdysis, the moulting of the exoskeleton

[[Ecdysis|{{dfn|ecdysis}}]]  results in:  ecdysis

The "invisible" second and third cases won't be noticed by casual readers, but can still be detected and acted upon by internal and external software (statistics-gathering bots, rich Web 2.0 applications, etc.), and can provide valuable contextual information to editors.

The definition parameter is most commonly omitted when the text following the term provides the defining content inline in the prose, or when the term is linked to an explanation elsewhere, as shown above. A common case of this is when an article provides a bold-faced term and an explanation of it, often at the start of a paragraph or section, indicating a significant side-topic in the article, subordinate to the main article subject boldfaced in the lead.

Other optional parameters

• |title=exact, plaintext term being defined – used a) when the content in the first parameter (term) contains any wikimarkup or HTML; or b) when the term being defined is actually slightly different from (i.e. more precise than) the marked up content; the true term being defined goes in this parameter. Any double-quotation mark (") must be escaped, as ".
  Real-world example: showing imprecise term in text and its precise official name as the |title=, with escaped quotation marks: {{dfn|Mac OS X Lion|title=Mac OS X 10.7 "Lion"}}, which results in: Mac OS X Lion (hover over it to see that tooltip is different from base content)
  
• |id=an_ID – an ID (no spaces, must begin with alphabetic letter) for #linking and possibly other purposes
• |style=arbitrary:css; – CSS directives for custom-styling the instance
• |class=css_class – a CSS class or classes (separated by spaces not commas if more than one)

Problem characters

If there would be a "=" (equals sign) in the term, either a) both unnamed parameters if present must explicitly be numbered:

{{dfn|1=E=MC2|2=Mass–energy equivalence}} which results in:  E=MC²

or b) the character itself can be escaped as the HTML character entity reference code = or the {{=}} template:

{{dfn|E=MC2|Mass–energy equivalence}} which results in:  E=MC²

{{dfn|E{{=}}MC2|Mass–energy equivalence|title=E=MC²}} which results in: E=MC²

No other characters are known to be problematic in the term.

For technical reasons, the second parameter (|2=, the definition) is more "brittle". The equals sign (=) must be escaped by one of the techniques just mentioned, and the standard keyboard (straight, not curly) double-quotation mark (") must also be escaped, no matter what, as " or ". This double-quote must also be escaped the same way in the |title= parameter:

{{dfn|1=ACT UP's slogan|2="Silence = Death"}} which results in:  ACT UP's slogan

{{dfn|ACT UP's slogan|"Silence {{=}} Death"}} which results in:  ACT UP's slogan

{{dfn|ACT UP's slogan|"Silence = Death"}} which results in:  ACT UP's slogan

{{dfn|"Teenage Wasteland"{{sic}}|title="Baba O'Riley"}} which results in:  "Teenage Wasteland" [sic]

Links and markup

Linking and wikimarkup should be done outside the template when possible:

• Right: '''[[Foo|{{dfn|Foo}}]]'''
• Wrong: {{dfn|'''[[Foo]]'''}}

The term content in the first parameter can be marked up with wikimarkup or HTML, at the inline level, such as italics, superscript other text-formatting code (versus block-level elements, such as paragraphs, tables, block quotations, and so on), if absolutely necessary. If this is done, the |title= parameter must contain the un-marked-up, plaintext term. Example: The displayed text (first parameter) uses superscript markup, for accessibility reasons, while the real plaintext in the title parameter uses a Unicode character entity (doesn't count as wikimarkup) for a superscripted 2, which is actually more correct but may not display properly on older systems:

{{dfn|1=E=MC<sup>2</sup>|title=E=MC&sup2;}}

yields:

E=MC²

while this:

{{dfn|1=E=MC<sup>2</sup>|2=Mass–energy equivalence; E is energy, m is mass, and c is the speed of light in a vacuum|title=E=MC&sup2;}}

gives:

E=MC²

Note that in the first case, the mouse hover tooltip is the Unicode version of the term, as given in the |title=, while in the latter it is the definition given in the |2= parameter.

Linked version:

[[Mass–energy equivalence|{{dfn|1=E=MC2|2=Mass–energy equivalence; E is energy, m is mass, and c is the speed of light in a vacuum|title=E=MC²}}]]

gives:

E=MC²

It still has a dotted underline indicating a tooltip, but is also a bluelink. Mouse hovering shows both the tooltip and, in the status bar, the target URL, in browsers that support these features.

Link inside the {{dfn}}:

{{dfn|1=[[Mass–energy equivalence|E=MC2]]|2=Mass–energy equivalence; E is energy, m is mass, and c is the speed of light in a vacuum|title=E=MC²}}

results in:

E=MC²

This doesn't mess up the page, but the definition fails and there's no tooltip cursor, meanwhile the markup is hard for other editors to understand anyway so it is deprecated.

Links, HTML, wikimarkup, and other markup cannot be applied to content in the |2= (definition) parameter, nor in a |title= parameter, only plain text and character entity references ("&-codes", like ").

Anchors and id

Example where an {{anchor}} is added. Because 2= is missing, no text appears when the mouse hovers over the newly defined term "open set".

An {{em|{{dfn|1=open set|id=dfn-anchorname open set}}}} is defined as ...<br/><br/> This makes it an example of an [[#dfn-anchorname open set|open set]].

results in:

An open set is defined as ...

This makes it an example of an open set.

Contrast to the alternative that uses the {{visible anchor}} template:

An {{em|{{visible anchor|open set}}}} is defined as ...<br/><br/> This makes it an example of an [[#open set|open set]].

which results in:

An open set is defined as ...

This makes it an example of an open set.

Note that clicking on the "open set" link results in the text being highlighted.

See also

• {{dfni}} is a wrapper for {{dfn}} that applies italics for MOS:TECHNICAL uses
• Related to {{glossary link}}, a variant for use with stand-alone and embedded glossaries
• {{abbr}}
• {{tooltip}}
• Not to be confused with {{defn}} (but see the related glossary templates {{glossary}}, {{glossary end}} and especially {{term}}; the last of these also makes use of the dfn HTML element)

References

Template:Dfn invokes Module:Navbox using Lua.

Usage

This template can be used to make a standard navigation box. It is intended for use within another template that standardises the title and contents of the box (see Template:ShipNavbox). This template SHOULD NOT be used directly within articles, as it creates a maintenance burden to do so whenever the contents of the box have to be updated.

The purpose of this template is to standardise the attributes of all navigation boxes, for example, their colours and other CSS attributes. The template is fairly simple, and could be extended to add other features in the future. Using this template allows changes to be implemented much quicker and easier than editing each template separately.

Syntax

{{navbox
|state      = uncollapsed, collapsed, plain, autocollapse (default)
|name       = mandatory - name of the template
|style      = optional - style for the whole table
|title      = mandatory - navbox header
|gtitleN    = optional - title of N-th group of items
|styleN     = optional - style for groupN; i.e. text-align
|groupN     = mandatory - list of groups of items
|fstyle     = optional - style for footer ; i.e. text-align
|footer     = optional - navbox footer
}}

• Groups: Currently there is no technical limit to the maximum number of groups.
  • Groups of items can be added as parameters: group1, group2, group3, ... up to groupN.
• Group title: Each group has its own title parameter: gtitle1, gtitle2, gtitle3, ... up to gtitleN. Note that the default width for the first column is 15%.
• Group style: Style may also be customised to each group in: style1, style2, style3, ... up to styleN.
  • Note that neither the title nor the items have any wiki-links built into the template. As a result, users of the template are free to use wiki-links as they wish.
• Line breaks: Line-breaks (<br />) are unnecessary, as text wrapping is done automatically by the template. This also includes links and text in gtitleN and groupN.
• Bullets: Create unordered lists with lines beginning with *.
• Pipe links: Because of the nature of template syntax, it may be necessary to use Template:! ({{!}}).

States

• Autocollapse: By default, the state of a navbox is "autocollapsed". This means that if the number of navboxes in a page exceeds the maximum allocation of the collapsible navboxes, then the remaining navboxes are collapsed automatically. For more information (or to change the setting), see MediaWiki:Common.js.
  • Currently, the autocollapse allocation is 2 (see MediaWiki:Common.js). This means that if there are 3 navboxes in a page, the third and subsequent navboxes will be collapsed automatically.
• Uncollapsed: Forces the navbox to be displayed.
  • All of the navboxes in this documentation are in the uncollapsed state.
• Collapsed: The reverse of uncollapsed. Forces the navbox to be hidden instead.
  • Navboxes with a height of more than 300 pixels will also be collapsed automatically. For more information (or to change the setting), see MediaWiki:Common.js.
• Plain: Removes the "show/hide" link.

Sub-groups

• For larger navboxes, it may be necessary to include sub-groups within a particular group of items. It is also possible to collapsible navboxes within the parent navbox, see Collapsible sub-groups.
• To create sub-groups within {{navbox}}, certain parameters are to be included:
  • The parent navbox group (i.e. group2 in the example below) requires the type parameter (gtype2 = Subgroup).
  • The nested navbox (sub-group) requires the inclusion of the sub-group parameter (subgroup = yes). This enables the template to differentiate between the sub-group and the parent navbox.

{{navbox
|name    =
|title   =
|gtitle1 =
|group1  =
|gtitle2 =  
|gtype2  = Subgroup (mandatory)
|group2  = 
  {{navbox
  |subgroup = yes (mandatory)
  |gtitle1  = 
  |group1   =
  |gtitle2  = 
  |group2   = 
  }}
}}

Collapsible sub-groups

• For extremely long navboxes, it is recommended to use collapsible navboxes within the parent navbox. Further sub-groups can then be added to these collapsible navboxes.
• To create collapsible sub-groups within {{navbox}}, these parameters need to be included:
  • The parent navbox is almost always uncollapsed (state=uncollapsed).
  • The parent navbox group (i.e. group1 in the example below) requires the type parameter (gtype1 = Subgroup).
  • The nested collapsible navbox requires the inclusion of the collapsible parameter (collapsible = yes). This enables the template to differentiate between the collapsible navbox and the parent navbox.
  • The nested collapsible navbox is forcefully collapsed (state=collapsed).

{{navbox
|state  = uncollapsed
|name   = 
|gtype1 = Subgroup
|group1 = 
  {{navbox
  |collapsible = yes
  |state   = collapsed
  |title   = 
  |gtitle1 = 
  |group1  = 
  |gtitle2 = 
  |group2  = 
  }}
}}

Use of images

• The use of images in navboxes is permitted, but please resize the images to keep them small. Inventory-sized images (25-30 pixels) are recommended.
• Please use {{t|plink}} to create links with images. Use {{t|plink}} for any case where text is not desired after the link. It functions the same as {{t|plink}}, but it does not produce a wikilink in text. Use {{t|chatl}} to link chatheads. These templates create links for both the image and text (except for {{t|plink}}) using far less wikicode than the standard syntax.

Link and file share the same name

{{plink|Item}}

File name differs from the link

{{plink|Item|File}}

Link and file share the same name, but different text is desired to display

{{plink|Item|alt=Text}}

File name differs from the link and different text is desired to display

{{plink|Item|File|alt=Text}}

Categorising

Navboxes are very useful for transcluding categories onto a large number of pages that share both a trait and the navigation box. For example: Template:ShipNavbox transcludes Category:Ships onto every page that uses it.

There are 2 methods of categorising pages with navboxes:

The first way is with {{t|Ctg}}. This is the preferred method, and can be used in most cases. The rules and operations for the Category handler template are very simple; however, they are enough to produce the desired results on most pages.

Categorisation should only be used on a template for large-scale addition. It is unhelpful, for example, to use a rule that only applies to 1 page.

Examples

To see the following navboxes in action, see Template:Navbox.

Single line navbox with centered list

{{navbox
|name    = 
|title   = 
|style1  = text-align:center
|group1  =
}}

Navbox with standard footer

{{navbox
|name    = 
|title   = 
|gtitle1 = 
|group1  = 
|footer  = Centered footer
}}

Navbox with styled footer

{{navbox
|name    = 
|title   = 
|gtitle1 = 
|group1  = 
|fstyle  = text-align:right
|footer  = Right-aligned footer
}}

Multiple line navbox

{{navbox
|name    = 
|title   = 
|gtitle1 = Group title 1
|group1  = 
|gtitle2 = Group title 2
|group2  = 
|gtitle3 = Group title 3
|group3  = 
}}

Collapsed navbox

{{navbox
|state   = collapsed
|name    = 
|title   = 
|style1  = text-align:center
|group1  = 
}}

Plain navbox with Tnavbar

{{navbox
|state   = plain
|name    = 
|title   = 
|style1  = text-align:center
|group1  = 
}}

Plain navbox without Tnavbar

{{navbox
|state   = plain
|title   = 
|style1  = text-align:center
|group1  = 
}}

Complicated navbox

{{navbox
|state   = uncollapsed
|name    = 
|title   = 
|gtitle1 = Level 1 Title 1
|group1  = 
|gtitle2 = Level 1 Title 2
|group2  = 
|gtitle3 = Level 1 Title 3
|group3  = 
|gtitle4 = Level 1 Title 4
|group4  = 
|gtitle5 = Level 1 Title 5
|gtype5  = Subgroup
|group5  = 
  {{navbox
  |subgroup = Yes
  |gtitle1  = Level 2 Title 1
  |group1   =
  |gtitle2  = Level 2 Title 2
  |group2   =
  |gtitle3  = Level 2 Title 3
  |gtype3   = Subgroup
  |group3   = 
    {{navbox
    |subgroup = Yes
    |gtitle1  = Level 3 Title 1
    |group1   =
    |gtitle2  = Level 3 Title 2
    |group2   =
    }}
  |gtitle4  = Level 2 Title 4
  |group4   = 
  }}
|gtitle6 = Level 1 Title 6
|group6  = 
|gtitle7 = Level 1 Title 7
|group7  = 
|fstyle  = 
|footer  = 
}}

Preventing unwanted documentation

The Navbox template's documentation is automatically transcluded under the navbox on any Template namespace page. It is not transcluded when used as a sub-group or collapsible sub-group template (subgroup= yes or collapsible=yes).

Should the documentation appear when it is unwanted, it can be hidden by setting the doc parameter doc=no on the template. In most cases, the doc parameter is NOT used and the parameter is removed completely.