Learning patterns/Doing more, with templates: A tutorial for Wikimedia project creators

A learning pattern forwiki design

Learning Pattern Library

Doing more, with templates: A tutorial for Wikimedia project creators

problemLearning to use and develop MediaWiki templates is harder than necessary.

solutionProvide a self-contained tutorial that gets the beginner quickly up to speed, by focusing on fundamentals.

creator• Greg at Higher Math Help

created on18 March, 2022

status:DRAFT

What problem does this solve?

Templates are a very powerful feature of the MediaWiki software used for Wikipedia. We can use templates to create reusable and customizable content, to save time, and to standardize formatting. With templates, we can change a navigation menu appearing across many pages by editing a single file. We can even use templates to perform calculations or to categorize pages automatically.

Anyone can make custom templates that serve their own purposes, using only a few basic ideas. However, learning these ideas is harder than it needs to be, since help pages tend to be encyclopedic rather than pedagogical.

What is the solution?

The solution is to provide a self-contained tutorial that gets the beginner quickly up to speed, by focusing on fundamentals. This tutorial is also designed to be actively worked through. It proceeds from using templates to creating them, and it develops the key concepts with step-by-step examples and exercises. Guidance that may be skimmed is placed into separate "Tips" sections. In case the fundamentals are not enough to solve a specific problem, this tutorial also provides guidance on how to learn more.

Things to consider

Let’s start with some terminology that will help us understand the scope of this tutorial.

Terminology

wiki

Just as word processing software is a type of software, a wiki is a type of website. Specifically, A wiki is a type of website whose contents can be edited from the web browser, and which keeps a version history for each editable page. Wikis are often, but not always, editable by any visitor to the site.

MediaWiki

Just as Google Docs is an example of word processing software, MediaWiki is an example of wiki software. MediaWiki is the free and open-source wiki software that underlies Wikipedia, its sister projects, and thousands of other public and private wikis.

Wikimedia

Just as Google Docs runs on servers managed by the for-profit Google, Wikipedia runs on servers managed by the nonprofit Wikimedia Foundation. (By itself, “Wikimedia” refers to the general knowledge movement supported by the Wikimedia Foundation.)

While Wikimedia projects such as Wikipedia and its sister projects are our focus, this tutorial generally applies to any wiki running on MediaWiki software. For example, there is a video embedded in this tutorial that talks specifically about Wikipedia, but it applies to other wikis as well.

When to use

This tutorial originated as a set of internal notes to assist with the creation of templates for Eventmath, a Wikiversity learning project. If you want to use or create MediaWiki templates for your own project, then this tutorial is for you!

In order to work through this tutorial, it will help if you have an account. If you have a Wikipedia account, for example, then that will allow you to work on the other Wikimedia projects, as well.

Since templates use the same markup language as regular pages, the skills assumed in this tutorial are covered in the basic introduction to editing with wiki markup. You only need to know how to find the “Edit source” tab on a MediaWiki page, change some text, and publish your changes. The help menu inside the source editor contains a list of the markup rules you need.

Terminology

The markup language used to create MediaWiki pages and templates is called wikitext. (It’s also known as wiki markup or wikicode.)

Template examples

Okay, let’s begin! We’ll start by glancing through some examples. Each of these is created with a template.

A support message

 Support

A keyboard combination

⇧ Shift+\

A message box

A scoring rubric

Scoring rubric	Score
(A) Impact potential Does it have the potential to increase gender diversity in Wikimedia projects, either in terms of content, contributors, or both? Does it have the potential for online impact? Can it be sustained, scaled, or adapted elsewhere after the grant ends?
(B) Community engagement Does it have a specific target community and plan to engage it often? Does it have community support?
(C) Ability to execute Can the scope be accomplished in the proposed timeframe? Is the budget realistic/efficient ? Do the participants have the necessary skills/experience?
(D) Measures of success Are there both quantitative and qualitative measures of success? Are they realistic? Can they be measured?
Additional comments from the Committee:

An infobox

Bombay Explosion

Smoke billowing out of Harbour
Date	14 April 1944
Time	16:15 IST (10:45 UTC)
Location	Victoria Dock, Bombay, British India
Website	example.com

