7,281
editsAd placeholder
Help:Templates: Difference between revisions
Jump to navigation
Jump to search
→Template documentation
No edit summary |
|||
| (21 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
{{ | {{PageSeo | ||
{{hatnote|This article is a technical guide to the | | title = Template creation | ||
A ''' | | 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'', added with {{t link|shortcut}}. 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|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. | |||
# Always include a list of all of a template's shortcuts. | |||
# 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. | |||
=== 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|template demo}}, {{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. | |||
== 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. | |||
== Additional resources== | |||
* [https://www.mediawiki.org/wiki/Help:Templates MediaWiki Help:Templates] | * [https://www.mediawiki.org/wiki/Help:Templates MediaWiki Help:Templates] | ||
[[Category: Wiki Help]] | [[Category: Wiki Help]] | ||