Help:Template

From The Sims Wiki, a collaborative database for The Sims series
Jump to navigation Jump to search
This page is a help page
It is meant to detail processes or procedures of some aspect or aspects of The Sims Wiki's norms and practices. It is not a policy page.

A template is a page that is created to be included on other pages. This is usually done for material that needs to be displayed on multiple pages. Templates are usually used to display infoboxes, navboxes, and notice messages.

Templates are usually added to pages through a method called transclusion, where the contents of the template are added to a page by referencing the template in the wikitext of the page using a special syntax that causes the contents of the template to be added to the page. When a template is transcluded, any changes made to the template will be automatically propagated to all of the pages the template is transcluded on.

Templates are usually stored in the Template namespace. Pages are considered part of this namespace if their title begins with Template: (note the colon).

Using templates[edit source]

Templates can be used on a page by editing the target page and typing in {{Name of template}} where you want the template to appear. This will cause the contents of the page "Template:Name of template" to appear in that spot. This is known as transclusion, and is the typical way most templates are used. Like regular wikilinks, the first letter of the template name is not case-sensitive.

Templates in the Template namespace can be transcluded with or without the Template: prefix; it does not matter. Both {{Foo}} and {{Template:Foo}} will both transclude the contents of "Template:Foo" onto the page. Templates that are stored in other namespaces need to have the namespace prefix attached. For example, a template that is being stored at "User:Foo/Template" must be called with {{User:Foo/Template}}. Typing in {{Foo/Template}} will cause the contents of "Template:Foo/Template" to be used instead.

If you try to use a template that doesn't currently exist, the template will be displayed as a red link, just like links to any other non-existent page. Clicking on this link will take you to a page where you can create the template page in question.

Parameters[edit source]

Many templates allow for the use of parameters that can, depending on the template, control different aspects of how the template is used, displayed, or functions on the page. The syntax for displaying parameters is {{Template name|parameter|parameter|...}}, where Template name is the name of the template, and each parameter may contain just a value (known as unnamed parameters) or be in the form name=value (known as named parameters). Template parameters are dependent on the coding of the template and will usually differ between templates. A template's documentation may provide information on the parameters it offers and how to use them.

For example, the {{FontColor}} template uses two unnamed parameters to control its output. This template provides a simple way of changing the text's background and color. The template documentation explains how to use the template in more detail. The template can be used like the following:

{{FontColor|Color of text|Text}}

If you type {{FontColor|blue|Text in blue!}} on a page, it would produce the following:

Text in blue!

And if you were to type {{FontColor|red|Text in red!}}, it would produce:

Text in red!

The first parameter sets the color of the text, while the second parameter is used for the text that should be colored. These two parameters normally need to be specified in the correct order in the wikitext for them to work. For example, {{FontColor|Text in blue!|blue}} will not work correctly.

Unnamed parameters are technically given a cardinal number as a name, so in the above example, the actual names for the parameters above are 1 and 2. As such, {{FontColor|1=blue|2=Text in blue!}} will work the same as {{FontColor|blue|Text in blue!}}. When using parameters like this, the ordering of the parameters in the wikitext does not matter, so {{FontColor|2=Text in blue!|1=blue}} will work correctly.

Named parameters have a defined name and must be called by that name in order to work. The {{Metabox}} template, for instance, utilizes named parameters to control and display its output. If you were to type:

{{Metabox|text=This is a message.|headline=Attention!|type=notice|image=Nuvola apps important.svg}}

It would produce:

Attention!
This is a message.

Parameters don't need to be in the same line; it is okay for them to be separated by line breaks. This is useful if there are a lot of named parameters, making it easier to read the wikitext later on.

{{Metabox
|text             = This is a message.
|headline         = Attention!
|type             = notice
|image            = Nuvola apps important.svg
}}

As mentioned previously, it doesn't matter what order named parameters are listed in in the wikitext of the page.

{{Metabox
|headline         = Attention!
|text             = This is a message.
|image            = Nuvola apps important.svg
|type             = notice
}}

Substitution[edit source]

Main article: Help:Substitution

