Template:TemplateBox

From Wikimedia Commons, the free media repository
Jump to: navigation, search
Documentation icon Documentation[view] [edit] [history] [purge]

This documentation is transcluded from Template:TemplateBox/doc.

The template provides a uniform way to provide basic information about the use of a template. See: Commons:Template documentation and Commons:TemplateData.

Usage

{{TemplateBox
 |1                  =
 |1d                 =
 |1d-td              =
 |1type              =
 |1def               =
 |1stat              =
 |name               =
 |desc               =
 |namespace          =
 |usergroup          =
 |placement          =
 |usage-notes        =
 |type               =
 |example            =
 |example-value      =
 |i18n-method        =
 |i18n-desc          =
 |i18n-mediawiki-msg =
 |i18n-subpage       =
 |seealso            =
 |setscats           =
 |print              =
 |shorthand          =
 |relieson           =
 |mustbesubst        =
}}

Template parameters

Parameter Description Default Status
1 name (param) parameter name (similarly 2, 3, …) empty optional
1d
1d-en
1d-td-en
1description
1description-en
1description-td-en
description (param) description of the parameter (similarly 2d, 3d, …) -langcode empty optional
1d-td
1description-td
1description-td-en
TemplateData description (param) description of the parameter (similarly 2d-td, 3d-td, …) for Extension:TemplateData which does not accept Wiki-markup. If this parameter is omitted, 1d is used. You can always override the defaults specifically for TemplateData by appending -td to the parameter-name. You can specify a language by appending your language-code. E.g. 3d-td-en would be the English translation of the description of parameter 3 which will be used in TemplateData. -langcode empty optional
1label
1label-td
1label-td-en
1label-en
label (param) A (very) brief name for the parameter. Try to keep under 20-ish characters. 1label-de would be the German translation of this label. -langcode empty optional
1aliases aliases (param) List of aliases. An alias is an alternative name for the parameter that may be used instead of (not in addition to) the primary name. Separate them by / (a slash) empty optional
1type type (param) The type of the parameter, for (soft) type hinting. One of: number, string, string/wiki-user-name, string/wiki-page-name, string/line; unknown is assumed by default empty optional
1set set (param) Label and ID of a set in one. Multiple parameters can be grouped in a set, if either none or all of them must be supplied. Try to keep under 20-ish characters. empty optional
1def
1def-td
1default
default (param) default value for the parameter (similarly 2def, 3def, …) -langcode empty optional
1stat
1stat-td
1deprecated
1required
status (param) status of the parameter (similarly 2stat, 3stat, …); possible values:
required  
optional  
optional- 
optional and not present in the standard form
deprecated  
optional optional
useTemplateData expose TemplateData whether the template should expose TemplateData - omitting means "false", setting to 1, true or yes, "true". Setting to only will suppress the house-made table. Setting useTemplateData to export will turn TemplateBox into a preformatted Copy&Paste template. empty optional
name title (template) name of the template (needed for viewing the documentation on another page than the template page, in particular for viewing the documentation page separately) {{BASEPAGENAME}} required
desc
desc-td
description
description-en
description (template) description of what the template does -langcode empty required
namespace namespace namespaces, the template is intended to be used in; possible values:
all
talks
contents
Main
Talk
User
User talk
Commons
Commons talk
File
File talk
MediaWiki
MediaWiki talk
Template
Template talk
Help
Help talk
Category
Category talk
Creator
Creator talk
Special
Any other values will show as “unknown”.
no namespace specified required
usergroup usergroup usergroup that is meant to use the template; possible values:
all
bot
administrator
admin
sysop
bureaucrat
crat
checkuser
licensereviewer
otrs
autoconfirmed
autopatrolled
filemover
oversight
patroller
rollbacker
steward
upwizcampeditors
no user group specified required
placement placement placement on the page. Possible values:
top  
bottom  
licence  
source  
empty optional
usage-notes usage-notes notes about the correct usage of the template empty optional
type type (template) what type is the template (infobox, formatting, licence tag, …) empty optional
example example Example use (works with a single unnamed parameter only). There is also example2 for a second example. empty optional
example-value example-result If there is more than one parameter you would like to show or if there are named parameters, use:

