EsportsWikis:Tutorial/Templates

From League of Legends at EsportsWikis
Jump to: navigation, search
Overview   Part 1   Part 2   Part 3   Templates   Tournament Templates   How to...   Writing Bios   Shortcuts    

Introduction

Templates are the bread and butter of our wiki, and you've seen them all over the place even if you don't realize it -- {{ci}}, {{team}}, {{TabsHeader}}, {{BlockBox}}, and scoreboards are all examples of templates. Actually, "template" is a bit of a misnomer - a better name for templates would be "functions." When you make a template, you are putting a bunch of wikitext that you don't want to type out over and over and over again, and making it easily insertable into any place in the wiki. Templates can also reference each other -- for example, {{TabsHeader}} references {{Tabs}}, which in turn references {{TabsTop}}. Templates can vary from very simple to extremely complex.

If you're familiar with programming and/or web design, you'll probably be able to figure out a lot of this on your own, but read over this page and bookmark the help page on parser functions to help you out with syntax anyway. And if you're not, then this page serves as a gentle introduction to templates and what they can do (hint: it's pretty much anything).

Recognizing Templates

How do you know when something is a template? Well, technically any page can be used as a template (more on that later). But in the vast majority of cases, a template will be hosted at a page with a URL like .../wiki/Template:[TemplateName]. When you're editing a page, you can tell that something is a template if it starts with {{. When the template is over, you will see the closure, }}.

