Difference between revisions of "Help:Templates"

From FlightGear wiki
Jump to: navigation, search
(Update mw links to use Template:Mediawiki)
(+ Wiki help navbar template; + Navigation templates)
 
Line 1: Line 1:
 +
{{Wiki help navbar}}
 +
 
'''Templates''' are pages that can contain complex pieces of wiki markup that can be reused on other pages with relative ease.  On this help page we will go through what a template is, how to find them and use them as well as editing existing and creating new templates.  Finally we will have a quick look on some of the things that can be used in more advanced templates.
 
'''Templates''' are pages that can contain complex pieces of wiki markup that can be reused on other pages with relative ease.  On this help page we will go through what a template is, how to find them and use them as well as editing existing and creating new templates.  Finally we will have a quick look on some of the things that can be used in more advanced templates.
  
Line 19: Line 21:
  
 
;Infobox templates:  Infobox templates are nearly always found at the top right of pages.  The are literally a box of information on a subject, often about the subject of the page.
 
;Infobox templates:  Infobox templates are nearly always found at the top right of pages.  The are literally a box of information on a subject, often about the subject of the page.
 +
 +
;Navigation templates: Navigation templates are usually found at the top right or bottom of a page.  They are meant to help the reader navigate between pages on a similar context, for example a series of articles or articles about FlightGear aricraft by the same manufacturer.
  
 
;Maintenace templates:  Maintenance templates are nearly without exception messagebox templates.  Their purpose is to aid the maintenance of the wiki and to point out things that need to be improved.
 
;Maintenace templates:  Maintenance templates are nearly without exception messagebox templates.  Their purpose is to aid the maintenance of the wiki and to point out things that need to be improved.

Latest revision as of 07:59, 3 June 2018


Templates are pages that can contain complex pieces of wiki markup that can be reused on other pages with relative ease. On this help page we will go through what a template is, how to find them and use them as well as editing existing and creating new templates. Finally we will have a quick look on some of the things that can be used in more advanced templates.

Basics

What is a template?

In simple terms you are adding another page, or rather contents from it, into the page you are editing when you use a template. This is called transclusion. While the wiki has a special template namespace, indicated by a preceding Template: in the page title, any page can be used as a template.

If a template for example is named Template:Helloworld and contains:

Hello World!

Typing the following on a page would copy that content to the page you are editing. Note that the first character is not case sensitive.

{{helloworld}}

However, the templates can in addition to MediaWiki, html and style sheet markup also use a wide range of special functions to do a lot, lot more.

Different types of templates

There are several types of templates, some of the more visible are the messagebox templates, infobox templates and navigation box templates, but there are also many other kinds of templates. The following is just some few of the different kinds of templates:

Messagebox templates
Messagebox templates are often found on the top of pages and sometimes on the top of sections. In rare cases they can be found in the text. Their purpose is to give the reader or potential editors information.
Infobox templates
Infobox templates are nearly always found at the top right of pages. The are literally a box of information on a subject, often about the subject of the page.
Navigation templates
Navigation templates are usually found at the top right or bottom of a page. They are meant to help the reader navigate between pages on a similar context, for example a series of articles or articles about FlightGear aricraft by the same manufacturer.
Maintenace templates
Maintenance templates are nearly without exception messagebox templates. Their purpose is to aid the maintenance of the wiki and to point out things that need to be improved.
Utility templates
Utility templates are often small, but very useful templates.
Inline templates
Templates that can be used within sentences and flowing text.

Using templates

Finding templates

There are several ways to find a template to use:

Using categories
Most templates can be found in Category:Templates and its subcategories.
Using lists of templates
There is also lists of some of the templates, see Help:Gallery of messagebox templates and Help:Gallery of infobox templates.
Finding templates through a page they are used within
Another way to find templates is when you find a page using templates you are interested in using. If you open that page for editing you will on the very bottom of the page find a list of the templates used by that page and the templates those templates are using.
Finding templates similar to another one
Links to similar templates can often be found at the bottom of a templates documentation.
Searching for contents of a template
As a last resort you can search for using possible contents of a template, typing "Template:<whatever>" in the search box. Instead of going straight to the page as you would do if you would knew its name, you will get to a page of search results with pages that might contain the template you are looking for.

Template parameters

Most templates take arguments, called parameters. Some templates do not. Some parameters may be optional, some mandatory. Mandatory parameters must always be used, while optional parameters doesn't have to. There are also unnamed and named parameters. Unnamed parameters are sometimes called numbered parameters as they have to be used in a certain order and ar numbered within the template source. Named parameters are always used in key-value pairs, like for example month=September 2018.

In some of the template documentation the following convention is used to illustrate how parameters can be used:

