Help:Templates: Difference between revisions

From BoyWiki
← Older edit
VisualWikitext
 
(81 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{Stub}}




A list of BoyWiki templates can be found on [[Portal:Template index]].


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 <nowiki>{{templatename}}</nowiki> while editing the page. When the page is later viewed, <nowiki>{{templatename}}</nowiki> is replaced by the content of the page "Template:templatename". If the page "Template:templatename" is later altered, all the pages with <nowiki>{{templatename}}</nowiki> in them will change automatically.
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 <nowiki>{{templatename}}</nowiki> while editing the page. When the page is later viewed, <nowiki>{{templatename}}</nowiki> is replaced by the content of the page "Template:templatename". If the page "Template:templatename" is later altered, all the pages with <nowiki>{{templatename}}</nowiki> 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 {{Tl|stub}} which indicates that the article is a fledgling.   
Amongst other things, templates are used to add recurring messages to pages in a consistent way, to add boilerplate such as template {{Tl|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".
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]]  
Templates are documented (or should be) at their pages. See [[Help:Template Documentation]]  
Line 14: Line 14:


==General==
==General==
Most templates are pages in [[Portal:Template index]]
Most templates are listed on [[Portal:Template index]]


Templates can contain any desired [[wp:wikitext|wikitext]], including calls to other templates. They have some limited programming capacities: customizable values (called [[#Parameters|parameters]]), calculation and branchings (using [[Help:Parser functions|parser functions]]), and access to wiki-specific variables ([[Help:Magic words|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).
Templates can contain any desired [[Help:Wikitext|Wikitext]], including calls to other templates. They have some limited programming capacities: customizable values (called [[#Parameters|parameters]]), calculation and branchings (using parser functions), and access to wiki-specific variables ([[Help:Magic words|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 <code><nowiki>{{template name}}</nowiki></code> 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.
'''How to do it:''' To transclude a template to an article or page, type <code><nowiki>{{template name}}</nowiki></code> 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.


Templates stored in other namespaces are transcluded in the same way, except that the namespace prefix, such as "User:", must be included. To transclude a page in [[WP:mainspace|mainspace]], precede its title with a colon, as, for example, <code><nowiki>{{:Page name}}</nowiki></code>.
'''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.


'''Note:''' Attempting to transclude a template that does not exist produces a [[wp:redlink|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==
==Usage syntax==
Line 36: Line 48:
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).
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).


===Substitution===
 
If a template is to be [[Help:Substitution|substituted]] in the wikitext rather than [[WP:transclusion|transcluded]], add the modifier <code>subst:</code> after the initial pair of braces, as in <code><nowiki>{{subst:afd}}</nowiki></code>. Parameters can be added as normally.
* Note: if substituting a page from mainspace, the word "subst" must be followed by two colons.


===Other details===
===Other details===
Template names are exactly like other [[Help:Page name|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. If the page name used for transclusion is a [[WP:redirect|redirect]], the redirect's target will be transcluded instead&nbsp;— this means that alternative names can be created for templates, as aliases that can be used seamlessly.
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 <code><nowiki>{{NAMESPACE}}</nowiki></code> may look like a template call, but it is actually a variable whose value is the namespace prefix of the current page.
Notice that the same double-brace syntax is used for many MediaWiki variables and parser functions (see [[Help:Magic words]]). For example, the code <code><nowiki>{{NAMESPACE}}</nowiki></code> may look like a template call, but it is actually a variable whose value is the namespace prefix of the current page.


==Basic template usage examples==
(If you wish to experiment with any of these, please use the [[Template:Template sandbox|template sandbox]].)
An example of a very simple template can be found at [[Template:Lambda]], which places the lambda symbol, λ. Click the "Edit" tab on that template page to see the template code (its wikitext). The "active" part of that code, called the ''expansion'' of the template, is <code>&amp;lambda;</code>. (The remainder of the wikitext is enclosed between <nowiki><noinclude>...</noinclude></nowiki> tags, which means that it is displayed on the template page itself, but will not be included along with the template.)
To transclude the above template onto another page (e.g. in the [[Wikipedia:Sandbox]]), type <code><nowiki>{{lambda}}</nowiki></code> (or <code><nowiki>{{Lambda}}</nowiki></code>&nbsp;— the case of the first letter is not significant) somewhere into the wikitext of the target page, and save it. The page will be displayed as if the template call were replaced by the expansion of the template, i.e. as if the wikitext contained <code>&amp;lambda;</code> at that point. The displayed page will therefore contain the text "λ".
For example, type "<code>The 11th letter of the Greek alphabet is the lambda (<nowiki>{{lambda}}</nowiki>)</code>" and you will see "The 11th letter of the Greek alphabet is the lambda ({{lambda}})". You can use templates without knowing the details of their code&nbsp;— you only need to remember what result they produce (this is usually described on the template page).
Another way to use this template is to [[Help:Substitution|substitute]] it. If you type "<code>The 11th letter of the Greek alphabet is the lambda (<nowiki>{{subst:lambda}}</nowiki>)</code>" and save the page, you will again see ""<code>The 11th letter of the Greek alphabet is the lambda (λ)</code>". However this time, if you look again at the saved wikitext, you will see that the template calls really were replaced by the expansion of the template when you saved the page. The link between the output text and the template is now broken, and the output will not be affected by changes which might be made to the template at some future time (as it would be in the case of transclusion).
==={{anchor|Parameters}} Examples with parameters===
An example of a template that takes parameters is [[Template:For]]. Type <code><nowiki>{{for|the card game|Contract bridge}}</nowiki></code> in the sandbox to produce the following text:
{{for|the card game|Contract bridge}}
This usage takes two unnamed parameters, but the same template can also be used with different numbers of parameters to give slightly different results, as explained in the documentation on the template page. For example, <code><nowiki>{{For||Latins|Latin (disambiguation)}}</nowiki></code> produces
{{For||Latins|Latin (disambiguation)}}
Note in particular the usage with an empty parameter&nbsp;— here the consecutive pipes mean that the first parameter passed to the template is the empty string.
Other templates, particularly more complex ones, take named parameters (or a mixture of named and unnamed ones). A simple example is [[Template:Payoff matrix]], used to generate a 2-by-2 grid. Type:
:<code><nowiki>{{payoff matrix | UL = 5 | UR = 7 | DL = 2 | DR = 9 | Name = Example usage }}</nowiki></code>
{{payoff matrix | UL = 5 | UR = 7 | DL = 2 | DR = 9 | Name = Example usage }}
to produce the grid you can see on the right.
See the template page for more possibilities. Notice that the template is used here without defining all its possible parameters&nbsp;— undefined parameters are given default values.
The spaces around the equal signs and before and after the parameters are used only for clarity&nbsp;— they are not needed, and are ignored when the template is evaluated (although this is not the case with unnamed parameters). However parameter names are fully case sensitive&nbsp;— for example, it is not possible to replace "DR" by "dr" or "Dr" in the above example. Parameters with names that are not used by the template are simply ignored.


==Usage hints and workarounds==
The following points may be worth noting when using templates:
* An unnamed parameter cannot contain an ordinary equals sign, as this would be interpreted as setting off a named parameter. (This does not apply if the equals sign comes within another template call or other item which the parser handles separately.) To pass an equals sign in an unnamed parameter (for example in a [[URL]] with key/value pairs), replace the equals sign with the special template {{tlx|{{=}}}}, which returns an equals sign that will not be specially interpreted. Another method is to replace the unnamed parameter (and any subsequent unnamed parameters) with named parameters&nbsp;— the first unnamed parameter is equivalent to a named parameter with the name "1", and so on. So to call template {{tl|done}} with the parameter "a=b", type either <code><nowiki>{{done|a{{=}}b}}</nowiki></code> or <code><nowiki>{{done|1=a=b}}</nowiki></code>.
* Similarly, it is not possible to use an ordinary pipe character | in template parameters, as it will be interpreted as a separator. (Again, this does not apply if it comes within another separately parsed item, such as a piped wikilink.) This time the problem can be solved by using the special template {{tlx|!}} in place of the pipe, or (if the pipe is not intended to be parsed specially at a higher level) using the [[List of XML and HTML character entity references|HTML entity]] <tt>&amp;#124;</tt>.
* Remember that whitespace characters (spaces, tabs, carriage returns and line feeds) are not automatically stripped from the start and end of unnamed parameters (as they are from named parameters). Including such characters (or any other non-visible characters in any parameters) may in some cases affect the template's behaviour in unexpected ways. (Template designers can use {{tl|StripWhitespace}} to remove unwanted whitespace in unnamed parameters.)
* In documentation and discussions it is often convenient to be able to produce the template call syntax, with a link to the template in question, but without actually calling the template. This can be done easily using the "{{tl|tl}}" template (the ''template link'' template). For example, using the text "<tt><nowiki>{{tl|tc}}</nowiki></tt>" produces "{{tl|tc}}". There is an extended version, {{tl|tlx}}, which also supports parameters.
* When a template is changed (when the template or one of its subtemplates is edited), the change will be reflected on all pages on which the template is transcluded. However the change may not become visible on all pages immediately&nbsp;— a previously cached version of a page, based on the previous version of the template, may continue to be displayed for some time. Use the [[Help:Purge|purge]] function to force a page to be displayed using the latest versions of templates. (This includes the template page itself, if it contains usage examples.)
* When viewing old versions of pages, remember that templates will be transcluded as they are now, not necessarily as they were when the old page version was active.
* To list all pages onto which a template is transcluded, use [[WP:What links here|What links here]] on the template page. (This will not include pages where the template has been substituted.)
* To get a list of templates transcluded on a page, click "Edit", and find the list below the edit window. This list also includes the sub-templates used by the templates that are directly transcluded. To get such a list for a page section, an old version of the page, or your newly edited version prior to saving, click "Show preview" on the appropriate edit page. (For an old version, the subtemplate tree will be constructed according to the templates' current state.)
* There are limits to the number and complexity of the templates that an article may have. See the "[[#Expand limits|Expand limits]]" section for help in resolving this.


==Creating and editing templates==
==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 [[WP:Template namespace|Template namespace]], though templates intended for your own personal use or for experimentation can be created in your own [[WP:user space|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&nbsp;— parameters, parser functions and other [[Help:Magic words|magic words]]&nbsp;— 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.
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. Templates intended for your own personal use or for experimentation can be created in your own [[WP:user space|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&nbsp;— parameters, parser functions and other [[Help:Magic words|magic words]]&nbsp;— 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, [[WP:navbox|navbox]] templates can be easily created by calling the generic [[Template:Navbox]]).
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, [[WP:navbox|navbox]] templates can be easily created by calling the generic [[Template:Navbox]]).
Line 94: Line 66:
'''Be extremely careful when editing existing templates&nbsp;— changes made can affect a large number of pages, often in ways you might not expect.'''  
'''Be extremely careful when editing existing templates&nbsp;— 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 [[WP:Templates for discussion|Templates for discussion]] (TfD).
===Handling parameters===
The values of the parameters which can be fed to a template are represented in the template code by items enclosed between ''triple'' braces:
* the code <code><nowiki>{{{xxx}}}</nowiki></code> will be replaced by the value of the parameter named ''xxx''
* the codes <code><nowiki>{{{1}}}</nowiki></code>, <code><nowiki>{{{2}}}</nowiki></code> etc. will be replaced by the first, second etc. unnamed parameter (or the value of a parameter named ''1'', ''2'', etc.); these are sometimes known as ''positional'' parameters
If a parameter is not assigned a value, then the above replacements will not take place&nbsp;— the form "{{{xxx}}}" will remain as the effective value of the parameter. To change this behaviour, define default values using the pipe syntax. For example, <code><nowiki>{{{1|default}}}</nowiki></code> will be replaced by the first unnamed parameter if there is one, or otherwise by the text "default". Similarly, <code><nowiki>{{{xxx|}}}</nowiki></code> will be replaced by the parameter named ''xxx'' if it exists, or otherwise will be left blank. Though if a template is called with the parameter specified as empty (e.g. <code>&#123;&#123;Example|&#125;&#125;</code>), the default for the parameter will be ignored; if that is undesired one can use <code><nowiki>{{#if:{{{1|}}}|{{{1}}}|default}}</nowiki></code> instead to get the text "default" even if the parameter is specified as empty.


Parameters do not get expanded when they are inside nowiki tags or XML-style extension tags. Thus, the following will not work within a template&nbsp;— <nowiki><myextension xparam={{{tparam}}}> ... </myextension></nowiki>&nbsp;— because the parameter is not expanded.


Because of the multiple uses of double-brace and triple-brace syntax, expressions can sometimes be ambiguous. It may be helpful or necessary to include spaces to resolve such ambiguity, for example by writing <code><nowiki>{{ {{{xxx}}} }}</nowiki></code> or <code><nowiki>{{{ {{xxx}} }}}</nowiki></code>, rather than typing five consecutive braces. However, watch out for unwanted whitespace appearing in template expansions.


===System variables and conditional logic===
===System variables and conditional logic===
Line 111: Line 73:
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.
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]], and the fuller documentation at the MediaWiki pages [[mw:Help:Magic words]] and [[mw:Help:Extension:ParserFunctions]].
Some of the most often used variables and functions are listed hereafter. For more, see [[Help:Magic words]].


{| class="wikitable" style="text-align:center;" width="80%"
{| class="wikitable" style="text-align:center;" width="80%"
Line 186: Line 148:
|}
|}


The PAGENAME and NAMESPACE variables are particularly useful, and frequently used, to change template behavior based on context. For example, if the template transcludes a category link (e.g. cleanup templates, which transclude a link categorizing the page as a page which needs cleanup), it will often check the NAMESPACE variable to make sure that talk pages, user pages, or anywhere else the tag might incidentally be placed do not themselves get categorized as pages needing cleanup.
==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 '''<nowiki><noinclude></noinclude></nowiki>''' 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 '''<nowiki><div></div></nowiki>''' tags and the '''<nowiki><span></span></nowiki>''' 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.
 
 
 
====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.
 


===Nesting templates===
Templates may contain other templates&nbsp;— 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.


To pass a parameter value to a nested template, place a parameter tag as the value of one of the nested template's parameters.
==Making Boxes==
* Examples:
----
** Template:A contains <nowiki>"the quick brown {{B|{{{3}}}}} jumps over..."</nowiki>. This takes the value passed to the third positional parameter of Template:A and passes it as the first positional parameter of Template:B, then returns the wikitext produced by B as part of the phrase.
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.
** Template:A contains <nowiki>"the quick brown {{B|waldo={{{3}}}}} jumps over..."</nowiki>. As above, except the third positional parameter of Template:A is passed to the named parameter "waldo" of Template:B.
 
This [http://en.wikibooks.org/wiki/Editing_Wikitext WikiBooks text] touches on HTML table structures, and explains how to use styles.  
 
   
====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.


Template parameters themselves can be chosen conditionally.
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.
* Example:
** Template:A contains <nowiki>"the quick brown {{B|{{{3}}}=fox}} jumps over..."</nowiki>. Template:A passes the word "fox" to a parameter of Template:B that's named in A's third positional parameter.


A template can call itself, but will stop after one iteration to prevent an infinite loop.
====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''.


When a nested template contains unmatched braces&nbsp;— as in {{tl|lb}}&#125;&nbsp;— the unmatched braces are treated as text during processing, and do not affect the parsing of braces in the nesting template. If the nested template is substituted, however, the substitution is processed first, and this ''will'' change how braces are parsed in the nesting template. This has little practical use, but can occasionally introduce unexpected errors.
===Nesting templates===
Templates may contain other templates&nbsp;— 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.


See the [[meta:Help:Advanced templates]] and [[meta:Help:Recursive conversion of wikitext]] for more information. These pages also contain information on unusual calls such as <nowiki>{{template {{{parameter|}}} }}</nowiki>.
===Examples===
Here are two examples of box templates that are easy to use and are useful to those just starting out.


===Noinclude, includeonly, and onlyinclude===
{{shortcut|WP:NOINCLUDE|WP:INCLUDEONLY|WP:ONLYINCLUDE}}
By default, when a template is transcluded (or substituted), the entire wikitext (code) of the template page gets included in that of the target page. However it is possible to modify that behaviour, using tags that specify which parts of the template code are to be included. This makes it possible to avoid transcluding information intended for display only on the template page itself, such as the template's documentation, [[WP:Category|categories]] and [[WP:interwiki links|interwiki links]]. It is also possible to have parts of the code be transcluded, but <em>not</em> be processed on the template page itself (e.g. categories to be applied to the target pages which do not apply to the template). The tags are as follows
* {{tag|noinclude}}&nbsp;— the text between the noinclude tags will not be included when the template is transcluded (substituted)
* {{tag|includeonly}}&nbsp;— the text between the includeonly tags will be transcluded (substituted), but will not be processed on the template's own page
* {{tag|onlyinclude}} (not often used)&nbsp;— specifies that nothing on the page <em>except</em> what appears between the onlyinclude tags will be transcluded (substituted)


Perhaps the most common issue with the use of these blocks is unwanted spaces or lines. It is important to remember that the effect of these tags ends immediately after the last angle bracket, not on the next line or with the next visible character.
<pre>
{{Box1 start}}
Sample text
{{Boxes end}}
</pre>
;gives...
{{Box1 start}}
Sample text
{{Boxes end}}
<pre>
{{Box1 start}}
Box1 text
{{Box2 start}}
Box2 text
{{Boxes end}}
</pre>
;gives...
{{Box1 start}}
First box text
{{Box2 start}}
Second box text
{{Boxes end}}


These tags can be nested inside each other, though (for a given page) this really only applies to the {{tag|onlyinclude|o}} tag; nesting {{tag|includeonly|o}} and {{tag|noinclude|o}} tags is fairly pointless. Be careful not to split the tags, however. Constructions like {{tag|onlyinclude|o}}abc{{tag|includeonly|o}}def{{tag|onlyinclude|c}}ghi{{tag|includeonly|c}} will not work as expected. Use the "first opened, last closed" rule that is standard for XML.
===Making a Basic Wiki Table===
<pre>
{|class="wikitable"
! one box
|} </pre>
;gives...


===Problems and workarounds===
{|class="wikitable"
* If the first included character of a template is one of the Wiki markup characters <code>:;*#</code>, then it is processed as though it is at the beginning of a line (even when the template tag is not). This allows the creation of various kinds of lists in templates where the template may not always be in the correct place for a list. To avoid this use {{tag|nowiki|s}} before the markup; see [[Help:Nowiki]].
! one box
* For issues involving the substitution of templates (for example, how to control whether subtemplates are substituted as well when the parent template is substituted), see [[Help:Substitution]].
|}
* The template {{tl|Strip whitespace}} can be used to strip any initial or final whitespace from unnamed parameter values, if this would cause problems (named parameter values are automatically stripped in this way).
* For debugging templates the following techniques are sometimes helpful:
** using "subst:"&nbsp;— substituting a template (rather than transcluding it) can show more clearly what is happening when the template is transcluded; see [[Help:Substitution]].
** using "msgnw:"&nbsp;— this keyword (short for "message, nowiki") transcludes the wikitext of the template page, more or less, rather than the processed contents. It is not perfect: lists are rendered, comments are removed, and single newlines are replaced with spaces (which is particularly confounding when transcluding wikitext tables).
** using [[Special:ExpandTemplates]] to see the full recursive expansion of one or more templates.
* To protect server resources and avoid infinite loops, the parser imposes certain limits on the depth of nesting of transclusions and on the page size with expanded templates. This may cause pages to break when using very complex templates, particularly if there are multiple such templates on the same page. For more information, see [[WP:Template limits|Template limits]]. A page's overall load on the server can be checked by examining the generated HTML for a page and looking for the "NewPP limit report" comments.
* Do not use <code>=</code> wikimarkup to create section headers within a template which is intended for use in article space&nbsp;— this will create an <code>[edit]</code> link that when transcluded will confusingly open the template for editing.


==Template limits==
<pre>
{{Anchor|Expand limits}}
{|class="wikitable"
{{details|Wikipedia:Template limits}}
!
'''"Post-expand include size"  limit.''' When templates are rendered or expanded to HTML for viewing in your browser, they use memory. This is called the "post-expand include size" and has a limit of 2,048,000 bytes. This size is included as an invisible comment in the HTML output— use your browser's view source feature to show the raw HTML and search for ''newpp''. The report will look like:
!Top row
<source lang="html4strict">
|-
<!--
!First row
NewPP limit report
| (add some txt)
Preprocessor node count: 2382/1000000
|}
Post-expand include size: 63476/2048000 bytes
</pre>
Template argument size: 9517/2048000 bytes
;gives...
Expensive parser function count: 2/500
{|class="wikitable"
-->
!
</source>
!Top row
|-
!First row
| (add some txt)
|}


The example shows that template expansion is using 63k out of 2M of available memory.
<pre>
{| class="wikitable"
!top row
!This is text
!This is more txt
!This is more txt
|-
!line1
|(add some txt)
|(add some txt)
|(add some txt)
|-
!line2
|(add some txt)
|(add some txt)
|(add some txt)
|-
!line3
|(add some txt)
|(add some txt)
|(add some txt)
|}
</pre>
;gives...


'''Display problem.''' If too many templates are included on a page, the post-expand include size may exceed the limit. When this happens, templates after the limit will no longer expand and will instead display as a wikilink (for example, {{red|1=<u>Template:''templatename''</u>}}). Common causes are the inclusion of too many citation templates and/or flag templates. To resolve this problem [[Wikipedia:Substitution|substitute templates]], remove templates, or split the page.
{| class="wikitable"
!top row
!This is text
!This is more txt
!This is more txt
|-
!line1
|(add some txt)
|(add some txt)
|(add some txt)
|-
!line2
|(add some txt)
|(add some txt)
|(add some txt)
|-
!line3
|(add some txt)
|(add some txt)
|(add some txt)
|}
<pre>
{| class="wikitable" style="float: right;: 1em auto 1em auto;"
|+ '''(this is my table name)'''
! scope="col" | top row
! scope="col" | This is text
! scope="col" | This is text
|-
| row 1  || (add some txt) || (add some txt)
|-
| row 2 || (add some txt) || (add some txt)
|}
</pre>
;gives...


{| class="wikitable" style="float: right;: 1em auto 1em auto;"
|+ '''(this is my table name)'''
! scope="col" | top row
! scope="col" | This is text
! scope="col" | This is text
|-
| row 1  || (add some txt) || (add some txt)
|-
| row 2 || (add some txt) || (add some txt)
|}
<Br>
If you float the wikitable right, you can make your text rap around the box without leaving large blank spaces on your page. This is often very useful.
<Br>
<center> (This is how a line would look.)</center>


----


<Br>


[[Category:Template documentation]]
==External Links==
*[http://creativecommons.org/licenses/by-sa/3.0/ Creative Commons Attribution-ShareAlike License]


*[http://en.wikipedia.org/wiki/ Some parts of this page have been adapted from wikipedia]










[[Category:BoyWiki]]
[[Category:Help templates]]

Latest revision as of 12:20, 13 April 2015


A list of BoyWiki templates can be found on Portal:Template index.

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 listed on 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. 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.



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.

Examples of core parser functions
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.

Examples of extension 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
Examples of System Variables
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}} 20150413122054

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.


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.


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.

This WikiBooks text touches on HTML table structures, and explains how to use styles.


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.

Examples

Here are two examples of box templates that are easy to use and are useful to those just starting out. 


{{Box1 start}}
Sample text
{{Boxes end}}
gives...

Sample text 

{{Box1 start}}
Box1 text
{{Box2 start}}
Box2 text
{{Boxes end}}
gives...

First box text

Second box text

Making a Basic Wiki Table

{|class="wikitable"
! one box
|}
gives...
one box 
{|class="wikitable"
! 
!Top row
|-
!First row
| (add some txt)
|}
gives...
Top row
First row (add some txt) 
{| class="wikitable"
!top row
!This is text
!This is more txt
!This is more txt
|-
!line1
|(add some txt)
|(add some txt)
|(add some txt)
|-
!line2
|(add some txt)
|(add some txt)
|(add some txt)
|-
!line3
|(add some txt)
|(add some txt)
|(add some txt)
|}
gives...
top row This is text This is more txt This is more txt
line1 (add some txt) (add some txt) (add some txt)
line2 (add some txt) (add some txt) (add some txt)
line3 (add some txt) (add some txt) (add some txt) 
{| class="wikitable" style="float: right;: 1em auto 1em auto;"
|+ '''(this is my table name)'''
! scope="col" | top row
! scope="col" | This is text
! scope="col" | This is text
|-
| row 1  || (add some txt) || (add some txt)
|-
| row 2 || (add some txt) || (add some txt)
|}
gives...
(this is my table name)
top row This is text This is text
row 1 (add some txt) (add some txt)
row 2 (add some txt) (add some txt)


If you float the wikitable right, you can make your text rap around the box without leaving large blank spaces on your page. This is often very useful.

(This is how a line would look.)


External Links

Retrieved from "https://www.boywiki.org/en/index.php?title=Help:Templates&oldid=22286"