{{TemplateBox
 |name=SampleTemplate
 |example=param1=value1{{!}}param2=value2
 |example-value={{SampleTemplate
   |param1=value1
   |param2=value2
   |category=
 }}
}}
empty optional
i18n-method translation method method the localization is achieved by. Known values:
autotranslate 
using {{autotranslate}} or applying a similar method
switch 
using {{LangSwitch}} in the template itself
no localization needed
custommediawiki-msg 
using MediaWiki namespace messages
mediawiki-msg 
using MediaWiki namespace messages, translated on translatewiki.net
ext.translate 
using {{autotranslate}} or applying a similar method on a subpage that is marked for translation using the translate extension
empty optional
i18n-desc translation info additional info about the localization empty optional
i18n-mediawiki-msg mediawiki-message When using “mediawiki-msg” as method, optionally put the name of the message here. Falls back to: empty optional
i18n-subpage translation-subpage When using “ext.translate” as method, optionally put the name of the sub-page here. A dot (.) means that the current template hosts the translation on its subpages directly. i18n optional
seealso see also relevant links (put in a list of them) empty optional
setscats categorizes into what categories are automatically set by the template (put in a linked list of them) empty optional
print print The way, the parameters are typically arranged. Possible values: multi - parameters arranged in multiple lines; one - one line; infobox - multiple lines and space padding in front of the =. one (if type param ≠ infobox) optional
lines
print
Use parameter print instead. empty optional
shorthand shorthand shorthand for easy use (redirects to main template). See examples here and here of lists of redirects, and searches for more. empty optional
relieson relies on list of templates on which the template's basic functionality relies empty optional
mustbesubst must be subst Set to "yes" (or any value) if the template must be substituted. This puts "subst:" into the template example under "usage". empty optional

Additional information

The template is intended to be used in the following namespaces: the Template namespace

The template is intended to be used by the following user groups: all users

Placement:

in the '/doc' subpage of a template

Relies on:
Module:TemplateBox, Module:Languages

See also

Localization

Boarisch | বাংলা | Català | Čeština | Dansk | Deutsch | Deutsch (Sie-Form)‎ | Zazaki | English | Español | Eesti | فارسی | Suomi | Français | Galego | Magyar | Italiano | 日本語 | 한국어 | Lëtzebuergesch | Македонски | മലയാളം | Plattdüütsch | Nederlands | ਪੰਜਾਬੀ | Polski | Português | Português do Brasil | Русский | Slovenščina | Svenska | Türkçe | Українська | 中文 | 中文(简体)‎ | 中文(繁體)‎ |

This template makes use of {{Autotranslate}} and the translate extension.

Icono de traducción.svgTranslate this template now!
 Administrate translations.

About: TemplateData

Every entity, except inherit that is documented at the TemplateData technical documentation, is supported by {{TemplateBox}}. Conversion to JSON is done by a LUA module. The LUA module automatically converts traditionally used parameters as well as the new ones to both, TemplateData, as well as the "historic table", on demand. The "historic table" is the table which was used to show parameter information at Wikimedia Commons before TemplateData was invented.

Required parameters
  • |desc= (or in its translated form), parameters and their description

Translation
  • Avoid {{LangSwitch}}. It doesn't work in TemplateData.
  • Append -langcode to the name of any translatable parameter, marked by -langcode in TemplateBox. For example, adding the French translation of the description of parameter 1, you would write |1d-fr=C'est la description pour paramètre un.. Supplying only |1d-en=This is the description of parameter 1. instead of |1d=This is the description of parameter 1. will also work. The -en-style is recommended because it eases the job for translators. They then recognize the structure behind it without having to consult the documentation.
  • The language code must be the last element. Valid: |1d-td-en=. Invalid: |1d-en-td=
Naming
  • Both, old names and new names are supported but treated differently if both of them are supplied.
    • For example, while creating the "historic table", if both 1def and 1default where supplied, the value for 1def would be used. For generating TemplateData, the preference is the other way around.
Overriding
  • It's possible to override a specific entity, either for the "historic table" or for TemplateData.
    • To override for TemplateData, append a -td to the parameter's default name.
    • On the other hand, if you coded something for TemplateData and want to use a link or other markup in the "historic table", use the parameter name without the -td or modify that, which should be only used for TemplateData appending -td.