A navigation box

A tabbed interface

Current page

Project

Project talk

Olympics Project

A user badge

This user is @HigherMathNotes on X.

A customizable image

8
7
6
5
4
3
2
1
	a	b	c	d	e	f	g	h

A reply

@Example: Message to user... ~~~~

This Reply to template triggers a notification to the user being replied to.

A citation

"Eventmath: An Open-access, Community-built Repository Pairing Current Events and Math Lessons". Twitter. 2021-07-28. 

A user bio

===Name===
* ''Twitter:'' [URL-of-twitter-profile @Twitter-username]
* ''User:'' [[User:Wikiversity-username|Wikiversity-username]]
* ''Bio:'' Your bio!

This template is designed to be loaded into the source editor so that it can be filled in by the user.

Learning by doing

Wouldn’t it be great if you could practice as you read this tutorial? You can! You just need a blank page where you can play around. The user sandbox is one such page.

Our first sandbox

Let’s take a few seconds to set up our first sandbox.

1. Log in to your wiki, from any page. You might see a link in the top right of the page that says Sandbox.

   

2. If you don't see a link to a sandbox already, create one by following these steps:
   1. Look for your username in the top right of the page, and click that to reach your user page.
   2. Click the “Edit source” tab, and create a link to a subpage called “sandbox” by typing [[/sandbox]]. Note that we’ve chosen to use lowercase letters in the name sandbox. Although it’s not necessary in every context, using consistent casing in code prevents errors.
   3. Publish your changes.
3. By default, the link to your user sandbox will be red if you haven't created the sandbox yet. To create it, follow these steps:
   1. Click the link to the sandbox (either the one you found, or the one you made).
   2. Add anything to the page (e.g. “My sandbox”).
   3. Publish your changes.

If these instructions are unclear, you can check out the two-minute video walkthrough below. (This video is from the days when manual creation was the only option.)

Video tutorial on creating a user page sandbox

Our second sandbox

Now let’s set up a second sandbox, which we’ll use for testing. You can do this by following steps 2 and 3 above, but this time add [[/sandbox2]] anywhere on your user page.

If you ever need additional sandboxes, you can create more by adding [[/sandbox3]], [[/sandbox4]], etc. (Although sandbox3, sandbox4, etc. work fine as page names, you can choose any names you like.) Each sandbox can be a place to try out different kinds of edits, to test templates, or to keep notes or drafts.

Using templates

Now that our user sandboxes are set up, let’s create a simple thank-you template that produces the following text:

Thank you so much! You’ve been a huge help. I’m looking forward to collaborating more in the future!

To do this, follow the steps below:

1. Delete any text currently in the main sandbox.
2. Type Thank you so much! You’ve been a huge help. I’m looking forward to collaborating more in the future!.
3. Publish these changes.

We’ll see how to use this template in the next section.

Concepts

Calling templates

Let’s use our thank-you template in the second sandbox:

1. In the source editor for the second sandbox, type {{User:username/sandbox}}, but replace “username” with your own username.
2. Publish your changes.

You should now see the thank-you message appear on your second sandbox.

Congratulations! You’ve created and used your first template. (If you can’t get this test to work as expected, try posting on the Discussion tab of this tutorial for help.) Now, if you were to use this template on a lot of pages, you could change them all at once by changing the original thank-you message. Neat!

Terminology: Calling a template

Whenever we type a template name inside of double braces, like {{User:username/sandbox}}, we say that we are calling the template.

If you’ve done any computer programming, this may remind you of calling a function. Calling a template works in the same way: it refers to code that’s already been written, and in this case, it returns that code as output.

Syntax: Calling a template

We call a template by typing {{My template}}, where My template is the name of the template. Note that this is the same way we link to a wiki page, except that we use double braces {{}} instead of double brackets [[]].

Note: Instead of My template, the full name of our thank-you template is User:username/sandbox. Later, we’ll see that a simple name like My template is perfectly valid, but {{My template}} refers to a template that’s saved in a different place.

Now let’s adapt our thank-you template so that it can address a specific person:

