Module:Format TemplateData/doc explained

Format TemplateData – Module with auxilary functions for template documentation, especially by TemplateData.

Core functionality is improved presentation on documentation pages.

__TOC__

Improve template documentation page – MediaWiki disappointing

For presentation of template depiction in VisualEditor agreement was made to abandon all markup and clickable links, permitting all tooltips in all environments. Basically this is reasonable, albeit tooltips with markup and clickable links are supported as HTML application for decades now and JavaScript is present anyway when VisualEditor is used.

This state is indefensible.

Improved presentation

In addition to the simple syntax supported by MediaWiki and presented in the VisualEditor, the following features can be added to the JSON code for the template documentation page. They affect the elements classified as InterfaceText, but are only useful for description fields.

Wikilinks (internal format)

External links (URL format)

Apostrophs ' for italic and bold

HTML entities

HTML tags

<noexport></noexport>

Templates

More effects

Eliminate disadvantages

Two aspects were found to be particularly disturbing in 2013–2017:

  1. Even if no parameters at all were defined, a table head is always displayed for a table without content. Even more, this is sortable.
    • A reduction was rejected with . A sortable table of the parameters would be always necessary, even if the table has no rows at all and consists only of the header row.
    • This ridiculous statement led to the development of this module in 2016.
  2. Even if the context does not permit that default values or even AutoValue specifications will be defined ever, a content-free six-line definition list is output for each individual parameter value.
    • / / /
    • MediaWiki did not even deign to answer the disastrous documentation page situation.

The general comments show that MediaWiki only regards the presentation of TemplateData specifications in the VisualEditor as important. However, someone has to program and maintain the templates and someone needs to generate the template description and make it manageable beside the functionality in the VisualEditor form, but that is beyond ken.

General workflow

Functions for templates

Details

f
  • Improve TemplateData-presentation; used in
  • Parameters of template transclusion environment (all optional):
    1
  • JSON string or <templatedata> object
    JSON
  • JSON string
  • (precedes 1)
  • Transition from &lt;templatedata> objects with pipe symbols needs special attention: Pipes are to be represented as <nowiki>{{!}}</nowiki>, on double curly brackets one should be encoded by HTML entity.
    TOC
  • 1 – Insert table of contents after general purpose descriptions; but before parameter list, if present
  • Example
    lang
  • Language code according to ISO 639 etc.
    lazy
  • 1 – Presentation only, do not generate an effective data block
  • For general method descriptions.
    debug
  • 1 – developer mode
    source
  • 1 – show effective JSON source text (after template expansion) for debugging
  • Parameters of #invoke for particular project adaption (all optional):
    lang
  • Language code according to ISO 639 etc.
    debug
  • Development mode, if provided and not equal 0
    cat
  • Title of a maintenance category on invalid parameter value etc.
  • Deprecated – use configuration module
    docpageCreate
  • Pattern for creation of subpage names; %s/Doku
  • Deprecated – use configuration module
    docpageDetect
  • Pattern for recognition of subpage names; /Doku$
  • Deprecated – use configuration module
    msgDescMiss
  • Localisation: complaint text on missing description
  • Deprecated – use configuration module
  • Returns: HTML code; and/or error message, probably with class="error"
    failsafe
  • Version management

    Functions for Lua modules (API)

    Some functions described above can be used by other modules:local lucky, TemplateData = pcall(require, "Module:Format TemplateData")if type(TemplateData)

    "table" then TemplateData = TemplateData.TemplateDataelse -- failure; TemplateData is the error message return "

    " .. TemplateData .. ""end
    TemplateData.failsafe(atleast)
    1. atleast
      optional
      nil or minimal version request or "wikidata"

    Returns: string or false

    TemplateData.getPlainJSON(adapt)
  • Reduce enhanced JSON information to MediaWiki JSON
    1. adapt
      string, with JSON (enhanced)

    Returns: string, with JSON (MediaWiki)

    TemplateData.test(adapt, arglist)
  • Simulation of template functionality
    1. adapt
      table, #invoke parameters
    1. arglist
      table, template parameters

    Returns: string

    Usage

    Currently focussing on one template only:

    Configuration

    A local module, if present, facilitates adaptions to the local project.

    A table is expected via mw.loadData. The following entries are optional components:

    catProblem
  • Title of a maintenance category on invalid parameter value etc.
    classNoNumTOC
  • Name of class for the table of contents; especially to suppress numbering.
  • nonumtoc
    classTable
  • table with classes for the table of parameters.
  • { "wikitable" }
    cssParams
  • table with CSS assignments for formatting of single parameters
    cssParWrap
  • table with CSS assignments for formatting of the entire parameter table
    docpageCreate
  • Pattern for creation of subpage names; %s/Doku
  • %s/Doku
    docpageDetect
  • Pattern for recognition of subpage names; /Doku$
  • /Doku$
    help*********
  • Link targets for context sensitive help on details
    helpBoolean
  • helpContent
  • helpDate
  • helpFile
  • helpFormat
  • Link target on help about wikitext transclusion layout
    helpLine
  • helpNumber
  • helpPage
  • helpString
  • helpTemplate
  • helpURL
  • helpUser
  • msgDescMiss
  • Localisation: complaint text on missing description
    permit
  • table with specification of properties for a single parameter; components:
    boole
  • table with specification for boolean presentation
  • Two components true and false – each one table:
    css
  • table with CSS for this explanation of the value
    lead
  • true – show explanation for 0 or 1 respectively preceding the value
  • false – show explanation for 0 or 1 respectively following the value
    show
  • explanation; string or false to suppress
    css
  • table with specifications for rendering of the parameter table; components:
    tablehead
  • table with CSS for table head
    required
  • table with CSS for required
    suggested
  • table with CSS for suggested
    optional
  • table with CSS for optional
    deprecated
  • table with CSS for deprecated