{{template name|mandatory unnamed parameter|optional unnamed parameter |mandatory named parameter= |optional named parameter=}}

In most cases it is possible to use any kind of wiki markup in the parameters, for example wiki links.

As said above the unnamed parameters must be used in a certain order, though they can if not mandatory be left empty. Take for example the following template:

{{template|parameter 1|parameter 2|parameter 3|parameter 4|}}

Usually the most commonly used and/or mandatory parameters are the first one or ones, but if we just as an example would be to use only the last two parameters we would have to do like below:

{{template|||parameter 3|parameter 4}}

Template documentation

When you know what template you want to use, you are recommended take a look at its documentation, unless you have already done that earlier. You will find the documentation on the template's page. The documentation describes the purpose of the template and how to use it, as well as link to related templates. Unfortunately not all templates are documented.

Many templates have a Known issues section in the template documentation. Some templates have innate peculiarities that can not be fixed, but can be worked around. One of the more common issues is that a few characters that are used to either build tables or are used within templates will break a template, those characters are the equal sign = and a vertical stroke and some combinations of it, |, || and |-. The usual workaround are to use the templates {{=}}, {{!}}, {{!!}} and {{!-}}.

The template documentation contains a list of the parameters the template uses that can be copied and pasted to the page you are editing, sometimes even with some of the parameters filled in, like for example this template:

{{splitapart|Discussion page section |date=September 2018}}

In the template documentation there is also a list of the parameters and how they are supposed to be used and there are often examples to illustrate the different ways the parameters can be used.

Creating new templates

Choosing a good name

Consider giving the template a meaningful name. Usually one would try to only have the initial character upper case. If you are mimicking a template on another wiki, using its name might be a good idea. If the template will be used very often it might actually be a good idea to use a very short name or an abbreviation, but proper categorisation and documentation will then be even more important. Do note that parameter names are case sensitive except for the first character.

Search first

To create a new template, please start by using the search function. This way you will find if there already is a template with that name or if there is one with a very similar name. If there is no template with that name you will be presented with the option to create that page. Click on the red link to open up a edit window.

Things to include

Two important things to add to your template is template documentation, preferably using {{informative template}} and if possible to put the template in a more fitting category than Category:Templates.

Unless it is a very simple template it can be a good thing to start by writing the documentation as this might help you figuring out the last few things in what you want the template to do and how you want it to do that, and then more or less use the documentation as reference when typing the template itself.

Preview often

Do remember that you can, and should use the preview button now and then, or at least one before saving, in order to catch any errors before saving. One way of debugging a template is to add obvious clues as to where in a template something got wrong, for example 1?, 2?... This can be really helpful in some cases, though in other cases it will be obvious. Some common mistakes are the same ones as on article pages: Missing end markers in tables and missing end tags or end tags with missing slashes.

While the template always can be fixed if there are errors it is better to have an extra preview than an extra edit. Do note that the template will be lost if you do not save it.

Editing templates

Editing a template is often as easy as editing a normal wiki page. Lets say you want to edit a template with the name what you always wanted to know. Either search for the template using the template namespace like Template:What you always wanted to know or click on a link to get you there.

If the template code is very complex, it might be an idea to resist tampering with it, even though the edits can easily be undone.

Always try to add documentation to templates missing that, preferably using {{informative template}}.

Passing unnamed parameters

Passing parameters to templates make them a lot more useful. Unnamed parameters can be used in the order they are passed, in essence {{{1}}}, {{{2}}} etc. Consider the following template, Template:Hello:

Hello, {{{1|}}}{{{2|stranger}}}!

Its usage:

{{hello|title|name}}

And an example:

{{hello|Dr.|Falken}}

Hello, Dr. Falken!

Default values

You might wonder what that vertical stroke and the text following, {{{1|}}}{{{2|stranger}}}, in Template:Hello does. Most of you will already have guessed that they are default values. Having at least an empty default value is a good practice, as templates otherwise will break when passed an empty parameter. Here is what happens when the above template is used without parameters:

{{hello}}

Hello, stranger!

And here is what would happen if it would be used without parameters and did not have default values:

Hello, {{{1}}}{{{2}}}!

Passing named parameters

While using a template with named parameters can be a bit more of typing, they are not that much extra typing when editing a template. They are however practical some other ways, they can be passed to a template in any order and, more important, they are named (as in not numbered). That last thing makes them immensely more useful in complex templates.

Using them in a template are not that different than unnamed parameters. Using the above template, but with named parameters, we could instead type:

Hello, {{{title|}}}{{{name|stranger}}}!

Its usage:

{{hello |title= |name=}}

And an example:

{{hello |title=Dr. |name=Falken}}

Hello, Dr. Falken!

