See something you'd like to change or add, but you've never edited an open encyclopædia before? This overview was written to help absolute beginners get started.

aSK:Template style manual

From A Storehouse of Knowledge
Jump to: navigation, search

The purpose of the template style manual is to make it easier for contributors using templates by having standard naming conventions and clear documentation.

Contents

Template names

Templates names comprising multiple words should have the words separated by spaces.

Apart from the first letter of the name, which is case-insensitive, all characters of a name should be lower case, except for initial letters of proper nouns.

  • Examples:
    • Box quote
    • Boxed Bible quote
  • Examples of what not to do:
    • BoxQuote
    • Box Quote
    • Box_quote

Template parameter names

Named parameters should all be lower case.

Named parameters comprising multiple words should have the words separated by spaces.

Linked parameters

If a parameter supplies text that will be automatically linked by the template, it's name should have a trailing capital "L" (separated from the rest of the name by a space). You can have linked and unlinked versions of parameters distinguished by this. For example:

  • parameter name would be for unlinked text
  • parameter name L would be an alternative for linked text.

(Note that it is up to the template to handle these two cases.)

Linked value template

An alternative is to use the {{linked value}} template. This template will return a linked version of the parameter unless the editor includes a link in the parameter (specifically, if the characters ]] are included. The {{Linked parameters}} template can be used to add explanatory text for this feature, in template documentation.

Example

The template has a parameter named language L. If the editor uses language L=English, then English will automatically be linked.

However, if the editor wants to put language L=English and French, he doesn't want 'English and French' as a link. So in this case, he can put language L=[[English]] and [[French]] and the template will detect the existing links and not add its own link.

Disabled parameters

See Data block, below, for parameter names beginning with #.

Documentation

Templates existing on A Storehouse of Knowledge must be documented, or they will be deleted.

They must be documented in two places:

There are exceptions to this rule:

  • Some articles have a sub-page transcluded into the article as a template, even though not in template namespace. These should only be used if the sub-page is transcluded into the one (parent) article. If they are to be used in more than one place, they should be in template namespace. These do not need to be documented.
  • A Storehouse of Knowledge does not allow signature templates. However, this does not preclude having a signature template which is substituted into another page. It is transclusion that is not allowed. As the template is only for use by a single person, it does not need to be documented.

Documentation on the template page

To include documentation on the template page, include it between <noinclude> tags. Anything between <noinclude> tags will appear on the template page but is not part of the template, so will not appear on pages that the template is placed on. There are three ways to put the documentation on the page:

  1. Write the full documentation.
  2. Put a link to another page which itself contains the documentation.
  3. Write the documentation on another page (usually a sub-page), and include that other page on the template page using the template syntax. For example: <noinclude>{{<template-name>/doc}}</noinclude> will place the contents of the "doc" sub-page of the template on the template page itself.

Methods 2 and 3 are useful if the template itself is locked from editing, as it still allows the documentation itself to be edited by any editor.

The following templates should be placed on the documentation page of all templates. In some cases, the first two templates are all that is required, but often other information should be added also.

  • {{Template doc}} This is a brief description of the template.
  • {{Parms}} This is a container for a list of parameters. If there are no parameters, just place {{Parms|}} on the page.
  • {{Parm}} This comprises the details of a single parameter. Use one of these for each parameter in the template, with all of them comprising the one parameter required for the {{Parms}} macro.

To make it easier, simply copy the following text to the documentation page of a template, then fill in the details. If you are not placing this on the template page itself, omit the <noinclude> tags.

<noinclude>
{{Template doc
 |#name =
 |pages =
 |purpose =
 |page cat =
 |template cat =
}}
{{Parms|
 {{Parm|name|purpose|required? (yes/no)|SMW parameter|Comment (may be default value)}} <!-- Replace the fields here with your own values -->
 {{Parm|||||}} <!-- use as many "Parm" macros as the template has parameters -->
}}
</noinclude>

Data block

A template may have a 'data block', a skeleton use of the template which can be copied to pages.

As some parameter may have defaults if the parameter is not supplied, including the parameter in the data block will override the default even if a value is not supplied. For example, if a template allows a parameter of name, but uses the page name if the name parameter is not passed, then the following copied from a data block would prevent the page name being used:

{{sample template
 | name    =
 | parm 2  =
}}

Therefore, within data blocks, names of parameters with default values should have a #[note 1] prepended. Editors using the template should then delete the # from the pasted data block if they want to pass a value to the parameter:

Using the default value Passing a value
('#' character has been deleted)
{{sample template
 | #name    =
 | parm 2  =
}}
{{sample template
 | name    = John Smith
 | parm 2  =
}}

Documentation in the template list

All templates must also be included in the template list for easy reference. To include your template in this list, locate the appropriate section and list your template in alphabetical order using the format * {{tl|your template name}} description. The description is a brief description of what the template is for, including mention of parameters.


Note

  1. The # symbol is chosen for convention only; almost any character would work
Personal tools

Variants
Actions
visitor navigation
contributor navigation
monitoring
Toolbox