Help:TemplateData

Help:TemplateData

Introduction

TemplateData is a powerful yet often overlooked feature of MediaWiki that dramatically improves the usability and maintainability of templates. It provides a structured, machine-readable description of a template’s parameters, their data types, default values, and other important characteristics. This information is used by the VisualEditor, the editing interface that allows users to edit pages without needing to learn complex wiki markup, to present a user-friendly interface for inserting and modifying template calls. Furthermore, it assists in validating template parameters, reducing errors, and making templates more accessible to less experienced editors. This guide is designed to provide a comprehensive introduction to TemplateData for beginners. We will cover its benefits, syntax, and implementation, alongside best practices for creating and maintaining effective TemplateData definitions. Understanding TemplateData is crucial for anyone involved in creating or managing templates on a MediaWiki-based wiki.

Why Use TemplateData?

Before diving into the specifics, let’s understand why you should bother with TemplateData. Here are several key advantages:

**Improved VisualEditor Experience:** Without TemplateData, the VisualEditor often presents a raw, intimidating form for template parameters. With TemplateData, the VisualEditor can generate a structured form with labeled fields, dropdown menus, and other input controls, making it much easier for users to understand and modify template parameters. This is especially important for complex templates with many parameters. The VisualEditor’s ability to provide contextual help based on TemplateData is a significant benefit.
**Parameter Validation:** TemplateData allows you to define the expected data type for each parameter (e.g., string, number, boolean, wiki page). The VisualEditor can then validate user input, preventing errors and ensuring that the template receives the correct data. This reduces the need for manual cleanup and improves the overall quality of content.
**Documentation:** TemplateData serves as a form of documentation for your template. It clearly outlines the purpose of each parameter and its expected format. This is invaluable for other editors who need to understand how to use your template. It's a self-documenting approach that reduces the need for separate documentation pages.
**Consistency:** By enforcing a consistent structure and data type for parameters, TemplateData helps to maintain consistency across all instances of the template. This is especially important for large wikis with many templates.
**Accessibility:** TemplateData makes templates more accessible to users who are not familiar with wiki markup. It allows them to use templates without needing to understand the underlying code.
**Future-Proofing:** As MediaWiki evolves, TemplateData will likely play an increasingly important role in template handling. Investing in TemplateData now will ensure that your templates remain compatible with future versions of the software.
**Error Reduction:** By providing clear parameter definitions and validation, TemplateData significantly reduces the likelihood of errors when using templates. This saves time and effort in the long run. Think of it as a form of automated quality control.

TemplateData Syntax

TemplateData is written in a JSON-like format. It’s not *exactly* JSON, but very close. The structure consists of key-value pairs, with keys enclosed in double quotes. Here’s a breakdown of the key elements:

**`description`:** A human-readable description of the template.
**`params`:** An object containing definitions for each template parameter. Each parameter definition is itself an object.
**`paramLabels`:** An object defining human-readable labels for parameters. This helps improve the VisualEditor's interface.
**`aliases`:** An array of alternative names for the template.
**`category`:** An array of categories the template belongs to.
**`modules`:** An array of Lua modules that the template uses.
**`hooks`:** Defines hooks for custom behaviour.

Let's look at a basic example:

```wiki <templatedata> {

 "description": "Displays a simple box with a title and content.",
 "params": {
   "title": {
     "label": "Title",
     "description": "The title of the box.",
     "type": "string",
     "default": "Box"
   },
   "content": {
     "label": "Content",
     "description": "The content of the box.",
     "type": "text",
     "required": true
   }
 },
 "paramLabels": {
   "title": "Box Title",
   "content": "Box Content"
 }

} </templatedata> ```

In this example:

The `description` provides a general overview of the template.
The `params` object defines two parameters: `title` and `content`.
Each parameter has a `label` (displayed in the VisualEditor), a `description`, and a `type`.
The `title` parameter has a `default` value of "Box".
The `content` parameter is `required`, meaning the template cannot be used without it.
The `paramLabels` object overrides the default labels for the parameters in the VisualEditor.

Data Types

The `type` attribute is crucial for parameter validation. Here are the commonly used data types:

**`string`:** A text string.
**`text`:** A multi-line text string. Useful for longer content.
**`number`:** A numeric value.
**`boolean`:** A true/false value.
**`wiki-page`:** A wiki page title. The VisualEditor will provide autocompletion.
**`category`:** A category name.
**`file`:** A file name.
**`url`:** A URL.
**`date`:** A date.
**`select`:** A dropdown menu with predefined options. (See section below)
**`range`:** A numeric range with minimum and maximum values.
**`unknown`:** Used when the data type is not known or doesn't matter.

Using `select` Data Type

The `select` data type is particularly useful for providing users with a limited set of choices. Here's an example:

```wiki <templatedata> {

 "description": "Displays a colored box.",
 "params": {
   "color": {
     "label": "Color",
     "description": "The color of the box.",
     "type": "select",
     "options": [
       "red",
       "green",
       "blue",
       "yellow"
     ],
     "default": "blue"
   }
 }

} </templatedata> ```