Most templates are used through transclusion, which is where the template's contents are automatically passed on to the page it is being used on. If the template is edited, the changes will be reflected on all pages that the template was transcluded on automatically, without any further edits necessary. For example, if "Template:XYZ" contained the text "The quick brown fox", and {{XYZ}} was added to the page "Animals", then the page "Animals" would contain the text "The quick brown fox" where {{XYZ}} was added. If "Template:XYZ" was edited to read "The quick brown fox jumps over the lazy dog", the "Animals" page would automatically update to read "The quick brown fox jumps over the lazy dog".

Substitution is an alternative method of using templates. When a template is substituted instead of being transcluded, the template's actual contents will be copied over to the page it is used on and will become a part of the page, and will no longer be automatically updated if the template is edited. In the above example, if {{subst:XYZ}} was used on the "Animals" page, when the edit is saved, the {{subst:XYZ}} code in the wikitext of the page will automatically change to "The quick brown fox", which is the contents of "Template:XYZ". If "Template:XYZ" is later edited to read "The quick brown fox jumps over the lazy dog", the "Animals" page will not reflect those changes because it no longer transcludes "Template:XYZ", and will continue to read "The quick brown fox".

Creating templates[edit source]

Templates are created like any other page. Most templates are located in the Template namespace, so their page titles should begin with Template: (note the colon) in order to be organized correctly. Many users who create templates for their own personal use or for testing purposes may also create them in a subpage of their userpage. Templates can technically be created on any page, but in practice it is best to create templates only in the two locations mentioned above.

Basic content transclusion[edit source]

The most basic template simply displays a prewritten or predefined text, image, table, or other form of page content, which can then be quickly used on multiple pages. This is as simple as writing the content you want the template to contain in the template page. For example, if we wanted to use the following text in our template...

"Have you guessed the riddle yet?" the Hatter said, turning to Alice again. "No, I give it up," Alice replied: "what's the answer?" "I haven't the slightest idea," said the Hatter. "Nor I," said the March Hare. Alice sighed wearily. "I think you might do something better with the time," she said, "than wasting it in asking riddles that have no answers."

...this is as simple as creating a template containing that text. For example, we can create a page titled "Template:Alice in Wonderland pointless riddle" containing just the text above, and we have our first template. Whenever we type {{Alice in Wonderland pointless riddle}} onto a page, that text will appear.

Adding parameters[edit source]

Main article: #Parameters

Template parameters are specified in the template code by using three curly braces ({{{ }}}) instead of the usual two for calling templates.

  • Unnamed parameters are created by using the codes {{{1}}}, {{{2}}}, and so forth. When the template is used, these parameters must either be used in order, or by using numbers as parameter names. For example, if "Template:Thank you" were to contain the code Thank you for {{{1}}}. Sincerely, {{{2}}}., then typing {{Thank you|your effort|Your Boss}} or {{Thank you|1=your effort|2=Your Boss}} on a page would produce "Thank you for your effort. Sincerely, Your Boss."
  • Named parameters are created by using the code {{{name of parameter}}}. For example, if "Template:Thank you" were to contain the code Thank you for {{{reason}}}. Sincerely, {{{signature}}}., then typing {{Thank you|reason=your effort|signature=Your Boss}} on a page would produce "Thank you for your effort. Sincerely, Your Boss."

These parameter codes will be replaced by whatever value is given to them when the parameter is used, even if it is blank. If the parameter isn't called at all, no replacement will take place, and the templates will show the raw parameter code, which may be undesirable. For instance, in the above example, simply writing {{Thank you}} will cause "Thank you for {{{1}}}. Sincerely, {{{2}}}." or "Thank you for {{{reason}}}. Sincerely, {{{signature}}}." to appear. You can rectify this in two ways:

  • You can specify a default parameter value that will be shown if the parameter isn't used or is left blank. You can do this by adding a pipe character (|) after the name of the parameter but before the closing curly braces. For example, Thank you for {{{reason|your effort}}} will produce "Thank you for your effort" if {{Thank you}} is used on a page. You can also set it so that the parameter simply doesn't display anything when it isn't used by just providing a pipe character. For example, Thank you for {{{reason|}}} will produce "Thank you for " if {{Thank you}} is used on a page.
  • You can use the #if parser function to either set a default value or don't produce any output if the parameter isn't used or is left blank. For example, Thank you for {{#if: {{{reason|}}} | {{{reason}}} | your effort }} will produce "Thank you for your effort" if {{Thank you}} or {{Thank you|reason=}} is used on a page, and "Thank you for being awesome" if {{Thank you|reason=being awesome}} is used.

