Help:Templates: Difference between revisions

From FlightGear wiki
Jump to navigation Jump to search
(include and noinclude tags + example. The example broke the page in so many ways before I figured out how to fix it. Can you say un-*pre*-dictable?)
m (→‎To include or not include: Some last fixes)
Line 106: Line 106:
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 <tt><nowiki><noinclude></nowiki></tt> and <tt><nowiki><includeonly></nowiki></tt> tags.
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 <tt><nowiki><noinclude></nowiki></tt> and <tt><nowiki><includeonly></nowiki></tt> 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 also that there both <tt><nowiki><includeonly></nowiki></tt> and <tt><nowiki><noinclude></nowiki></tt> starts right behind the text of the template, as a having a line break there would cause a line break when the template is used.  Here is the full ''Template:Hello'':
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 <tt><nowiki><includeonly></nowiki></tt> and <tt><nowiki><noinclude></nowiki></tt> 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'':


  <nowiki>Hello, {{{1|}}}{{{2|stranger}}}!<includeonly>[[Category:Pages that says hello]]</includeonly><noinclude>
  <nowiki>Hello, {{{1|}}}{{{2|stranger}}}!<includeonly>[[Category:Pages that says hello]]</includeonly><noinclude>
Line 117: Line 117:


== Usage ==
== Usage ==
  &lt;nowiki&gt;{{&lt;/nowiki&gt;'''hello'''&lt;nowiki&gt;|&lt;/nowiki&gt;''title''&lt;nowiki&gt;|&lt;/nowiki&gt;''name''&lt;nowiki&gt;}}&lt;/nowiki&gt;&lt;nowiki&gt;
  &lt;nowiki&gt;{{&lt;/nowiki&gt;'''hello'''&lt;nowiki&gt;|&lt;/nowiki&gt;''title''&lt;nowiki&gt;|&lt;/nowiki&gt;''name''&lt;nowiki&gt;}}&lt;/nowiki&gt;


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

Revision as of 18:33, 11 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 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.
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

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=March 2024.

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. 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 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=March 2024}}

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.

Editing templates

Creating new templates

Consider giving the template a meaningful name. 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, but proper documentation will then be even more important. Do note that parameter names are case sensitive except for the first character.

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.

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 how you want it to do that, 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 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!

You might wonder what that vertical stroke and the text following, {{{1|}}}{{{2|stranger}}}, in Template:Hello does. Some of you might 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:

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>

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:

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 at first look like templates except for that they mostly are all uppercase. 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. A good hint is that well placed empty html comments can make the code way more readable. 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
If parser functions can do magic for the functionality of a template CSS can do magic for its appearance.

External links