Editing Help:Templates

{{PageSeo
| title = Template creation
| image = bg3wiki_help.png
| description = Guidelines for creating templates and writing template documentation on Baldur's Gate 3 Wiki.
}}
{{hatnote|This article is a technical guide to the creation of templates on BG3Wiki. For a guide on how to use templates, see [[Help:Using templates]]. See [[Help:List of templates]] for a list of templates.}}
{{NavWiki|help}}
A template is a special type of page designed to be transcluded within other pages. Templates allow editors to automatically insert frequently-used images, code, and formatting on a page. 

To ensure standardised practices across the wiki, this page provides guidelines for the process of '''template creation'''.

'''Template documentation''' is essential component of template creation, and ensures templates are well understood and used correctly across the wiki.

To create or edit templates you need access to them. This can be requested on the Discord or by visiting an admin's talk page.

== Template names ==
In order to ensure templates naming conventions are standardised across the wiki, all templates follow the same naming conventions.

=== Template page names ===
Template page names should be given in lower case letters with a single space between words.

Note that the first letter of a template page name will always be considered capitalised, including when the template is linked to or transcluded.

; Examples of good template page names
* {{t link|cite text}}
* {{t link|relative location}}
* {{t link|spell page}}

==== Exceptions ====
Sometimes template names may consist of an abbreviation or a single word.

For example, {{t link|reflist}} is named as such because it adds a <nowiki><reference></nowiki> tag to list references. If it had been named <nowiki>{{reference list}}</nowiki> the name would have implies it's a list of or for {{em|reference}} tags instead.

Similarly, certain abbreviated names for templates such as {{t link|sai}}, {{t link|ref}} and {{t link|em}} are also considered acceptable, due to their simplicity.

=== Shortcuts ===
To make templates easier to use, each template should have 1-5 ''shortcuts''. These are redirects which have shorter names for ease of access. These do not need to follow the template page naming conventions.

As few shortcuts as possible should be created in order to prevent ambiguity. It a single shortcut is sufficient, then additional shortcuts {{em|should not}} be created.

There are no precise standards for naming shortcuts, but they should ideally be intuitive and unambiguous.

Typically, a shortcut is considered reasonable if:
* It is an unambiguous abbreviation of the target template's name.
* It is more convenient to type than the full template name.
* It is closely associated with the template's function.

; Examples of shortcuts
* {{t link|"}}, redirects to {{t link|quote inline}}
* {{t link|t link}}, redirects to {{t link|template link}}
* {{t link|cw}}, redirects to {{t link|content warning}}

== Template creation guidelines ==
Template creation is an essential part of the technical BG3Wiki workflow. However, it's important to take care when creating or improving templates.

=== What to keep in mind ===
Ideally, new templates should be:
# Easy to use, with as few parameters as possible.
# Have clear and easy to understand [[Help: Template documentation|template documentation]] with examples.
# Have easy to use TemplateData.

=== Important considerations ===
Some important considerations when creating templates:
* Line breaks interact unexpectedly with the table parser, which can break some templates.
* Adding a pipe to a template parameter <nowiki>{{{parameter}}} > {{{parameter|}}} </nowiki> will provide it with a default value (in this case, an empty string).
** This is important to remember when using the <nowiki>{{#if:}} </nowiki> parser function, since in cases where a parameter is undefined, <nowiki>{{{parameter}}}</nowiki> will return the value "true", whereas <nowiki>{{{parameter|}}}</nowiki> will return the value "false".
** It is also important to remember when a parameter is used as a value, since in cases where a parameter is undefined, <nowiki>{{{parameter}}}</nowiki> will return the value "<nowiki>{{{parameter}}}</nowiki>", whereas <nowiki>{{{parameter|}}}</nowiki> will return its default value (in this case, an empty string).
* Expr and ifeq, when evaluating numbers, produce different results. This is because expr treats numbers as floats, whereas ifeq treats them as integers.

=== Cargo database ===
Templates also allow the wiki to populate database tables with stored values using [https://m.mediawiki.org/wiki/Extension:Cargo Cargo queries]. This allows the wiki to create automatically generated lists of items or spells.

=== Formatting ===
* Templates {{em|must}} have "template data", achieved by clicking "Manage template data" at the top of the page. This enables templates to be used by visual editors.
** The template data {{em|must}} be on the template's main page if it does not have a doc subpage. It {{em|must}} be on the template's doc subpage if it does have one.
* Templates {{em|should}} have documentation that includes at least one example of its usage. 
* Templates {{em|should}} use {{c|<nowiki>{{documentation|content=}}</nowiki>}} for all of its documentation.
** Long documentation {{em|may}} be moved to a {{c|/doc}} subpage. In this case, use {{c|<nowiki>{{documentation}}</nowiki>}} on the main page instead.
* Templates {{em|must}} have categories. At the bare minimum, it should be categorized as [[:Category:Templates]] or one of its subcategories.
** The categories {{em|should}} be located on the doc subpage, if it exists. The doc subpage {{em|must}} use {{c|<nowiki><noinclude></nowiki>}} tags around categories, otherwise the subpage will be counted as a template in the category index.
* Cargo declare {{em|must}} be in a noinclude on the template's main page, even if there is a doc subpage.

== Template documentation ==
Template documentation should ideally include the following:
* A description of what the template does.
* Examples of the template in use, either using {{t link|comparison table}}, {{t link|c}} and / or <nowiki><pre></pre></nowiki> tags.
* Clear descriptions of the template's parameters.
* Links to similar or relevant templates.

=== How to include documentation ===
The template itself should be placed within the tag {{code|<nowiki><includeonly></includeonly></nowiki>}}. The template documentation should follow immediately after and should be placed within the tag {{code|<nowiki><noinclude></noinclude></nowiki>}} and use [[Template:Documentation]]. Be careful not to leave any unnecessary whitespace or line breaks! Example:
: {{code|<nowiki><includeonly>Template here.</includeonly><noinclude>{{documentation|content=Template documentation here.}}</noinclude></nowiki>}}

Examples can be written using either the <nowiki>{{code}}</nowiki> template and the <nowiki><nowiki></nowiki></nowiki> tag:
: {{code|<nowiki>{{code|<nowiki>{{ExampleTemplate|ExampleParameter}}</nowiki></nowiki><nowiki>}}</nowiki>}}

Or by using well as the {{code|<nowiki><pre>...</pre></nowiki>}} tag.

The code example should be followed by the actual template in use.

Templates that have very long documentation can move the documentation (including template data) to the {{C|/doc}} subpage. The main page can simply contain {{c|<nowiki><noinclude>{{documentation}}</noinclude></nowiki>}}. The {{c|/doc}} subpage's contents will then automatically be transcluded on the template's page. Note that categories should remain on the main template page, still within the {{c|noinclude}} tags.

=== Writing template data ===
{{hatnote|For a thorough guide to TemplateData, see [https://m.mediawiki.org/wiki/Special:MyLanguage/Help:TemplateData Information about TemplateData]}}
TemplateData can be managed by via the Template Documentation Menu, which can be opened via the "Manage TemplateData" button located above the Source Editor:
[[File:Template documentation Manage TemplateData.png|thumb|758px|center|alt=A screenshot of the Manage TemplateData button which is located above the Source Editor.]]

TemplateData allows editors using the Visual Editor to easily add Templates to articles, but can also serve as an effective shorthand documentation for editors using the Source Editor.

== Additional resources==
* [https://www.mediawiki.org/wiki/Help:Templates MediaWiki Help:Templates]

[[Category: Wiki Help]]