Guidelines:Templates

Main Page

Guidelines:Getting Started

Getting Involved

Discord

Discord

Zelda Wiki:Knight Challenges

Knight Challenges

Zelda Wiki:Image Requests

Image Requests

https://trello.com/b/ToL30iNx/wiki-projects

Trello

Guidelines:Main

Guidelines

A template is a page made to be included in other pages. Template pages define reusable pieces of wikitext forming common elements of articles such as infoboxes, navboxes, citations, and so on.

Template pages are created in the Template namespace.

Using templates

Templates are invoked using double curly brackets, like so:

{{Nomenclature}}

The template page, in this case Template:Nomenclature, should explain the purpose of a template and how to use it. When using a template for the first time, please take the time to read its documentation. If documentation is absent or unclear, you can ask for help in the #wiki-tech channel on our Discord server or on the template's talk page.

Ways to invoke a template

Transclusion

Main article: mw:Help:Transclusion

Transclusion is the most common way to use templates. Here are some examples:

Input	Output
{{OoT}}	Ocarina of Time
{{OoT|-}}	Ocarina of Time
{{Cite Book|book= E|page= 97}}	Encyclopedia, Dark Horse Books, pg. 97

When a page is loaded, the transclusion wikitext, as shown in the Input column, is replaced with the contents of the template, as shown in the Output column). This process is called expansion.

As shown in the second and third examples above, some templates accept parameters, which modify the template's output. Additionally, some templates have page detection and will change their output depending on which page they're used on.

Substitution

Main article: mw:Help:Substitution

---

---

Parameters

Main article: mw:Help:Templates § Parameters

Templates can define parameters to modify their output. When a template is invoked, the values passed for these parameters are known as arguments.

Here are some examples of templates being used with parameters:

Input	Output
{{Color TWWHD|Vermilion|merchant's oath}}	merchant's oath
{{Cite Book|book= E|page= 97}}	Encyclopedia, Dark Horse Books, pg. 97
{{Correct Title|Swordsman Newsletter #1|reason= <code>#</code>}}	The correct title of this article is Swordsman Newsletter #1. The omission of the # is due to technical restrictions.

In the first example, Vermilion is the argument provided for the positional parameter (or anyonymous parameter) in position 1. merchant's oath is the parameter in position 2.

In the second example, book and page are named parameters.

A template can mix positional and named parameters, as shown in the third example.

Aliases

At Zelda Wiki, positional parameters are typically assigned aliases for documentation purposes. The "true identity" of the parameter remains a number—we just assign an alias so that we have a word to refer it by. In {{Color TWW}} as shown above, parameter 1 is given the alias color, and parameter 2 the alias text. These terms are used in validation warnings when these required parameters are missing.

Lists

Many of Zelda Wiki's templates accept lists of values as parameters. Some templates accept lists as comma-separated values (CSV), while others use bulleted lists with the asterisk (*) as the bullet symbol, in imitation of the MediaWiki syntax for unordered lists.

Input	Output
<!-- Comma-separated values --> {{Exp Game|OoT, MM, TP}}	(OoTOcarina of Time | MMMajora's Mask | TPTwilight Princess)
<!-- Bullet list --> {{Icon List|BotW| * Chillshroom * Blue Nightshade * Winterwing Butterfly }}	Chillshroom Blue Nightshade Winterwing Butterfly

MediaWiki does not have a built-in mechanism for list parameters. These are Zelda Wiki idioms implemented using the Lua module functions splitComma and splitAsterisk.

Some wikis use variadic parameters for lists. One limitation with this method is that a single transclusion cannot provide multiple different lists, which is something some of our templates do. See for example Template:Categories.

Tuples

A tuple is an ordered sequence of values. A 2-tuple is an ordered pair of values, a 3-tuple an ordered sequence of 3 values, and so on. The number of values in a tuple is called arity.

In the context of Zelda Wiki templates, there are two kinds of tuples: variadic tuples and named tuples.

Variadic tuples

Variadic tuples use variadic parameters for tuple values, with |- arguments separating rows in imitation of MediaWiki's table markup. In fact, variadic tuples are most often used to represent table rows that require some addiditional processing by a template. {{Data Table}}, {{Treasure Chests}}, and {{Wares}} are examples of templates that use variadic tuples.

Input	Output	Categories added
Template:Treasure Chests accepts variadic 4-tuples, or 3-tuples if the "Coordinates" column does not apply.
{{Treasure Chests|game= OoS |- | Treasure Chest [2] | Gasha Seed | [[File:OoS Gnarled Root Dungeon Treasure Chest 2.png|108px]] | In 1F's western room |- }}	Treasure Chest Contents Coordinates Notes Treasure Chest Gasha Seed In 1F's western room	Category:Pages with data tables
{{Treasure Chests|game= SS |- | Treasure Chest | Red Rupee | On the ledge near the entrance of the Cave |- | Treasure Chest | Red Rupee | On a small ledge in an open }}	Treasure Chest Contents Notes Treasure Chest Red Rupee On the ledge near the entrance of the Cave Treasure Chest Red Rupee On a small ledge in an open	Category:Pages with data tables
Template:Data Table accepts tuples with an arity corresponding to the number of columns defined.
{{Data Table |columns= A, B |- | A1 | B1 |- | A2 | B2 }}	A B A1 B1 A2 B2	Category:Pages with data tables

Named tuples

Named tuples use named parameters for tuple values, with numbers at the end to indicate which tuple they correspond to. {{Navbox}} is an example of a template that uses named tuples.

Input	Output
{{Navbox |header= Zelda stuff |group1= Characters |links1= * [[Link]] * [[Zelda]] * [[Ganon]] |group2= Items |links2= * [[Boomerang]] * [[Hookshot]] * [[Sword]] }}	Zelda stuff hide ▲ Characters Link • Zelda • Ganon Items Boomerang • Hookshot • Sword

Variadic parameters

Some templates accept an indefinite number of positional parameters. We call these variadic parameters. In Zelda Wiki's templates, they are typically used for variadic tuples. One exception is Template:Template, which uses variadic parameters like so:

Input	Output
{{Template|Color TWW|Vermilion|merchant's oath}}	{{Color TWW|Vermilion|merchant's oath}}

Many wikis use variadic parameters to pass lists of values to templates. While some Zelda Wiki templates do still support this method, it has largely been superseded by list parameters.

Page detection

Some templates, such as {{Nomenclature}}, detect which page they're being used on and change their output accordingly. This is typically done using the magic word {{SUBPAGENAME}} so that sandboxes can have the same template output as their mainspace equivalents. For example, {{Nomenclature}} will generate the same output on User:SomeUser/Sandbox/Ganondorf as on Ganondorf.

Errors

Main article: Zelda Wiki:Errors

---

---

Warnings

Main article: Zelda Wiki:Errors § Warnings

---

---

Using pages as templates

Any page can be transcluded or substituted like a template. The only difference with pages in the Template namespace is that you don't need to use a namespace prefix when you invoke them.

Mainspace pages can be transcluded like so:

{{:Bosses in Echoes of Wisdom}}

Pages in any other namespace can be transcluded like so:

{{User:CantomPhaleb/Sandbox}}

Developing templates

Accessibility

All templates should expand to accessible content. Where possible, use semantic HTML, and WAI-ARIA attributes if needed. Refer to Help:HTML in wikitext for a list of HTML tags and attributes that MediaWiki allows in wikitext.

Case study

Before Template:List was created, editors would use <br> tags in infoboxes to make lists styled without bullet points. Although this seems to work well enough at a glance, it results in poor semantics—the HTML generated from this wikitext does not explicitly indicate the presence of a list, which could cause confusion for visually impaired users who use screen readers to browse the web.

Template:List uses the semantically correct <ul> list element, which allows screen readers to announce lists as such. (Normal unordered list syntax also generates <ul> tags—Template:List simply uses CSS to style them without bullet points.)

Controlling inclusion

Main article: mw:Help:Templates § Controlling template inclusion

By default, a template's content is displayed in its entirety, both when viewed directly and when included in another page. The template's page when viewed directly appears exactly as the template would render without any parameters.

This is an issue if the template has required parameters. Also, we want a template's documentation to be displayed on the template page itself, but obviously not in any transclusions.

The includeonly and noinclude tags address these issues. Content within includeonly is only included during transclusion, and not on the template page itself. Conversely, content within noinclude tags is only displayed on the template page, and not in tranclusions.

Thus, the wikitext on template pages often looks like this:

<includeonly>template implementation</includeonly><noinclude>{{/Documentation}}</noinclude>

The includeonly tags can be omitted if the template accepts no parameters.

Documentation

All templates should have documentation. This documentation should be placed on a /Documentation subpage (e.g. Template:Nomenclature/Documentation and transcluded on the main template page like so:

<noinclude>{{/Documentation}}</noinclude>

Documentation is placed on a separate page because otherwise editing the documentation would trigger unnecessary jobs for all the pages transcluding the template.

Documentation pages should look something like this:

==Purpose==
<!-- Explain the purpose of the template. What problem does it solve? -->

==Usage==
{{Parameters}}
<!-- Using the above template, document the template's parameters if any. -->

===Examples===
{{Examples/v2
|-
|
}}
<!-- 
Provide examples that illustrate all the different ways that the template can be used. Ideally, use examples from actual articles where the template is used.

You should also provide examples covering all the ways in which a template can be ''misused'', such as missing required parameters or invalid arguments. This ensures that the template has proper error handling.
-->

{{Documentation Footer}}<includeonly>
<!-- Place the template in one or more subcategories of Category:Templates -->
</includeonly>

Categorization

As shown in the boilerplate above, templates should be placed in a subcategory of Category:Templates. The categories should be placed on the /Documentation using includeonly tags.

The includeonly tags ensure that the template page itself is categorized, not the documentation subpage. Categories should be placed on the documentation subpage to avoid triggering unnecessary jobs.

Implementation

Gadgets

---

---

Interactive templates like {{Tabs}} and {{Smoothie Calculator}} depend on JavaScript code loaded via Extension:Gadgets. Such templates should be marked with Template:Gadget Dependant.

Magic words

Main article: mw:Help:Magic words

---

---

Modules

Main article: Guidelines:Modules

---

---

Template styles

Main article: Guidelines:CSS

---

---

Internationalization

Internationalization (i18n for short) is the process of designing a template or module such that it can be easily imported by other wikis in any language, particularly foreign-language Zelda wikis in our family.

Templates and modules are internationalized by having their English text stored in system messages, rather than in the code directly. This allows other wikis translate the text without having to edit the code. By the same token, Zelda Wiki administrators can more easily change the English text as well.

By convention, these system messages are prefixed with zw- to distinguish them from system messages used by MediaWiki itself.

List of zw- system messages

Naming

Please use title case for template names on Zelda Wiki.

Do	Don't
Use title case {{Page or Section}}	Don't use sentence case or camel case {{page or section}} {{PageOrSection}}

Optimization

Speed

It takes a certain amount of time for MediaWiki to expand each transclusion on a page. Template developers must take care to ensure that any changes they introduce do not significantly increase the loading time of articles in the mainspace. The NewPP parser report lists the most expensive template calls on a page.

A template's expansion time depends mainly on how it uses magic words and extension tags. Cargo calls and DPL queries tend to be the most expensive calls on a page.

Scale

Every time someone edits a template or one of its dependencies, MediaWiki triggers jobs to update every single page that transcludes the template. If the template is transcluded on hundreds or thousands or pages, the resulting job queue may strain Zelda Wiki's servers and/or lead to increased server costs.

Our current hosting situation is stable enough to support these kinds of edits. However, template editors should be aware that these edits have a cost. We must do our best to minimize their occurrence.

High-usage templates that require frequent updates, such as color templates, should be split by game. High-usage templates should have minimal dependencies, as any edits to a dependency will also trigger a cascade of jobs for the templates that use it. If a certain template functionality is used only for a small subset of the template's total transclusions, consider making a separate template speficially for that functionality.

Reflection

Reflection refers to certain templates' ability to describe the arguments provided to them in a format other templates can read—typically JSON. Documentation generators such as Template:Descriptions/DocGen and Template:Navbox Doc rely on the reflection functionality of the templates they document, which are bult with Template:Descriptions and Template:Navbox/v2, respectively.

Testing

When editing a template, a Preview page with this template option should appear at the bottom of the edit form. In the Page title box, enter the name of a page that currently uses the template and press the adjacent Show preview button. This allows you to preview the template as it would appear on that page if you saved the edit.

When developing a template, it is often useful to start by creating examples that demonstrate how you want the template to work. As you develop the template, you can preview your examples to see if your code is working. It's the wiki version of test-driven development.

Versioning

Oftentimes a template's shortcomings become apparent only after editors have started using it. Template developers can choose to improve the existing template or create a new one from scratch.

If you find yourself having to make this choice, ask yourself this: Do the parameters of the existing transclusions need to be changed? If so,

• Are there many transclusions to change?
• Can the transclusions be changed with a bot?
• Will the old parameters still work while the migration is happening?

If one decides a new template is needed, this is a good time to consider a different template name. Otherwise, you can make a /v2 subpage of the current template (e.g. Template:Navbox/v2) until the migration is complete, at which point the old template can be deleted and the new one can be moved to the basepage. In the meantime, mark the old template as deprecated.

How templates work

Caching

Main article: mw:Manual:Cache

---

---

Expansion

Main article: mw:Manual:Parser

Expansion is the process by which the MediaWiki parser transforms template invocations into wikitext. The difference between transclusion and substitution is a matter of when the expansion actually happens. With transclusion, the expansion happens when the page is loaded. With substitution, the expansion happens sooner—the moment the editor saves the page, with the result of the expansion being what is stored on the page. In other words, substitutions are expanded when the page is edited, and transclusions are expanded when the page is read.

To avoid slow page loading, it is therefore necessary to ensure that templates are developed and used such that the tranclusion expansion time is reasonably optimal. The NewPP parser report has a transclusion expansion time section indicating the top 10 most time-consuming templates on the page.

Special:ExpandTemplates can take transclusions and show the result of fully expanding them to wikitext. When debugging a template issue, this can be useful for understanding what a transclusion is actually producing on the page.

Job queue

Main article: mw:Manual:Job queue

---

---

Notes

Guidelines

hide ▲

Main

Account Migration • Code of Conduct • Getting Started • Main Guidelines • Policy Voting Process • Projects

Content

Articles • Boilerplates • Cameos • Canon • Categories • Files • New Games • Redirects • References • Sandboxes • Terminology • Theories • Translations

Games and Books

Breath of the Wild • Echoes of Wisdom • Encyclopedia • Age of Calamity • Link's Awakening for Nintendo Switch • Tears of the Kingdom

Technical

Animated PNGs • Bots • Cargo • CSS • Modules^{(Data, Exercises)} • Moving Pages • Pywikibot • Templates

Templates

{{Categories}} • {{Media}} • {{Navbox}} • {{Term}}

Policy Log