Hi fellow wiki editors!

To help newly registered users get more familiar with the wiki (and maybe older users too) there is now a {{Welcome to the wiki}} template. Have a look at it and feel free to add it to new users discussion pages (and perhaps your own).

I have tried to keep the template short, but meaningful. /Johan G

Difference between revisions of "Help:Templates"

From FlightGear wiki
Jump to: navigation, search
(Translating templates: I simplified this quite a bit by creating Template:LangSwitch)
(Completely rewritten the text. This is now a help page, though there is still a bit more to do)
Line 1: Line 1:
This page is meant to help you with the use of '''templates''' on the wiki.
+
'''Templates''' are pages that can contain complex pieces of wiki markup that can be reused on other pages with relative ease.
  
== Editing or creating templates ==
+
== Basics ==
Editing a template is almost 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". To do so open "wiki.flightgear.org/Template:what_you_always_wanted_to_know" (mind the underscores, that replace the spaces!).
+
=== What is a template ===
If you created a new template, you can embed it in any wiki article from now on by writing: <nowiki>{{what you always wanted to know}}</nowiki> (insert the template name here).
+
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 the 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.
 +
<pre>{{helloworld}}</pre>
 +
 
 +
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.
 +
 
 +
;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.
 +
 
 +
== Using templates ==
 +
=== Finding templates ===
 +
Most templates can be found in [[:Category:Templates]] and its subcategories.  There is also lists of some of the templates, see [[Help:List of messagebox templates]] and [[Help:List of infobox templates]].
 +
 
 +
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.
 +
 
 +
=== 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.  Named parameters are always used in key=value pairs, like for example <tt>month={{CURRENTMONTHNAME}} {{CURRENTYEAR}}</tt>.
 +
 
 +
In some of the template documentation the following convention is used to illustrate how parameters can be used:
 +
 
 +
<nowiki>{{</nowiki>'''template name'''<nowiki>|</nowiki>mandatory unnamed parameter<nowiki>|</nowiki>''optional unnamed parameter''<nowiki>|</nowiki>mandatory named parameter=<nowiki>|</nowiki>''optional named parameter=''<nowiki>}}</nowiki>
 +
 
 +
In most cases it is possible to use any kind of wiki markup in the parameters, for example wiki links.
 +
 
 +
=== Template documentation ===
 +
When you know what template you want to use, you might want to take a look at its documentation.  The documentation describes the purpose of the template and how to use it, as well as link to related templates.
 +
 
 +
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 a vertical stroke and some combinations of it, <tt>|</tt>, <tt>||</tt> and  <tt>|-</tt> and the equal sign <tt>=</tt>.  The usual workaround are to use the templates {{tl|!}}, {{tl|!!}}, {{tl|!-}} and {{tl|{{=}}}}.
 +
 
 +
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:
 +
 
 +
<nowiki>{{</nowiki>'''splitapart'''<nowiki>|</nowiki>''Discussion page section''<nowiki>|</nowiki>''date={{CURRENTMONTHNAME}} {{CURRENTYEAR}}''<nowiki>}}</nowiki>
 +
 
 +
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 how it they be used in different ways.
 +
 
 +
== Editing templates ==
 +
=== Creating new templates ===
 +
To create a new template, please use 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.
 +
 
 +
Two important things to add to your template is template documentation, preferably using {{tl|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 writing the documentation as this might help you figuring out the last few things in what you want the template to do, and then more or less use the documentation as reference when typing the template itself.
 +
 
 +
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.  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 existing 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 {{tl|informative template}}.
  
 
=== Translating templates ===
 
=== Translating templates ===
Line 12: Line 74:
 
It 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.
 
It 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.
  
== Small collection of various templates ==
+
== Advanced template editing ==
{{hatnote|For rather complete lists of infobox and messagebox templates, see [[Help:List of infobox templates]] and [[Help:List of messagebox templates]].}}
+
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:
 +
;Magic words:  Magic words at first look like templates except for that they mostly are all uppercase. One of them for example is <tt><nowiki>{{PAGENAME}}</nowiki></tt>, another one is <tt><nowiki>__NOTOC__</nowiki></tt>.
 +
;Parser functions:  Parser functions allow more or less regular programming with conditionals, switches, string formatting etc.  A good hint is that well placed empty html comments can make the code way more readable.
 +
;HTML:  It might seem a bit funny to mention it, but sometimes you forget that you can use html in a MediaWiki wiki
 +
;Cascading style sheets:  If parser functions can do magic for the functionality of a template CSS can do magic for its appearance.
  
{| border=1 cellpadding=3 style="border: 1px #AAAAAA solid; border-collapse: collapse;background:#ffffff;"
+
== External links ==
|- style="background:#eeeeee;"
+
* [http://www.mediawiki.org/wiki/Help:Templates MediaWiki template help]
! width="20%" | Tag
+
! width="70%" | Text that will be shown
+
! width="10%" | Place
+
|-
+
|<nowiki>{{abc}}</nowiki>
+
|{{abc}}
+
|Top
+
|-
+
|<nowiki>{{Boeing}}</nowiki>
+
|{{Boeing}}
+
|Bottom
+
|-
+
|<nowiki>{{Building}}</nowiki>
+
|{{Building}}
+
|Bottom
+
|-
+
|<nowiki>{{Main article|Link to article}}</nowiki>
+
|{{Main article|Link to article}}
+
|
+
|}
+
  
 
[[Category:Help]]
 
[[Category:Help]]

Revision as of 22:02, 9 November 2013

Templates are pages that can contain complex pieces of wiki markup that can be reused on other pages with relative ease.

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 the 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.
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.

Using templates

Finding templates

Most templates can be found in Category:Templates and its subcategories. There is also lists of some of the templates, see Help:List of messagebox templates and Help:List of infobox templates.

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.

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. Named parameters are always used in key=value pairs, like for example month=October 2019.

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.

Template documentation

When you know what template you want to use, you might want to take a look at its documentation. The documentation describes the purpose of the template and how to use it, as well as link to related templates.

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 a vertical stroke and some combinations of it, |, || and |- and the equal sign =. 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=October 2019}}

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 how it they be used in different ways.

Editing templates

Creating new templates

To create a new template, please use 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.

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 writing the documentation as this might help you figuring out the last few things in what you want the template to do, and then more or less use the documentation as reference when typing the template itself.

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. 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 existing 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}}.

Translating templates

Translating templates is different from translating normal articles. All translations are written within one and the same template. To do that one can use the {{LangSwitch}} template.

{{LangSwitch |en=English text |de=<German text> |fr=<French text> ...}}

It 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.

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:

Magic words
Magic words at first look like templates except for that they mostly are all uppercase. One of them for example is {{PAGENAME}}, another one is __NOTOC__.
Parser functions
Parser functions allow more or less regular programming with conditionals, switches, string formatting etc. A good hint is that well placed empty html comments can make the code way more readable.
HTML
It might seem a bit funny to mention it, but sometimes you forget that you can use html in a MediaWiki wiki
Cascading style sheets
If parser functions can do magic for the functionality of a template CSS can do magic for its appearance.

External links