In this example, the `color` parameter will be displayed as a dropdown menu in the VisualEditor, offering the options "red", "green", "blue", and "yellow". The default value is set to "blue".

Adding TemplateData to a Template

There are two main ways to add TemplateData to a template:

1. **Directly in the Template Page:** This is the most common and recommended approach. Add the `<templatedata>` block to the *top* of the template’s page. Make sure it’s the very first thing on the page, before any `{{#switch}}`, or other code. Example:

   ```wiki
   <templatedata>
   {
     "description": "A simple example template.",
     "params": {
       "name": {
         "label": "Name",
         "description": "The name to display.",
         "type": "string"
       }
     }
   }
   </templatedata>
   {{#switch:{{{1}}}
   |name=Hello, {{{1}}}!
   }}
   ```

2. **Using a Subpage:** You can create a subpage named `/TemplateData` on the template’s page. For example, for the template `Template:Example`, you would create a page named `Template:Example/TemplateData`. The content of this subpage would be the TemplateData JSON. This is useful for separating the TemplateData from the template code, making the template code cleaner. However, the direct inclusion method is generally preferred for simplicity.

   ```wiki
   {{#switch:{{{1}}}
   |name=Hello, {{{1}}}!
   }}
   ```

   And on `Template:Example/TemplateData`:

   ```wiki
   {
     "description": "A simple example template.",
     "params": {
       "name": {
         "label": "Name",
         "description": "The name to display.",
         "type": "string"
       }
     }
   }
   ```

Important Considerations and Best Practices

**Validation:** Always validate your TemplateData using the [TemplateData Editor](https://www.mediawiki.org/wiki/TemplateData_Editor) to ensure it’s syntactically correct. Incorrect TemplateData can cause issues with the VisualEditor.
**Completeness:** Provide TemplateData for *all* parameters, even optional ones. This ensures a consistent and user-friendly experience.
**Clarity:** Write clear and concise descriptions for each parameter. Avoid jargon and technical terms.
**Accuracy:** Make sure the data types and default values are accurate. Incorrect information can lead to errors.
**Consistency:** Use consistent naming conventions for parameters and labels.
**Localization:** Consider translating the `description` and `label` attributes into other languages to make your templates accessible to a wider audience.
**Testing:** After adding or modifying TemplateData, test the template in the VisualEditor to ensure that the changes are working as expected.
**Updates:** Keep TemplateData up-to-date as you modify the template. Outdated TemplateData can cause inconsistencies and errors.
**Use `required` judiciously:** Only mark a parameter as `required` if it *absolutely* must be provided for the template to function correctly.
**Consider using `aliases`:** If your template has parameters with names that are not intuitive, use the `aliases` attribute to provide alternative names that are more user-friendly.

Advanced Techniques

**`inherits`:** You can inherit TemplateData from another template using the `inherits` attribute. This is useful for creating variations of a template.
**`includes`:** Allows you to include TemplateData from other pages.
**Lua Modules:** For complex templates, you can use Lua modules to generate dynamic TemplateData. This provides greater flexibility and control.
**Hooks:** Hooks allow you to customize the behavior of the VisualEditor when editing templates.

Troubleshooting

**VisualEditor Not Showing the Form:** If the VisualEditor is not showing the structured form for your template, double-check that the TemplateData is valid and placed correctly (at the top of the template page or on the `/TemplateData` subpage). Clear your browser cache and try again.
**Validation Errors:** If the TemplateData Editor reports errors, carefully review the code and correct any syntax errors.
**Incorrect Data Types:** If the VisualEditor is not validating user input correctly, double-check the `type` attribute for each parameter.

Resources

[Help:TemplateData/Editor](https://www.mediawiki.org/wiki/Help:TemplateData/Editor) – The official TemplateData Editor.
[MediaWiki documentation on TemplateData](https://www.mediawiki.org/wiki/Manual:TemplateData) – Comprehensive documentation.
[TemplateData documentation on MediaWiki.org](https://www.mediawiki.org/wiki/TemplateData) – Another useful resource.
[VisualEditor documentation](https://www.mediawiki.org/wiki/VisualEditor) – Learn more about the VisualEditor and how it interacts with TemplateData.

This guide should provide a solid foundation for understanding and using TemplateData. By investing the time to create and maintain effective TemplateData definitions, you can significantly improve the usability and maintainability of your templates and contribute to a more user-friendly wiki experience. Remember to always validate your TemplateData and test your templates thoroughly.

Help:Contents Help:Templates Help:Editing Help:VisualEditor Help:Lua Template:Documentation Help:Categories Help:Files Help:Pages Help:Links

Trading and Investment Strategies

Start Trading Now

Sign up at IQ Option (Minimum deposit $10) Open an account at Pocket Option (Minimum deposit $5)

Join Our Community

Subscribe to our Telegram channel @strategybin to receive: ✓ Daily trading signals ✓ Exclusive strategy analysis ✓ Market trend alerts ✓ Educational materials for beginners