1. Edit the template source so that it reads exactly as follows (yes, those are triple braces!):

   Thank you so much, {{{friend}}}! You’ve been a huge help. I’m looking forward to collaborating more in the future!

2. Publish the changes.

We can test the adapted template by using it to thank someone named Kind Person:

1. In the “Edit source” tab for your second sandbox, delete what you had previously.
2. Type {{User:username/sandbox|friend=Kind Person}}. The vertical bar between sandbox and Kind Person is often called the pipe character, which can be produced by typing ⇧ Shift+\. Also, remember to replace “username” with your own username, since you saved the template as a subpage of your own user page.
3. Publish the changes.

You should now see the following thank you message:

Thank you so much, Kind Person! You’ve been a huge help. I’m looking forward to collaborating more in the future!

Hooray! You’ve created and used your first template parameter. Specifically, you used a parameter called friend in order to allow the template caller to customize the thank-you message with the name of the person to be thanked.

Terminology: Template parameter

A template parameter is a placeholder inside a template that gets filled with a custom value that's supplied by the user when calling the template.

If you’ve done any computer programming, this may remind you of a parameter in a function, procedure, or routine. A template parameter serves the same purpose: it’s a variable within a template that’s replaced with an input value when the template is called.

Syntax: Creating a named template parameter

To create a parameter called my parameter within the source of a template, type {{{my parameter}}}. (Note the use of triple braces, instead of the double braces that we use to call a whole template.) You can type {{{my parameter}}} in multiple places throughout the template; in each place, it will be replaced with the value that the user supplies when calling the template.

Syntax: Calling a template with named parameter values

We can supply parameter values when calling a template by typing {{My template|my parameter=my value|my other parameter=my other value|...}}. Be sure to use the pipe character | as a separator.

To make this more readable, we can produce the same result by typing this on separate lines and adding spaces to align the equals signs (we can also add spaces before the parameter names, if we wish):

{{My template
| my parameter       = my value
| my other parameter = my other value
| ...
}}

Note that the parameters we’ve used are called named parameters. Since we’re specifying them by name, we don’t need to remember a particular order. In other words, we could swap the following lines:

| my parameter       = my value
| my other parameter = my other value

Named parameters are the only kind we need, but sometimes unnamed parameters are convenient. To see how these work, let’s tell the template not only who is being thanked, but also who is doing the thanking.

1. Edit the template source so that it includes a signature after two dashes, which is customary, and so that it uses the numbers 1 and 2 in place of parameter names:

   Thank you so much, {{{1}}}! You’ve been a huge help. I’m looking forward to collaborating more in the future! – {{{2}}}

2. Publish the changes.

As before, let’s use the template to thank someone named Kind Person, but this time we’ll sign it as Thankful Person.

1. In the “Edit source” tab for your second sandbox, delete what you had previously.
2. Type {{User:username/sandbox|Kind Person|Thankful Person}}. Remember to replace “username” with your own username.
3. Publish the changes.

You should now see the following thank you message:

Thank you so much, Kind Person! You’ve been a huge help. I’m looking forward to collaborating more in the future! – Thankful Person.

Cool! Notice how we did not need to provide name = value information to the template. We only needed to type the values. That’s because the first value Kind Person and the second value Thankful Person automatically replace {{{1}}} and {{{2}}}, respectively. Actually, since unnamed parameter values are distinguished by their position in the template call, we sometimes refer to unnamed parameters as positional parameters.

Syntax: Creating an unnamed (positional) template parameter

Everything about creating named parameters applies here, except that numbers are used in place of a parameter name like my parameter. So, to create a parameter that will be replaced with the first value supplied in a template call, type {{{1}}} in the source of the template; to create a parameter that will be replaced by the second value, type {{{2}}}; etc.

Syntax: Calling a template with unnamed parameter values

When a template uses unnamed parameters, we pass in parameter values value1, value2, … by typing {{My template|value1|value2|...}}. As with named parameters, we may also specify the values on separate lines, which is useful if the values are long:

{{My template
|value1
|value2
|...
}}

Exercise: A thank-you template with a list parameter

1. Create a thank-you template with parameters for the person being thanked, the reasons for saying thank you, and the person doing the thanking.
2. Call the template with a list of reasons for saying thank you.