To include or not include

Sometimes you have content in a template that you do not want to be transcluded or that you want to have transcluded but not included in the template. Consider for example the template documentation, of course you would not want it to be on every page the template is used on, also, sometimes you want a template to add a category to the page it is used on, but not to the template itself. This can be done using the <noinclude> and <includeonly> tags.

To go back to the Template:Hello template, the below example shows how Category:Pages that says hello is added to the page that uses the template but not to the template and how the documentation and Category:Hello templates is added to the template, but not the page it will be used on. Note that both the <includeonly> and <noinclude> tags are right behind the text of the template, as a having a line break would cause a line break when the template is used.

Here is the full Template:Hello. Do not worry about typing all that text, {{informative template}} is one of the templates with pre-filled examples you can copy and paste into the template you are editing.

Hello, {{{1|}}}{{{2|stranger}}}!<includeonly>[[Category:Pages that says hello]]</includeonly><noinclude>
{{Informative template|1=
__NOTOC__
== Goal ==
This template can be used to show a friendly hello.

Adding this template to a page will automatically add that page to [[:Category:Pages that says hello]].

== Usage ==
 <nowiki>{{</nowiki>'''hello'''<nowiki>|</nowiki>''title''<nowiki>|</nowiki>''name''<nowiki>}}</nowiki>

;parameter:  Optional title, for example "<tt>Dr.</tt>"

;parameter:  Optional name, defaults to "<tt>stranger</tt>"

== Examples ==
 <pre>{{hello|Dr.|Falken}}</pre>
Hello, Dr. Falken!

 <pre>{{hello}}</pre>
Hello, stranger!

}}

[[Category:Hello templates]]
</noinclude>

Category suppression

Sometimes it is helpful if a template suppresses categorisation and only categorizes some of the pages it is put on. There is a few templates that can be used for that in Category:Namespace templates. Most of them uses the namespace of the page the template is put on. For example Help talk:Templates is in the Help talk namespace.

One of those templates is {{main other}}:

{{main other|text if main|text if other |demospace=}}

If the template is put on a page in the main namespace, the the namespace that articles are in, text if main text is used. Otherwise text if other is used. Both can be overridden if demospace is set as demospace = other when in the main namespace and demospace = main when in any other.

If a category link is used in text if main like below the page will only be categorized if the template is put in the main namespace. Note that all the parameters are optional.

...
}}

{{main other|[[Category:Hello templates]]}}
</noinclude>

Apart from demospace some templates will have a nocat parameter that when not empty or set as nocat = yes will suppress categorisation altogether.

Translating templates

Templates are translated in a different way than normal articles. Instead of creating another page for each translation, all translations are written within one template. To do that one can use the {{LangSwitch}} template, for example like below.

[http://{{LangSwitch
| en =  <!-- English -->
en
| de =  <!-- German -->
de
| fr =  <!-- French -->
fr
}}.wikipedia.org Wikipedia]
{{LangSwitch
| en =  <!-- English -->
{{ The template with English contents }}
| de =  <!-- German -->
{{ The template with German contents }}
| fr =  <!-- French -->
{{ The template with French contents }}
}}
Note  Many templates use tables and have to start from the beginning of the line, like in the above example.
Note  Inserting blank lines or spaces will usually cause unintended changes to the way the template are rendered.

The {{LangSwitch}} template uses the two letter language code present in all but the English page titles. If none of the languages that have been translated to is found, a template have not yet been translated to that language and the English text will be used instead, provided it is available.

When checking out that the language versions render as they should you can add a lang parameter to the template for debugging purposes. Remember to remove it before saving or the template will only be showed in that language. The below example would show the French (fr) version of the template:

{{LangSwitch
...
| lang = fr }}

Advanced template editing

The templates can contain some very advanced and often complex code, but even easier code can do great things to make life easier for you as an editor using it later.

While this page will not go into details, there is a few secrets to more advanced templates:

Tables
Wiki tables are tricky to understand, but can do a lot for any kind of box template and small layouts.
Magic words
Magic words are mostly all uppercase and many of them at first look like templates. Some of them are for example {{CURRENTMONTHNAME}} and __NOTOC__.
Parser functions
Parser functions allow more or less regular programming with conditionals, switches, string formatting etc. One of them is #if, {{#if: string | passed if non-empty | passed if empty }}.
HTML
It might seem a bit funny to mention it, but sometimes you forget that you can use (some) html tags in a MediaWiki wiki.
Cascading style sheets
Like magic words and parser functions can do magic for the functionality of a template CSS can do magic for its appearance.

A good hint on getting more readable template source is that well placed HTML comments (<!-- Comment -->) will help a lot.

External links

Advanced template help