Editing Help:Templates

Jump to navigation Jump to search
Warning: You are not logged in. Your IP address will be publicly visible if you make any edits. If you log in or create an account, your edits will be attributed to your username, along with other benefits.

The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then publish the changes below to finish undoing the edit.

Latest revision Your text
Line 1: Line 1:
{{PageSeo
{{NavWiki|template}}
| title = Template creation
A '''Template''' is a special type of page designed to be included within other pages. Templates are often used as 'shorthand' to automatically insert frequently-used images, code, and formatting on a page. We use templates extensively on bg3.wiki.
| 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'''.
See the [[Help:Template Quick Reference|Template Quick Reference]] for an overview of the most commonly-used templates, or continue reading for examples of various templates.


'''Template documentation''' is essential component of template creation, and ensures templates are well understood and used correctly across the wiki.
Templates are powerful tools and can become very complex. For a much more in-depth look into templates, see [https://www.mediawiki.org/wiki/Help:Templates MediaWiki Help:Templates].


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.
== Page creation templates ==
We use templates like [[:Template:WeaponPage|WeaponPage]] to maintain a clean, consistent style across a large number of pages that share similar properties, such as [[Spell]]s, [[Weapon]]s, and other [[Equipment]]. These templates take your input in the form of standard parameters and use it to generate a pre-formatted page, optimise the page for search engines and embedded social media links, and add the page to the appropriate categories.


== Template names ==
Examples:
In order to ensure templates naming conventions are standardised across the wiki, all templates follow the same naming conventions.
* {{SmallIcon|Worgfang Icon.png}}[[Worgfang]] and {{SmallIcon|Everburn Blade.png}}[[Everburn Blade]] were created using [[:Template:WeaponPage]]
* {{SmallIcon|The Jolty Vest Icon.png}}[[The Jolty Vest]] and {{SmallIcon|Amulet of Lost Voices Icon.png}}[[The Amulet of Lost Voices]] were created using [[:Template:EquipmentPage]]
* {{SmallIcon|Potion of Speed Icon.png}}[[Potion of Speed]], {{SmallIcon|Throwable_Smokepowder_Satchel_Icon.png}}[[Smokepowder Satchel]], and {{SmallIcon|Book Thay A Item Icon.png}}[[Necromancy of Thay]] were created using [[:Template:MiscItemPage]]


=== Template page names ===
Another great benefit of this approach is that it allows us to populate database tables with the provided information. For example, every time you add a new item to the wiki using the appropriate page template, it automatically adds the item to a database table which can be queried from elsewhere. This is, for example, how the lists on weapon type pages like [[Longswords]] are generated.
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.
== Data querying templates ==
When information is added to the wiki using an appropriate page creation template, the information is also made available in a database table. These tables can be queried from other pages, to display the data there as well, instead of having to link the user to the original page, or having to copy-paste the content.


; Examples of good template page names
For example, when you visit the page of a spell that inflicts [[Bleeding (Condition)|Bleeding]], you want to see the effects of the condition right then and there, instead of having to navigate to another page. If we copy-pasted the description of the condition into every page that mentions it, we would have a lot of work to do if a patch for the game changed how the condition works! For this reason, the condition is defined once, using the [[Template:ConditionPage|Condition Page]] template, and other pages query the data to display it.
* {{t link|cite text}}
* {{t link|relative location}}
* {{t link|spell page}}


==== Exceptions ====
Writing these queries can be quite complicated. So, the wiki offers templates that do the heavy lifting for you. A primary example is the [[Template:Condition|Condition]] template, which you provide with the name of a condition, and it queries the data for you, displaying the effects of that condition in a nice format.
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.
== Other templates ==
Other templates can be used in a more focused fashion to insert frequently used, pre-formatted information or to add visual flair to a page, such as <code><nowiki>{{MediumArmour}}</nowiki></code> ({{MediumArmour}}) or <code><nowiki>{{action|bonus}}</nowiki></code> ({{action|bonus}}). These types of templates are often embedded within other, larger templates like Page Creation Templates, but they can and should also be used on their own where appropriate.


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.
Additional template examples:
* [[Template:CharacterInfo]] can generate character infoboxes for Companions, NPCs, and other creatures.
* [[Template:Ability]] and [[Template:Class]] can add formatted Ability Scores and Classes, like so:
** {{Ability|Strength|20}}, {{Class|Cleric}}
* [[Template:SAI]] for '''S'''pell and '''A'''ction '''I'''con Links. Like so:
** {{SAI|Magic Missile}}, {{SAI|Frenzied Strike}}
* [[Template:ItemIcon]] and other templates in that family, such as [[Template:RarityItem]]. Like so:
** {{RarityItem|Dagger +1}} for a rarity border use {{InfoBlob|<nowiki>{{RarityIcon|Dagger +1}}</nowiki>}}
** {{SmItemIcon|Dagger +1}} for a simple iconlink use {{InfoBlob|<nowiki>{{SmItemIcon|Dagger +1}}</nowiki>}}


=== Shortcuts ===
== Using templates ==
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.
=== Add a template to a page ===
[[File:visual_editor_template.png|right|thumb|Inserting a template with the Visual Editor]]
* When using the Visual Editor, select '''Insert''' &gt; '''Template''' from the toolbar and start typing a template name. The visual editor may not always display documentation for the template or its parameters, so be sure to open the template's page for usage information.
* When using the Source Editor, you can either copy and paste template code from an existing page, or newly invoke a template you're already familiar with by enclosing the template name in {{code|<nowiki>{{double curly braces}}</nowiki>}}. For example:
** Code: {{code|This attack has <nowiki>{{Advantage}}</nowiki>}}
** Result: This attack has {{Advantage}}


There are no precise standards for naming shortcuts, but they should ideally be intuitive and unambiguous.
=== Template parameters ===
Some templates have optional or required '''parameters''' that change the output of the template, giving it more versatility.


Typically, a shortcut is considered reasonable if:
When invoking a template with parameters, separate each parameter with a pipe symbol {{code|<nowiki>|</nowiki>}}.
* It is an unambiguous abbreviation of the target template's name.
* Template with one parameter:
* It is more convenient to type than the full template name.
** Code: {{code|<nowiki>{{enchantment|+1}}</nowiki>}}
* It is closely associated with the template's function.
** Result: {{enchantment|+1}}
* Template with multiple parameters:
** Code: {{code|<nowiki>{{AttributeBlock|8|15|7|6|10|8|hp=12|dex save = yes|race=Bird|hp=10}}</nowiki>}}
** Result:
{{AttributeBlock|8|15|7|6|10|8|hp=12|dex save = yes|race=Bird|hp=10}}


; Examples of shortcuts
=== Template documentation ===
* {{t link|"}}, redirects to {{t link|quote inline}}
{{hatnote|See also: [[Help: Template documentation]]}}
* {{t link|t link}}, redirects to {{t link|template link}}
Template creators are encouraged to document (on the template's page itself as well as via the TemplateData button on the same page) how to use that template, including usage examples and accepted values for any template parameters. If you're unfamiliar with a particular template, navigate to its page to learn how it works. If a template page does not show any usage instructions, it could still be a work in progress, and you may want to check with its creator before using it.
* {{t link|cw}}, redirects to {{t link|content warning}}


== Template creation guidelines ==
See [https://bg3.wiki/wiki/Special:AllPages?namespace=10 All Pages (Template namespace)] for a full list of available templates on bg3.wiki.
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 ===
=== More template examples ===
Ideally, new templates should be:
* The {{code|<nowiki>{{DamageInfo}}</nowiki>}} and {{code|<nowiki>{{DamageText}}</nowiki>}} templates can insert pre-formatted damage information based on the parameters you provide, like so:
# Easy to use, with as few parameters as possible.
**{{code|<nowiki>{{DamageInfo|2d6+1|Slashing|modifier=melee}}</nowiki>}} displays {{DamageInfo|2d6+1|Slashing|modifier=melee}}
# Have clear and easy to understand [[Help: Template documentation|template documentation]] with examples.
**{{code|<nowiki>{{DamageText|1d4|Fire}}</nowiki>}} displays {{DamageText|1d4|Fire}}, better for compact or inline usage
# Always include a list of all of a template's shortcuts.
* The {{code|<nowiki>{{Icon}}</nowiki>}} and {{code|<nowiki>{{SmallIcon}}</nowiki>}} templates help you add an icon to represent a spell or item, like so:
# Have easy to use TemplateData.
** {{code|<nowiki>{{Icon|Chain Mail Icon.png}} [[Chain Mail]]</nowiki>}} displays {{Icon|Chain Mail Icon.png}} [[Chain Mail]], the better alternative to this is [[Template:ItemIcon]].
 
** {{code|<nowiki>{{SmallIcon|Magic Missile Icon.png}} [[Magic Missile]]</nowiki>}} displays {{SmallIcon|Magic Missile Icon.png}} [[Magic Missile]], the better alternative to this is [[Template:SAI]].
=== 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|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.
 
== 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]


[[Category: Wiki Help]]
[[Category: Wiki Help]]
Please note that all contributions to Baldur's Gate 3 Wiki are considered to be released under the CC BY-NC-SA license, except when noted otherwise (see BG3Wiki:Copyrights for details). If you do not want your writing to be edited and redistributed at will, do not submit it here. Per our Content Rules, you are promising that you wrote this yourself, or copied it from a public domain or similar free resource. Do not submit copyrighted work without permission!

To edit this page, please answer the question that appears below (more info):

Cancel Editing help (opens in new window)

Templates used on this page:

Retrieved from "https://bg3.wiki/wiki/Help:Templates"