Hint: You can create bullet points with asterisks, and you can supply an entire bulleted list as the value of a single parameter. We haven’t done an example like this, so you may need to guess a reasonable way to type this. Trying out features is what the sandbox is for!

Solution:

One way to solve this is to type the following into the source editor of your main sandbox:

Thank you so much, {{{person to thank}}}!

You’ve been a huge help:
{{{reasons}}}
I’m looking forward to collaborating more in the future!

– {{{person saying thanks}}}

To call the template, type something like the following into the source editor of your second sandbox, remembering to replace username with your own username:

{{User:username/sandbox
| person to thank = Kind Person
| reasons = 
* You fixed my typos.
* You answered my questions.
* You shared my ideas.
| person saying thanks = Thankful Person
}}

Including templates

There are two main ways to include a template in another page. Until now, we’ve only used one of them.

Concept: Transclusion (syntax, result, uses)

This is the method we’ve been using, as it’s the most common.

• Syntax: {{My template}}
• Result: When you save the page, the contents of the template appear in place of {{My template}} on the rendered page (the "Read" tab), but not in the source. The source will still contain only the wikitext {{My template}}, rather than the template contents.
• Uses: Suppose we reuse a template on many pages and decide later that it needs to appear differently on all those pages. With transclusion, we only need to change the template page, since the other pages will all pull their content from there.

Concept: Substitution (syntax, result, uses)

This method has a different effect, which can be useful in certain situations.

• Syntax: {{subst:My template}}
• Result: When you save the page, the contents of the template appear in place of {{subst:My template}} in both the rendered page and the source.
• Uses:
  • If we substitute a template into a page, then we can directly edit the source of the template from within that page. For example, the user bio template is designed to be substituted, since substituting the template enables editors to fill in the outline that it provides.
  • If we substitute a template into a page, then its contents and appearance will stay the same when the original template is changed. This is to be expected, since the reference {{subst:My template}} to the original template is eliminated upon saving. This is also helpful in the case of the user bio (a user will fill in the bio based on the current headings, not future headings).
  • Additional uses can be found on the Wikipedia help page on substitution, but we won’t have a need for those uses.

In case you find yourself reading other help articles, you may encounter a term that is frequently used in this context.

Terminology: Template expansion

When a template call like {{My template}} or {{subst:My template}} is replaced with the contents of the template (either in the rendered page or the source), we say that the template has been expanded. This is appropriate, since the small amount of code in the template call gets replaced with a larger amount of code.

Preloading templates

We’ve been assuming that you are doing all the editing yourself. If you’re developing a project that other editors will contribute to, you may want to make editing easier for them by providing pages that are partially filled in.

Concept: Preloading

It’s possible to ensure that when a user creates a new page for your project, the source editor will be filled with wikitext that you provide in advance (for example, this may include an outline that the editor will fill in). We say that such wikitext is preloaded into the editor.

We’ll learn a simple way to preload text later in this tutorial, during our discussion of extensions.

Tips

Syntax highlighting

To make wikitext easier to read, turn on syntax highlighting, if it’s not already enabled for you. To do this, just click the highlighter button () in the toolbar of the source editor. You can click it again to turn it off, if you prefer.

Typing template names

With passwords, if you accidentally use a lowercase letter in place of an uppercase letter, you typically won’t be able to log in. In other words, passwords are case sensitive. This is usually the case (pun intended) with code as well, so your safest bet is to match the casing of template names.

However, the first letter of template names is case insensitive, so if you see code like {{my template}} and also {{My template}}, rest assured these are calls to the same template.

There is a method to this madness! Wikilinks (a link from one wiki page to another) behave the same way: [[my link]] and [[My link]] point to the same page. Both template calls and wikilinks refer to a page by its title (a template name is nothing but the title of the page where the template is located). In general, page titles are case sensitive except for the first letter, according to the default configuration of MediaWiki software.

Typing parameter names and values

With parameters, it’s helpful to be aware of casing and spacing:

• Parameter names are fully case-sensitive (including the first letter). In addition to using lowercase and uppercase letters, you can include spaces, hyphens, and numbers: my parameter my-parameter, and my parameter-2 are all valid parameter names. You may also use camel case if you prefer, as in myParameter.
• In the case of named parameters, we can use extra spacing around parameter names and values to make wikitext easier to read. We illustrated this previously with an example:

  {{My template
  | my parameter       = my value
  | my other parameter = my other value
  | ...
  }}
  

  In this case, space at the beginning and ends of parameter names and values, including space that separates parameters onto different lines, is stripped away before the page is rendered.

• In the case of unnamed parameters, space is preserved, so if you see an extra space somewhere in your output, that may be why.

Finding templates

There are a variety of ways to find templates to use, or to adapt based on your needs. Let’s make sure you’re aware of some of them; if you bookmark this page, you can come back to it in case you forget anything. With each of these approaches, start by focusing on the wiki you’re working on, like Wikipedia or Wikiversity. If you don’t find anything, consider other wikis. MediaWiki templates can be copied between wikis, although as we’ll discuss, this may require extra work.

Note: Some of the approaches below refer to the advanced search interface. You can reach this interface by performing an empty wiki search: find the wiki search box at the top of any page and click the search button without entering any text.

• To browse templates and get a sense of what's available...
  • Option 1: Search for “category: templates” from the advanced search interface.
  • Option 2: Look for a template index on your wiki, such as the Wikipedia template index or this list of Wikipedia template examples.
• To locate the source of a template you find in use on a page, click "Edit source," and...
  • Option 1: Scroll down and click “Templates used on this page,” below the editor.
  • Option 2: Find the template call in the source; if it's {{My template}}, do a wiki search for Template:My template.
• To search for a template that displays a box with text inside (for example), try...
  • Option 1: Search for template: box, template: message box, etc. from the advanced search interface.
  • Option 2: Search for “Wikipedia box template,” “Wikipedia message box template,” etc. using a general web search provider.
• To find examples of how to use a particular template (in case the source is inscrutable or not well documented), try...
  • Option 1: Search for hastemplate: "My template", from the search box on any wiki page, to see a list of pages that include the template.
  • Option 2: Click "What links here" in the wiki sidebar (under "Tools") while you're on the template page, to see a list of pages into which the template is transcluded.

Creating templates

Concepts

Publishing templates

Previously, we created a thank-you template in the so-called “User” namespace. Consequently, we had to type out the sandbox’s full page name, including the User: prefix, when calling the template.

However, most templates are created in the “Template” namespace. This is done by creating a page with a name like “Template:My template.” We could call this template with the markup {{My template}}, since the Template: prefix is implied if none is specified.

Concept: Publishing a template

We can create templates like any other page:

1. Perform a wiki search for the page name of the page you want to create. Try this now, with the page name Template:My template. If no page with this name already exists, you should see a message like the following at the top of the search results:

   Create the page "Template:My template" on this wiki!

   Typically, the link will be red. That’s the default color for links to pages that have not yet been created.
2. Click the red link to create the page. You can try this now. (Don’t worry. You’ll be taken to a page editor, and the page won’t actually be created until you click “Publish” at the bottom of the editor.)

Note: There are other ways to create pages. One that is often recommended is to create a link to the page before it exists. That link will be red by default. Then you can proceed as above. This has the advantage of ensuring that the page you create will start out with at least one other page linking to it, providing context for the page and helping others to find it. However, templates are usually referenced with template calls in double braces {{}}, rather than wikilinks in double brackets [[]]. So, later in this tutorial, we’ll see how to create links to our templates by categorizing them, instead of manually linking to them.

Controlling inclusion

Documenting templates

Tips

Adapting templates

Naming templates

Categorizing templates

Adding features

Concepts

Parameters

Magic words

Extensions

Tips

Adding design elements

Concepts

HTML

CSS

Tips

Fixing mistakes

Concepts

Testing templates in general

Testing new templates

Testing existing templates

Tips

Documenting tests

Moving templates

Resolving common issues

Purging

Readability

Empty vs. undefined

Section headings

URLs as parameter values

Modules, gadgets, and widgets, oh my!

Is that all?

Glossary

Endorsements

See also

Related patterns

External links

References