After the {{, you will see a word or words, for example TabsHeader or SetPlayerVariables or Infobox Team. That word or words is the title of the template, and the same as the rest of the URL after Template: where the template code is located. If it's a simple template, that might be it. But usually there will be at least one variable defined. Let's look at the {{ci}} template again. If you write {{ci|Sona}}, you see  Sona. The |Sona tells the template what champion to use.

Let's look at another template: {{RosterSwapLine}}. {{RosterSwapLine}} is used on our roster changes tracking page to track rumors. Here's an example line of {{RosterSwapLine}}:

{{RosterSwapLine|date=Rumor|player=Chaox|team2=LMQ|pos2=AD|url=http://thinkpiece.gg/return-trash-talk-3/}}

Similar to our example above with {{ci}}, we have the name of the template at the beginning, but this time after the name comes several variables: |date=Rumor, |player=Chaox, etc. Each | separates between two variables. In theory, you can have any number of variables in a template.

However, there's another difference that you might notice. In {{ci}}, we just wrote {{ci|Sona}}, not {{ci|champ=Sona}}. That's because the champion in {{ci}} is an unnamed variable, whereas the variables in {{RosterSwapLine}} are all named variables.

Unnamed Variable Named Variable
Example: "Sona" in {{ci|Sona}} Example: "Chaox" in {{RosterSwapLine|...|player=Chaox|...}}
Must always be written in the exact same order, if there are multiple unnamed variables* Can be written in any order
Will usually be used only in templates with at most 2-3 variables Will usually be used only in templates with at least 2 variables
*You may, if you want, reorder the parameters if you tell the template the order that they're supposed to be in: e.g. instead of writing {{ci|Sona|Sona, Maven of the Strings}} we could instead write {{ci|2=Sona, Maven of the Strings|1=Sona}}. Both will yield  Sona, Maven of the Strings.

Using Templates

Now that we can recognize templates and their parts, how do we use them? Some templates, like {{ci}} will have extensive documentation that you can see when you navigate to their page (remember a template's URL is always .../wiki/Template:[TemplateName]). If you're not sure what to do, seeing if the template in question has documentation can be a great place to start. However, frequently we make templates that don't have documentation -- while this isn't the best practice, we make a lot of on-the-fly templates, and writing documentation for each one would be very time-consuming. So if there's no documentation, how do you figure out what a template does?

The best way is always going to be to look at an example of the template in action. If you're trying to use a template that you don't understand already, chances are that you're editing a page that includes other instances of that template. Most templates will have descriptive names for their variables, or at least you can look at the values that the variables have and figure out what you're supposed to put.

What if you can't find any instances of the template you need to use? Turns out, there's an easy way to look for them! Go to the template's page (Template:TemplateName). Then, find What Links Here under Tools in the sidebar and click it. You'll be taken to a page like this one, where you can see a list of pages that include the template in question. If it says "(transclusion)" after the link, then the template is used in that page. Click to the page that uses the template, go to Edit, and search for the template name within the page.

Still not sure? Let's look at the template code itself. Let's first use a relatively simple example: The code for the tabs used in this tutorial ({{TutorialTabs}}).

<includeonly>{{TabsHeader
|name1=Overview
|link1=EsportsWikis:Tutorial
|name2=Part 1
|link2=EsportsWikis:Tutorial/Part 1
|name3=Part 2
|link3=EsportsWikis:Tutorial/Part 2
|name4=Part 3
|link4=EsportsWikis:Tutorial/Part 3
|name5=Templates
|link5=EsportsWikis:Tutorial/Templates
|name6=Tournament Templates
|link6=EsportsWikis:Tutorial/PBS
|This={{{N}}}
}}</includeonly><noinclude>{{documentation}}</noinclude>

That looks pretty familiar - in fact, it's just the {{TabsHeader}} template with some other stuff added before and after it, and instead of |This=1 or something, it says |This={{{N}}}. In the source code for templates, {{{ }}} denotes that something will be a variable when you use the template in another page. There's four things that you can see between {{{ }}} tags, and they indicate what type of variable it is:

What you see What it means
{{{N}}}
The variable is named N, and so you would write:{{TutorialTabs|N=2}}.
{{{1}}}
The variable is unnamed, and so you would write {{TutorialTabs|2}} or {{TutorialTabs|1=2}}.
{{{N|2}}}
The variable is named N. If you just write {{TutorialTabs}}, the default value of 2 will be passed along to N.
{{{1|2}}}
The variable is unnamed. If you just write {{TutorialTabs}}, the default value of 2 will be passed along as the first parameter.
{{{N|}}}
The variable is named and optional. Not including it when you call the template will just result in that part of the template being omitted.*
{{{1|}}}
The variable is unnamed and optional. {{ci}}'s second variable is a good example of this.
*Technically, what you are doing here, is the same as above with the default value of 2; it's just that the default value is nothing.

Includeonly, Onlyinclude, and Noinclude

Let's go back to our {{TutorialTabs}} template, the template we looked at above. What's the deal with it saying <includeonly> at the start and then </includeonly><noinclude>{{documentation}}</noinclude> at the end? Here's what's going on.

Fundamentally, templates are no different from any other page in the wiki.

Having a sentence as a section heading is kind of weird, and the only reason I've done it here is that this is a really, really, really important concept. Just because a template is named Template:TemplateName doesn't mean that it's special in any way. When you call a template using {{templatename}}, the wiki assumes that you're looking for something in the Template namespace by default, but if you want you can call something in any namespace!

Remember back when we wrote "Hello, world!" on a page back in Task 1?

Input Output
{{User:RheingoldRiver/Tutorial_Task_1}}
Hello, world!!!

It works exactly the same as any other template, inserting code from one place to another.

So! Where do Includeonly, Onlyinclude, and Noinclude come in? Go look at a template called {{TeamsVsAlign}}. When you go to the page, you see some documentation about the code, but you don't actually see the code that comprises the template. Why not? What stops you from seeing it, and what stops the documentation from being inserted along with the rest of the template code whenever you use the template?

Transclusion

Transclusion is the inclusion of text from one page to another, accomplished by referencing the one page within the other. You can read about transclusion here. Using a template is the most common form of transclusion.

The meanings of <includeonly>, <onlyinclude>, and <noinclude> become clearer if we put them into sentences involving transclusion.

  • Include this code only when transcluding (and not when displaying normally).
  • Only include this part of the code when transcluding.
  • No include this code when transcluding.
What to do with the code between inclusion tags
Term When displaying When transcluding
<includeonly> Don't display it Display it
<onlyinclude> Display everything Display only the things within the tags
<noinclude> Display it Don't display it

Okay, let's get back to {{TeamsVsAlign}}. Here's its code:

<includeonly><div style="width:{{{width|300px}}};display:table;table-layout:fixed;"> 
	<div style="width:calc(50% - 10px);text-align:right;display: table-cell;"> {{team|{{{1|}}}|leftshortlinked}} </div>
	<div style="display:table-cell;width:20px;text-align:center"> vs </div> 
	<div style="width:calc(50% - 10px);display:table-cell;text-align:left;">  {{team|{{{2|}}}|rightshortlinked}} </div>
</div></includeonly><noinclude>{{documentation}}</noinclude>

So we have <includeonly>, and then the code that we want it to use, using two variables (unnamed, optional variables), and then a </includeonly>. So all of the code between those two tags is not displayed at Template:TeamsVsAlign but is displayed whenever the code is embedded.

Then after that, we have <noinclude>{{documentation}}</noinclude> -- so we're going to display the documentation at Template:TeamsVsAlign, but not when we use the template elsewhere. (What exactly is documentation? We'll go over that in a bit.)

Writing Templates

Templates can range from very simple (such as a template to create one row of tabs, like {{TutorialTabs}}, which is used for these pages) to much more complicated (such as {{RosterChangeLine}}, the template used to track roster swaps). We'll go over the basics here, and if you want to go more indepth, check out [Help:Templates MediaWiki's help page] and a more in-depth page. You can also contact Chris, our MediaWiki developer.

When should you create a template?

  • When you need to enter a very long piece of code many times with slightly different parameters each time
  • When you need to enter identical code in several places that's subject to change

A good example of the first case is {{TeamsVsAlign}}, which was created for the purpose of making the tables in the Worlds extended stats index for 2014 Worlds. While

<div style="width:{{{width|300px}}};display:table;table-layout:fixed;"> 
	<div style="width:calc(50% - 10px);text-align:right;display: table-cell;"> {{team|{{{1|}}}|leftshortlinked}} </div>
	<div style="display:table-cell;width:20px;text-align:center"> vs </div> 
	<div style="width:calc(50% - 10px);display:table-cell;text-align:left;">  {{team|{{{2|}}}|rightshortlinked}} </div> 
</div>

isn't a ton of code when used once, imagine that much code used for every single table.

The second case applies to pretty much all tournaments that have tabs at the top. There are always multiple pages for the coverage that we have, including Scoreboards, Picks and Bans, etc. And if there's a new tournament added in the series, or if we decide to add additional content, or any other change that needs to be made to the tabs, we don't want to have to change that on every single page -- so we make a template for it.

How to name a template

Please don't name your template anything like "Template1," "RheingoldRiver's Template for Worlds Tabs," or "Blueberry Spicehead." Give it a descriptive title that gives users a decent idea of what it's for. {{TeamsVsAlign}} is for aligning the "Vs" in a column of "Team 1 vs Team 2" for various teams. {{Season 3 NA LCS Tabs}} are tabs for the season 3 NA LCS events. {{TutorialTabs}} are tabs for the tutorial section. {{RosterChangeLine}} generates one row in the table of confirmed changes in our roster swap portal.

Conventions to follow:

  • If your template is primarily a TabsHeader with a variable as the number, make the name ___Tabs, where ___ is a reasonable name for the event or set of pages where the tabs will go.
  • If your template exists to make formatting easier but isn't necessarily going to be used only in the capacity for which you're making it, give it a name based on what it does not why you made it -- {{TeamsVsAlign}} rather than {{WorldsStatsTableEntry}} is a good example.
  • Multiple words should be combined with a capital at the start of each new entry -- {{TeamsVsAlign}}, not {{Teams_Vs_Align}} or {{teamsvsalign}}.
  • Try to make the name as short as possible without losing information. {{TeamsVsAlign}} may not give you a ton of information about what it does, but we don't want something like {{MakesACellHaveVsInTheCenterAndPutsTeamNamesOnEachSide}} -- generally a template name should probably be less than 20-25 characters.

Starting your Template

Start out with

<includeonly>
</includeonly><noinclude>{{Documentation}}</noinclude>

As discussed previously, your code will go in between the includeonly tags. Write the code that you want your template to have, keeping in mind what we went over with variables - you will probably want to have at least one variable in most cases.

Documentation

The last part is documentation. While it's not required, we request that you always document your templates, even if it's something as simple as "Tabs for the Editing Tutorial." (which is the documentation for {{TutorialTabs}}). Fortunately, making documentation is very easy, and you already did half of it when you wrote <noinclude>{{Documentation}}</noinclude> at the end of your code!

Simply go to .../wiki/Template:TemplateName/doc and write your documentation there, then press save. Then go back to .../wiki/Template:TemplateName and Refresh the page using the button in the dropdown menu next to the search bar. Done!

Your First Template

Let's write a template! Normally, you would put the template at /wiki/Template:[Template Name], but since we try to keep that namespace uncluttered, make it at /wiki/User:[Username]/My_First_Template. You'll make a couple versions of the template.

Version 1: No Variable

Make the following template:

<includeonly>Hello, World!</includeonly>

Now make a page called /wiki/User:[Username]/TemplateTest and write:

{{[Username]/My_First_Template}}

You should see "Hello, World!" written.

Version 2: Required Variable

You can choose to make separate templates at .../My_First_Template_1, etc, or not. For convenience of writing, we'll assume they're all in the same place. Write the following code:

<includeonly>My favorite champion is {{ci|{{{1}}}}}.</includeonly>

Now if you write {{My_First_Template|Sona}}, you will see "My favorite champion is  Sona."

Version 3: Optional Variable

Same thing, but instead of {{{1}}}, try {{{1|Sona}}}. Now you can write {{My_First_Template}} and it will show "My favorite champion is  Sona."

Version 4: #if

This is slightly more advanced, but still pretty basic. The help article on parser functions should help you understand how the #if works.

<includeonly>{{#if: {{{1|}}}
| My favorite champion is {{ci|{{{1}}}}}
| My favorite champion is {{ci|Sona}} }}</includeonly>

We've made the same thing as the optional variable above!

These are obviously extremely simple templates, and as you learn more you will make much more complicated ones, using #ifeq, #switch, and #expr, and other parser functions. It can be a lot of fun!