Help:Templates: Difference between revisions
| Line 147: | Line 147: | ||
|} | |} | ||
==Text Paragraphs== | ==Text Paragraphs== | ||
Revision as of 15:06, 26 December 2012
 | This article is a fledgling. Help BoyWiki grow by expanding it |
Templates are pages shown in Portal:Template index. This means any page whose name begins with "Template:", such as "Template:Documentation", can be used as a template. The content of a template can be added to a page by typing {{templatename}} while editing the page. When the page is later viewed, {{templatename}} is replaced by the content of the page "Template:templatename". If the page "Template:templatename" is later altered, all the pages with {{templatename}} in them will change automatically.
Amongst other things, templates are used to add recurring messages to pages in a consistent way, to add boilerplate such as template {{stub}} which indicates that the article is a fledgling.
When a template is automatically expanded and appears on a page, it is said to be "transcluded".
Templates are documented (or should be) at their pages. See Help:Template Documentation
General
Most templates are pages in Portal:Template index
Templates can contain any desired Wikitext, including calls to other templates. They have some limited programming capacities: customizable values (called parameters), calculation and branchings (using parser functions), and access to wiki-specific variables (magic words), such as dates, times, and page names. They may also contain tags which define which parts of the wikitext are to be included when the template is transcluded or substituted. This means that the appearance of the template page itself need not be the same as that of the transcluded content (for example, it can contain documentation, categories, etc. for the template).
How to do it: To transclude a template to an article or page, type {{template name}} in the wikitext at the place where the template is to appear. The prefix "Template:" need not be included, and an initial capital is not necessary.
Note: Attempting to transclude a template that does not exist produces a red link, just like linking to any other nonexistent page. Following the link allows one to create that particular template.
Also see: Help:Templates for beginners
- TEMPLATES are just blocks of saved text that have been given names. Some are ordinary text paragraphs and some contain wikitext to make headings, indents, tables, and the like. In a simple case, by typing a template's name in the work, an entire block of text is added to the page with all of its formats and other parts, just as if it had been typed by the user. This behavior can be repeated at any point that the user wants, and almost any work that is found on a wiki page could be placed within a template to do this. The main effort as you might suppose, lies in its initial design.
- NAMES of templates are assigned when they are first saved. The name must be unique, and it is used when a template is called for use. Sometimes other text is also used along with the name; it can include any options and parameters.
- OPTIONS allow the user to vary the template's usual behavior.. The usual behavior suits most situations but the designer builds-in ways of changing things just in case. Option values are usually limited to a short list so these are described in a template's documentation. For example, option values for an option called align might include only left, right, or center, and no others. Templates do not always need options, since their default behavior is often enough.
- DEFAULTS are the values used by a template when the user did not say. Default values are specified in design, and they could apply to formats or to user text inputs. For example, in the alignment example above, if the align option was not used, the template could use left, provided that left had been specified in design as its default. In the same way if the user forgets to type a text input, the template could use a pre-planned default input instead of the missing parameter; sometimes just a code to say something was forgotten.
- PARAMETERS are usually bits of text that a user enters for a template to process. For example, if a template makes text red, it still needs to know the text to color; this text is called a parameter, and the text is included by the user when the template is called for use. Sometimes parameters contain text like code to insert an image, or even a gallery or a table; it just depends what the template is designed for. A template can even be the parameter of another template; for example, a template to insert a test paragraph might occupy the parameter space of a template to make a text box. The new paragraph would then appear in a new text box.
- MORE GENERALLY, templates let us do much of the preparation in advance of making a page, and let us insert a block of typing, be it code to make tables, boxes, and other structures, or just a paragraph of text that is used a lot.
Usage syntax
Parameters
The basic transclusion syntax given above can be extended by the addition of parameters, which are used to control the template's output. The syntax for this is
{{template name|parameter|parameter|...}}
where each "parameter" may either contain just a value (these are called unnamed parameters) or be of the form name=value (named parameters). The first, second, etc. unnamed parameters are equivalent to parameters named "1", "2", etc.
Whitespace characters (spaces, tabs, returns) are stripped from the beginnings and ends of named parameter names and values, but not from the middle: thus {{ ... | myparam = this is a test }} has the same effect as {{ ... |myparam=this is a test}}. This does not apply to unnamed parameters, where the whitespace characters are preserved.
What parameters (if any) can or should be passed to a template, and how they are to be named, depends on the coding of that template. Named parameters can be defined in any order. Superfluous or misnamed parameters will be ignored; undefined parameters will be assigned default values. If a parameter is defined more than once, the last value takes effect.
The value of a parameter can be the empty string (pipe or equals sign followed immediately by the next pipe or the closing braces). This is different from leaving the parameter undefined (although templates are often coded so as to behave the same in both cases).
Other details
Template names are exactly like other page names case-sensitive except for the first letter, with spaces indistinguishable from underscores. If the symbol # (normally used to link to a section of a page) appears in a transclusion, then it and any characters that follow it are ignored.
Notice that the same double-brace syntax is used for many MediaWiki variables and parser functions (see Help:Magic words). For example, the code {{NAMESPACE}} may look like a template call, but it is actually a variable whose value is the namespace prefix of the current page.
Creating and editing templates
Templates are created and edited in much the same way as any other page: choose an appropriate name, navigate to that page, then click the Edit tab or create a new page as needed. As mentioned above, templates are normally placed in the Template namespace, though templates intended for your own personal use or for experimentation can be created in your own user space. Anything that can be included on a normal page or article can be included on a template, including other templates (called subtemplates). Templates often make use of programming features — parameters, parser functions and other magic words — which allow the transcluded content to vary depending on context. There are also special tags to control which information is transcluded and which is not.
Before creating a template, do a quick search for existing templates (e.g. by exploring Portal:Template index) to see if there's already a template that does what you want, or a similar template whose code can be copied and modified (or left in place and expanded). Look for generic templates on which the new template can be based (for example, navbox templates can be easily created by calling the generic Template:Navbox).
There is no hard rule about what name to choose for a template — make it short but reasonably descriptive. If similar templates exist, try to follow a consistent naming pattern. Templates can be renamed without breaking existing transclusions, provided a redirect to the new template name is left behind.
Be extremely careful when editing existing templates — changes made can affect a large number of pages, often in ways you might not expect.
To propose the deletion of unused or inappropriate templates, or other changes in the way particular templates are used, go to Templates for discussion (TfD).
System variables and conditional logic
Template code often makes use of the variables and parser functions described at Help:Magic words, in order to make the template's behaviour depend on the environment (such as the current time or namespace) or on the parameter values which are passed to it. They can also be used for arithmetical calculations. Notice that full string manipulation is not available (although templates have been created which provide such functionality, though very inefficiently and imperfectly), nor are certain standard programming features such as loops and variable assignment.
Some of the most often used variables and functions are listed hereafter. For more, see Help:Magic words.
| Description | Text entered | Result |
|---|---|---|
| Uppercasing text | {{uc: Heavens to BETSY! }} | HEAVENS TO BETSY! |
| Lowercasing text | {{lc: Heavens to BETSY! }} | heavens to betsy! |
| Getting a namespace name | {{NS: 1 }} | Talk |
| Getting a Wikipedia URL | {{fullurl: pagename }} | https://www.boywiki.org/en/Pagename |
The ParserFunctions extension gives more programming-oriented parser functions.
| Description | Text Entered | Result |
|---|---|---|
| Testing between options | {{#ifeq: yes | yes | Hooray...! | Darn...! }} {{#ifeq: yes | no | Hooray...! | Darn...! }} |
Hooray...! Darn...! |
| Testing if a parameter is set | {{#if: {{{param|}}} | Hooray...! | Darn...! }} | Darn...! |
| Making a calculation (mathematics) [area of circle of radius 4, to 3 decimal places] |
{{#expr: ( pi * 4 ^ 2 ) round 3 }} | 50.265 |
| Testing the result of a calculation [is 1230 even or odd?] |
{{#ifexpr: 1.23E+3 mod 2 | Odd | Even }} | Even |
| Description | Text Entered | Result (for this help page) |
|---|---|---|
| Page names | {{PAGENAME}} {{FULLPAGENAME}} |
Templates Help:Templates |
| Name of the current namespace | {{NAMESPACE}} | Help |
| Number of registered users | {{NUMBEROFUSERS}} | 225 |
| Number of pages in a given category | {{PAGESINCATEGORY:"Weird Al" Yankovic albums}} | 0 |
| Current software version | {{CURRENTVERSION}} | 1.42.1 |
| Timestamp of last revision | {{REVISIONTIMESTAMP}} | 20121226150653 |
Text Paragraphs
The code for a template need not start with any special character or symbol. The main consideration is that the code performs the required action, just as if it were typed directly onto the page. At the 'end of the code block, be sure to add the <noinclude></noinclude> tags as mentioned above.
All of the existing Wikitext and HTML code that can be used in a page can be used for a text template. The user of a page does not have access to the parts associated with styles, namely the heading of the web page and their style sheets. As a result, users are limited to modifying the parts of the page that are available, the text within the body of the page. Those familiar with web page design will know that the only remaining available method is to modify the page's text with in-line styles. Working methods use the <div></div> tags and the <span></span> tags, thanks to a feature of Wikitext that allows the use of HTML coding within it. CSS, (Cascading Style Sheet), properties and values are used within these tags to modify the text styles that would otherwise apply.
It is as well to point out here the difference in use for span and div in text templates. Span should be used to format text only, noting that any formats applied to the text will not extend beyond the last text character; div, on the other hand, will apply its formats to a rectangular block of text that extends across the page. the significance of this is that div is neater for changing background colors on the page. A comparative example can be seen in the Classes and Styles in Tags section of Class and Style Notes.
The Simplest Case
Before doing any formatting, consider the method for making a template from a simple block of text. Type a block of text, with all of its formats and page layout in place, then save the block as a template. It is as simple as that. Such blocks of text find use for test text, such as Lorem Ipsum, a well-known text block of fictitious content used by printers and others in laying out their work. To use such a template just type: Template:Block at any convenient place on a page to produce the text block. This block of text is not pre formatted with hard breaks, so it will wrap within the space where it is typed, and with the default text styles of the page.
Images
Making Boxes
The following sections make box or table templates from Wikitext. They can also be made with HTML tables in the same way. When it comes to making such a template, wikitext is fine but when a table is needed to go into a template as its parameter, or part of its parameter, an HTML table should be used instead. The WikiBooks text [[../Tables|Making Tables]] touches on HTML table structures, and explains how to use styles. It is assumed that the reader is familiar with these concepts in the text that follows.
The Box Structure
Boxes are essentially tables, in fact table cells. The CSS property list to format tables is extensive. Simple boxes make use of the table container, and one or two cells within it.
Apart from the table container, the other structures of a table include its rows, and cells. In the case below there are two rows, each with only one cell in them. Each part of a table has properties that affect it, and an example of typical table coding can be seen in the listing below.
Parameters and Options
It is intended to provide three options along with the two parameters. The options are to be background,width, and align. The parameter names are to be 1 and 2, with the labels heading and content.
Nesting templates
Templates may contain other templates — this is usually called "nesting". As the template is processed, the wikitext produced by any nested templates is transcluded into the nesting template, so that the final product is essentially processed from the most deeply nested template out. While fairly straightforward in application, it involves some noteworthy quirks and tricks.
