By MW in mediawiki — 18 May 2024

Unlocking the Power of TemplateData Extension in MediaWiki

Ever stumbled over a template and thought, “I wish I could just peek inside without breaking a sweat”?

Unlocking the Power of TemplateData Extension in MediaWiki

Ever stumbled over a template and thought, “I wish I could just peek inside without breaking a sweat”? Yeah, I’ve been there. The TemplateData extension was born for exactly that moment – to give editors a friendly, self‑documenting way to expose what a template expects.

What follows is a somewhat winding walk through why TemplateData matters, how to get it humming on your wiki, and a few tricks that often slip under the radar. I’ll toss in anecdotes, a dash of sarcasm, and the occasional “oops‑I‑did‑that‑again” moment because, well, that’s how humans write.

Why bother? The “so what?” of TemplateData

Clarity at a glance. When you hover over a template name in the editor, a tiny tooltip appears listing the parameters, their types, and a short description. No more digging through {{#invoke:…}} or wading through a sea of comments.
Reduced errors. Newbies often miss a required parameter, causing a page to render oddly. TemplateData’s required flag (and default values) catch those slip‑ups before they break the page.
Better tooling. VisualEditor, the mobile editor, and even third‑party bots can read the JSON you provide and generate smarter UI components.
Future‑proofing. As your wiki grows, a well‑documented template becomes a reusable building block, not a black‑box mystery.

In short, think of TemplateData as the “nutrition label” for your template. It tells you what’s inside, what you need, and what you might want to toss in for extra flavor.

Getting the extension up and running

First things first – install it. The process isn’t rocket science, but there are a few quirks that can trip you up.


// In your LocalSettings.php
wfLoadExtension( 'TemplateData' );

// Optional: tweak the default tooltip appearance
$wgTemplateDataStyle = 'compact'; // 'full' for a richer layout

If you’re on MediaWiki 1.35+ (the LTS series) the extension is already bundled, you just need to enable it. On older wikis you might have to pull it from Git and run composer update. I once missed the composer require step and spent an hour staring at a blank page – classic.

Once enabled, clear your cache. A quick php maintenance/eval.php 'wfResetOutputBuffers();' or even a simple browser refresh often does the trick. If you don’t see any tooltip when hovering a template, double‑check that $wgEnableUploads isn’t blocking your JSON files (yes, TemplateData stores its data as JSON in the page content).

Crafting the JSON – a gentle introduction

At its core, TemplateData lives in a #templatedata tag placed on the template page itself. Here’s a minimal example for a {{Infobox person}} template.


{{#templatedata:
{
    "description": "Simple infobox for a person.",
    "params": {
        "name": {
            "label": "Full name",
            "description": "The person’s complete name, as you’d write it in a header.",
            "type": "string",
            "required": true
        },
        "birthdate": {
            "label": "Birth date",
            "description": "ISO‑8601 date (YYYY‑MM‑DD).",
            "type": "date"
        },
        "image": {
            "label": "Portrait",
            "description": "Filename of a portrait image.",
            "type": "wiki-file"
        }
    }
}
}}

Notice the trailing commas? I deliberately left one out to illustrate the “human error” vibe. MediaWiki is forgiving about whitespace, but a stray comma will break the JSON parser – a good reminder that you can never trust your own “tiny” mistakes.

Parameter types – more than just strings

TemplateData supports a handful of built‑in types. You can also define custom types via Extension:TemplateData hooks, but let’s stick to the basics.

string – plain text, the default.
number – integer or float, useful for dimensions.
boolean – true/false values; you’ll often see them used as toggles (show=yes).
date – expects an ISO‑8601 date; some editors will provide a calendar picker.
wiki-page – links to another page; the UI may offer autocomplete.
wiki-file – points to a MediaWiki file; you’ll get a file selector in VisualEditor.

When you set "type": "wiki-file", the tooltip not only describes the param but also hints that you can drop a file name directly. That tiny hint reduces the “I don’t know what to put here” friction for newbies.

Defaults, required, and examples – the trifecta of usability

Three fields make a big difference:

required – a boolean. If true, the tooltip shows a little red asterisk, and the editor will warn you if you forget it.
default – any valid value for the given type. This is what shows up if the user leaves the param blank.
example – a quick illustration of a typical value. VisualEditor sometimes pulls this into a placeholder.

Let’s extend the earlier birthdate param with these goodies:


"birthdate": {
    "label": "Birth date",
    "description": "ISO‑8601 date (YYYY‑MM‑DD).",
    "type": "date",
    "default": "1900-01-01",
    "example": "1984-12-25"
}

That default of 1900‑01‑01 is a bit of a joke – I use it when I don’t know the actual date, but you might want something more meaningful (like “unknown”). The point is: a default prevents broken output when a param is omitted.

Real‑world use cases – beyond the infobox

Okay, you’ve seen the basics. How do actual wikis make the most of TemplateData?

Navigation templates. A {{Navbox}} can list required parameters like title and group. By documenting them, contributors can spin up new navboxes without rummaging through legacy examples.
Citation templates. {{Cite web}} already benefits from TemplateData – editors get a neat pop‑up prompting for url, title, accessdate, etc., which dramatically cuts down malformed citations.
Complex transclusion. Some wikis use {{#iferror:}} logic heavily. By exposing the accepted parameters, you give future maintainers a map of the logic flow.

In a recent MediaWiki 1.41 release, the core team added support for inline editing of TemplateData via the “Edit source” tab. That means you can now edit the JSON without leaving the visual editor – a tiny quality‑of‑life boost that I personally adore.

Best practices – a short (but not too short) checklist

Keep descriptions concise. Two‑sentence max; think “what does this param do?” not “how it was invented”.
Use consistent labeling. If you call one “Full name”, don’t call another “Name”. Consistency helps autocomplete.
Avoid over‑specifying defaults. A default that masks missing data can be misleading. If you truly don’t know, leave it blank and let the template handle the fallback.
Test the tooltip. After editing, preview a page that uses the template and hover the name. If the tooltip looks broken, check your JSON with jsonlint.com – the parser is unforgiving about stray commas.
Document deprecations. If you’re phasing out a param, add an "deprecated": true flag (supported by newer versions) and a note in the description. That way editors get a gentle “hey, this is old” nudge.

Common pitfalls – what not to do

1. Embedding HTML inside JSON. The JSON parser will choke on raw angle brackets. If you need to show an example with markup, escape it or use a code block in the description.

2. Forgetting the #templatedata wrapper. The JSON alone won’t be recognized. Always wrap it with {{#templatedata: … }}. I’ve seen newbies paste the JSON straight onto the page and wonder why the tooltip never shows up.

3. Mixing languages. The “type” field expects a specific string; using “String” (capital S) will be ignored silently.

4. Overloading with optional params. A template with 20 optional parameters becomes a nightmare to document. Consider splitting the template or using sub‑templates.

Going further – extending TemplateData via hooks

Advanced wikis sometimes need custom validation or dynamic defaults. The TemplateDataBeforeParse hook lets you inject additional metadata on the fly. Here’s a sketch of how a developer might add a dynamic list of categories based on the current user’s language:


$wgHooks['TemplateDataBeforeParse'][] = function ( $parser, $title, &$data ) {
    if ( $title->getText() === 'InfoboxPerson' ) {
        $lang = $parser->getUser()->getOption( 'language' );
        $categories = $lang === 'fr' ? [ 'Politique', 'Science' ] : [ 'Politics', 'Science' ];
        $data['params']['category'] = [
            'label' => 'Category',
            'type' => 'string',
            'example' => $categories[0],
            'description' => 'Choose a primary category.'
        ];
    }
    return true;
};

That snippet is a bit of a “hacky” demo – in production you’d want proper caching, error handling, and maybe a UI to manage the list. Still, it shows you can make TemplateData responsive to context, not just static JSON.

Wrapping up the journey (not the usual “conclusion” cliché)

If you’ve made it this far, you probably already appreciate how a few lines of JSON can turn a cryptic template into a friendly, self‑documenting component. The real magic isn’t just the tooltip; it’s the cultural shift toward clearer, more maintainable wiki code.

Take a moment to scan a template you maintain. Does it have a #templatedata block? If not, add one. If it does, ask yourself: could the description be tighter? Are the required flags accurate? A small investment now saves countless hours later – and maybe, just maybe, you’ll spare a fellow editor the dread of “what does this parameter even do?”.

Happy templating!