Pay attention
  • TemplateData does not support parsing Wiki-Markup. Think of it as if it would expand all templates and finally putting a nowiki around all this.
  • When including templates, they must be wrapped them in <nowiki>s, if they should not be expanded (it's, on the other hand, a geeky feature that you can use, if having the expanded content inside TemplateData is exactly what you want).
  • Even though some tags, such as <pre> seem to be rendered as expected, avoid them.
Activation
  • TemplateData can be activated setting the useTemplateData parameter to 1 or to only. The former will add a collapsed version of the table; the latter one replaces the "historic table" with the TemplateData table. In both cases, TemplateData is available through the API.
Fetching TemplateData (e.g. for TemplateBox itself)

/w/api.php?action=templatedata&format=json&titles=Template%3ATemplateBox (raw result, pretty result)

Advantages
  • No type-mixture: Instead of inserting a new content-type, a template can be used.
  • Syntax: Less error-prone compared to editing JSON (without a special editor).
  • Schema: Always valid. TemplateBox always passes a structure matching the requested schema.
  • Flat structure.
  • Prepared for future changes. Adjustments to the LUA module can be made to support future changes. The power of control remains at Commons.
  • Inserting redundant information can be avoided.
  • Template traditionally used at Commons.
Issues
  • Grouping sets is currently not supported in the "historic table". Set labels are not supported to be multilingual (ideas how one could achieve this are truly welcome).
Example
{{TemplateBox

  | useTemplateData = 1
  | 1 = artist
  | 1aliases = Artist
  | 1label-en = Artist
  | 1type = string

  <!-- used as the parameter description in the main parameter area of the documentation -->
  <!-- and in the template data section unless overridden with 1d-td-langcode -->  
  | 1d-de = Künstler, der das ursprüngliche Kunstwerk geschaffen hat.<br/>Benutze möglichst immer {{Creator:Vorname Nachname}} mit der Vorlage {{Tl|Creator}}.
  | 1d-en = Artist who created the original artwork.<br/>Use {{Creator:Name Surname}} with {{Tl|Creator}} template whenever possible.
  | 1d-fr = Artiste ou artisan à l'origine de l'œuvre.<br/>Dans la mesure du possible, utiliser le modèle {{Tl|Creator}}.
  | 1d-sv = Artist som skapade originalverket.<br/>Använd {{Creator:Förnamn Efternamn}} med {{Tl|Creator}}-mallen om detta är möjligt.

  <!-- this overrides 1d-en in the Template data section -->
  <!-- and all other translations unless each is provided as desc-td-langcode -->
  | 1d-td-en = Artist who created the original artwork; this overrides "1d-en" in the Template data section; "1d-en" is used in the template "Parameter" section.

  | 1def-de = Freifeld, angezeigt als: "{{int:wm-license-information-author}}".
  | 1def-en = blank field presented as: "{{int:wm-license-information-author}}".
  | 1def-fr = champ vide: « {{int:wm-license-information-author}} »
  | 1def-sv = tomt fält, visas som: "{{int:wm-license-information-author}}"

  <!-- used as the description of the template in the main documentation area -->
  <!-- and in the Template data section unless overridden with desc-td-langcode -->
  | desc-de = Deutsche Übersetzung der {{tl|Vorlagen}}beschreibung
  | desc-en = English translation of the {{tl|template}} description

  <!-- this overrides desc-en in the Template data section -->
  <!-- and all other translations unless each is provided as desc-td-langcode -->
  | desc-td-en = English translation that is used in the Template data section instead of "desc-en". This will also replace all desc-langcode translations, unless corresponding "desc-td-langcode" is provided.

}}

A live example is Template:Information/doc (edit that enabled TemplateData through TemplateBox, API-result showing the JSON generated by the Lua Module behind TemplateBox)

Experimenting

You can use Special:ExpandTemplates to experiment with how the template will output the template documentation and the Template data section; e.g., copy the example above and paste it into the input text on the Special:ExpandTemplates page; then click on the ok button to see the result.


Complications

( NOTE : the {{sed|1}} template links appears HERE : >>> )

edit

Boarisch: A Problem is, dåss de Vurlog koa Bearbaitung in de Abschnitt mit de bekanntn Links zualässt. Des Problem ham ma sowoi in da Vurlognhauptseitn ois å auf da Dokumentationsseitn, de då dazuakeart. Dazua kinnt no, dåss'es å de heagnommane Vurlog „TemplateBox“ betrifft. Wenn ma de Vurlog Template:Sed heanimmt, is dazu a Lösung gfundn, wia ma an am Åbschnitt werkn ko.
Deutsch: Eine Schwierigkeit ist, dass die Vorlage eine Bearbeitung in den Abschnitten mittels des bekannten Links nicht zulässt. Dies betrifft sowohl die Vorlagenhauptseite als auch dessen Dokumentationsseite. Betroffen hiervon ist ebenso die dazu verwendete Vorlage „TemplateBox“. Mittels der Vorlage Template:Sed kann hier Abhilfe geschaffen werden, wie in diesem Abschnitt geschehen.
English: A complication is that the template suppresses section editing links on the whole page of the documented template, and also on its documentation page, even for paragraphs outside the part produced by this template TemplateBox. Template:Sed can be used (as is done here) to create an edit link anyway.
Eesti: On siiski üks komplikatsioon, mille puhul mall varjab sektsiooni redigeerimise linke dokumenteeritud malli tervel leheküljel, ning samuti selle dokumentatsiooni-leheküljel, mis laieneb isegi lõikudele väljaspool selle TemplateBox malli loodud osa. Saab kasutada Template:Sed malli (nagu see siinjuures rakendatud), et ikkagi luua redigeerimislink.
Français: Une autre complication est que le modèle de la section supprime l'édition de liens sur la page entière du modèle documenté, ainsi que sur sa page de documentation, même pour les paragraphes en dehors de la pièce produite par ce modèle TemplateBox. le modèle Template:Sed peut être utilisé (comme c'est le cas ici) pour créer quand même un lien modifier (edit).
Português: Uma dificuldade, é que a predefinição suprime os links para edição de secções em toda a página da predefinição documentada, e também na respectiva página de documentação, mesmo nos parágrafos que estão fora da área produzida por esta predefinição TemplateBox. Mesmo assim, a predefinição Template:Sed pode ser usada (como se faz aqui) para forçar a criação de um link de edição.