Template:TemplateBox

Template documentation[ view · edit · history · purge ]

This documentation is transcluded from Template:TemplateBox/doc.

Warning:

This page is shared between multiple wikis. All changes to this page will be automatically copied to all wikis listed in the left side bar.

Tracked in Phabricator
Task T54966
RESOLVED

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

Usage

Usage notes: For a copy-paste form with short parameter descriptions see section Usage – with short parameter descriptions

The template takes no parameters.

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:Languages
• Module:TemplateBox
• Module:TNTTools
• {{Documentation subpage}}

See also

• Commons:Template documentation
• Commons:TemplateData
• Template:Documentation/preload10
• Template:Documentation/preload20
• Template:Documentation/preload30
• {{Documentation}}
• {{Doc-inline}}, {{doc-end}}

Localization

This template makes use of {{Autotranslate}} and the translate extension. The layout of the template can be found under Template:TemplateBox/layout.

Translate this template now!

 Administrate translations.

Usage – with short parameter descriptions

• Standard form for copy & paste with comments explaining shortly each parameter
• Additional comments and space for categories is included so it can work as a complete copy paste form for new doc pages.
• The parameter names are without language code:

<!-- Add categories where indicated at the bottom of this page and interwikis at Wikidata -->
{{TemplateBox
 <!-- TEMPLATE PARAMETERS SECTION (for 2nd parameter copy paste & change "1" → "2") -->
 |1          = <!-- 1st parameter: name of the first parameter the template takes-->
  |1label    = <!-- 1st parameter: label, very brief name, preferably less than 20 characters -->
  |1d        = <!-- 1st parameter: description (+LANGUAGE CODE) -->
  |1d-td     = <!-- 1st parameter: description for TemplateData without any wiki markup (+LANGUAGE CODE) -->
  |1aliases  = <!-- 1st parameter: alternative names that may be used, separated by "/" -->
  |1type     = <!-- 1st parameter: type (values: number, string, line, boolean, date, url, wiki-page-name, unknown/…) -->
  |1set      = <!-- 1st parameter: set ID / Label (to group multiple parameters in a set) -->
  |1def      = <!-- 1st parameter: fixed default value (+LANGUAGE CODE) -->
  |1av       = <!-- 1st parameter: autovalue, dynamically-generated default value, e.g. current year -->  
  |1sv       = <!-- 1st parameter: suggested values to help users select the desired value, separated by "/" -->  
  |1stat     = <!-- 1st parameter: status (values: required, optional, optional- or deprecated) -->
 <!-- TEMPLATE SECTION -->
 |useTemplateData    = <!-- expose TemplateData (values: true, export; default: false) -->
 |name               = <!-- template title -->
 |desc               = <!-- template description (+LANGUAGE CODE) -->
 |namespace          = <!-- namespaces, the template is intended to be used (values: all, File, Category,…) -->
 |usergroup          = <!-- usergroup that is meant to use the template (values: all, admin,…) -->
 |placement          = <!-- placement on the page (values: top, bottom, licence or source) -->
 |usage-notes        = <!-- notes about the correct usage of the template -->
 |type               = <!-- template type (values: infobox, formatting, licence tag,…) -->
 |example            = <!-- example value for one (unnamed) parameter -->
 |example-value      = <!-- example use of the template with the value of the example parameter -->
 |i18n-method        = <!-- translation method (values: mediawiki-msg, ext.translate, autotranslate,…) -->
 |i18n-desc          = <!-- translation info -->
 |i18n-mediawiki-msg = <!-- name of the message when using “mediawiki-msg” as method -->
 |i18n-subpage       = <!-- translation subpage when using "ext.translate" as method -->
 |i18n-data-file     = <!-- tabular data file on Wikimedia Commons in the Data namespace -->
 |seealso            = <!-- relevant links (each of them on a new code line with * in the beginning) -->
 |setscats           = <!-- categories which are automatically set by the template -->
 |print              = <!-- template code layout in the Usage-section (values: one, multi, infobox) -->
 |shorthand          = <!-- redirects to the main template -->
 |relieson           = <!-- list of templates on which the template's basic functionality relies -->
 |mustbesubst        = <!-- set to yes (or any value) if the template must be substituted. -->
 |docsub-page        = <!-- page parameter from {{Documentation subpage}} -->
}}<includeonly>{{Sandbox other||
<!-- Categories below this line; interwikis at Wikidata -->

}}</includeonly>

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

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.