Magic words and parser functions[edit source]

Templates often make good use of magic words and parser functions, which are special features of wiki markup that can give instructions to the wiki software to perform certain basic tasks, such as checking to see if a parameter is filled or performing mathematical operations.

Examples of magic words and parser functions
Description Text entered Result
Uppercasing text {{uc: Heavens to BETSY! }} HEAVENS TO BETSY!
Lowercasing text {{lc: Heavens to BETSY! }} heavens to betsy!
Getting a namespace name {{NS: 1 }} Talk
Getting a The Sims Wiki URL {{fullurl: pagename }} https://www.thesimswiki.com/wiki/Pagename
Testing for equality between two strings (or parameters) {{#ifeq: yes | yes | Hooray...! | Darn...! }} Hooray...!
{{#ifeq: yes | no | Hooray...! | Darn...! }} Darn...!
Testing whether a string (or parameter) contains anything (other than whitespace) {{#if: {{{param|}}} | Hooray...! | Darn...! }} Darn...!
Making a mathematical calculation
[area of circle of radius 4, to 3 decimal places]
{{#expr: ( pi * 4 ^ 2 ) round 3 }} 50.265
Testing the result of a calculation
[is 1230 even or odd?]
{{#ifexpr: 1.23E+3 mod 2 | Odd | Even }} Even
Page names {{PAGENAME}} Template
{{FULLPAGENAME}} Help:Template
Name of the current namespace {{NAMESPACE}} Help
Number of registered users {{NUMBEROFUSERS}} 2,576
Number of pages in a given category {{PAGESINCATEGORY:Content}} 32
Current software version {{CURRENTVERSION}} 1.41.0 (5498056)
Timestamp of last revision {{REVISIONTIMESTAMP}} 20190606221652

Nesting templates[edit source]

Templates can be used in other templates; this is called "nesting". This is often used to build templates that are made out of other templates, and allows for the use of "meta" templates that power other templates. For example, {{Metabox}} is a "meta" template used to build other templates like {{Note}} and {{Info}}. Nested templates can accept parameters, but those parameters must be explicitly specified by the template that is being used on the page. For example, if "Template:A" contained the text "The quick brown {{B|wally={{{animal}}} }}" and "Template:B" contained the text "{{{wally|fox}}}", then typing in {{A|wally=rabbit}} will not work properly, but {{A|animal=rabbit}} will.

You can use a template within itself (i.e. "Template:A" containing the text "The quick brown {{A}}", but it will stop after one iteration to prevent an infinite loop.

Template nesting is a useful and powerful feature, but it can quickly increase the complexity of templates, as well as make it harder to diagnose issues. Nevertheless, nesting templates makes it easier to write new templates and update existing ones.

Noinclude, includeonly, and onlyinclude[edit source]

By default, when a template is used, all of the text in it gets included in the target page. This can cause problems or unwanted behavior if the template page contains items that should normally only be seen on the template page itself, and not included with other pages. The following tags allow editors to control what gets shown when a template is used and what doesn't:

  • <noinclude> . . . </noinclude> will not include any of the contents placed inside of them onto target pages when the template is used. This is typically used to surround template documentation, which should normally only be seen on the template page and not used on other pages.
  • <includeonly> . . . </includeonly> will include any of the contents placed inside of them onto target pages when the template is used, but said content will not be shown on the template page.
  • <onlyinclude> . . . </onlyinclude> will include any of the contents placed inside of them onto target pages and on the template page itself, but anything not placed between these tags are not included onto target pages.
Wikitext What is rendered here (source page) What is transcluded there (destination page)
<noinclude> text1 </noinclude> text2 text1 text2 text2
<onlyinclude> text1 </onlyinclude> text2 text1 text2 text1
<includeonly> text1 </includeonly> text2 text2 text1 text2

Documentation[edit source]

A template's documentation explains what the template does and how to use it. Documentation is a crucial part of developing templates and you should generally endeavour to write documentation for your templates as much as possible. Although documentation is not technically required for the template to work, not including documentation can be discourteous to other editors, as they will need to look at the wikitext of the template in order to figure out how to use it.

Documentation can be included on the template page by using the {{Documentation}} template. This template should be surrounded by <noinclude></noinclude> tags so it doesn't get transcluded into other pages. Ideally, this should be placed at the very bottom of the template, below the last line of code. For example:

Foo. Bar. Foo. Bar.
<noinclude>{{Documentation}}</noinclude>

A template's documentation page is located at the /doc subpage of the template page. For example, the /doc subpage of "Template:A" would be "Template:A/doc". The {{Documentation}} template will automatically transclude the contents of the /doc subpage onto the main template page.

Categorizing templates[edit source]

Templates should be categorized appropriately so other editors can easily find them. They should ideally be categorized in one of the sub-categories of the main template category. Categories added to a template should be located on its documentation subpage, wrapped in <includeonly> . . . </includeonly> tags, and not placed on the main template page. Placing categories on the documentation page allows them to be edited by non-administrators if the template is protected from editing, while the <includeonly> . . . </includeonly> tags prevent the documentation subpage itself from being categorized. Because the {{Documentation}} template is located between <noinclude> . . . </noinclude> tags, the categories will be added to the template page but not on the pages the template is used on.

Categorizing pages using templates[edit source]

Templates can be configured to add pages to categories. This is often done for maintenance or tracking categories. When doing so, it is best to surround the categories with <includeonly> . . . </includeonly> tags to keep the template itself from being categorized. For example, a template can add a page to a maintenance category if it is being used incorrectly.

Categories added by a template will appear on pages like normal, but the categories will not appear in the wikitext of the page, which may confuse new editors. If the category added by the template is incorrect, and there are multiple templates in use on a page, it may take more experienced editors some time to be able to find the template adding the category. Note that the HotCat script will not be able to modify categories added to a page via templates.

Redirects[edit source]

Template redirects will work properly, and will point to the destination page of the redirect. For example, if "Template:A" was redirected to "Template:Apple", typing {{A}} on a page will have the same effect as typing {{Apple}}. This works for parameters and for substituted templates as well.

Template limits[edit source]

Main article: Help:Template limits

When templates are expanded and rendered in HTML for viewing in your browser, they use up resources on the servers. To prevent excessively long and complex pages that take a long time to load, and to prevent denial-of-service attacks caused by the excessive use of complex templates, the MediaWiki software that powers The Sims Wiki is configured to stop expanding templates after the page they are used on exceeds certain pre-set limits. Once these limits are reached, any additional templates used on the page will not be expanded and will display incorrectly.

You can view the limits—and how far the current page has gone to reaching those limits—by doing one of the following:

  1. Edit the page using the source editor, then preview the page. The template limits will be shown at the bottom of the page under Parser profiling data (help) :.
  2. Right-click on the page and select your browser's "View Source" option to view the HTML source of the page. The template limits and their current values will be shown under an HTML comment titled "NewPP limit report". For example:
<!-- 
NewPP limit report
CPU time usage: 0.196 seconds
Real time usage: 0.284 seconds
Preprocessor visited node count: 558/1000000
Preprocessor generated node count: 0/1500000
Post‐expand include size: 51749/2097152 bytes
Template argument size: 121/2097152 bytes
Highest expansion depth: 9/40
Expensive parser function count: 6/500
Unstrip recursion depth: 0/20
Unstrip post‐expand size: 3750/5000000 bytes
Number of Wikibase entities loaded: 0/400
Lua time usage: 0.080/10.000 seconds
Lua memory usage: 2.12 MB/50 MB
-->

In general, the higher the numbers, the longer it takes for the page to load, and the more complex the page is considered to be. Some level of complexity is to be expected on pages that use complex templates, but when creating templates it is often useful to keep speed and performance in mind. For example, consider keeping templates short and efficient, and avoid inserting redundant code. Editors can also help with these template limits by avoiding the excessive use of complex templates and consider using fewer templates, if possible. For example, typing <references /> by hand is better for performance than using the {{Reflist}} template.

Lua-based templates[edit source]

Main article: Help:Lua

A growing number of templates on The Sims Wiki are being written in Lua rather than wikitext. Lua is a programming language that is designed to be simple to use and learn. This functionality is provided by the Scribunto extension.

Lua code is stored in the module namespace and not the template namespace. Templates will call these modules using the {{#invoke:}} parser function. For example, Module:Bananas can be used in a template by typing {{#invoke:Bananas}} on a template.

See also[edit source]