Template:Category handler/doc

This template is a metatemplate. It is used to build other templates and should not be used standalone, except for testing or simple usage. This template is implemented by the Lua module Module:Category handler.

This template invokes the following functions: category_handler from Category handler.

This documentation is for a ready template. This message indicates that a template is ready for use, or has recently been repaired. This message may be removed once this template has been used on several pages or once it is verified to work as intended. Details: Functionally complete. See its corresponding module for more details.

Template:Category handler is intended as a metatemplate that helps templates categorize pages. It also suppresses categories depending on the namespace or subpage.

Usage

Categories are entered as unnamed parameters, as shown.

{{Category handler | cat 1 | cat 2 | cat 3 }}

For example, the code below

{{Category handler | Abstract MOS patterns | 8-tone scales}}

categorizes the page under the following categories.

[[Category:Abstract MOS patterns]][[Category:8-tone scales]]

For testing purposes, categories can be turned off by adding debug=1. Modifying the previous example

{{Category handler | Abstract MOS patterns | 8-tone scales | debug=1 }}

disables categories.

Typically, this template is used as part of another template, so use something like debug={{{debug|}}}, so that debug=1 can be added to an instance of that template.

Category suppression rules and use-cases

By default, this metatemplate allows categories within the following namespaces: main, file, mediawiki, template, category, and module. Templates placed outside of those namespaces will not categorize those pages. Additionally, pages with the suffix /doc or /sandbox will not be categorized.

This metatemplate is meant primarily for templates used within those namespaces. Use of this metatemplate is not required for templates with basic categorizing rules, or templates meant to be placed within other namespaces, such as the user namespace. Additionally, specialized templates, such as those meant for categorizing /doc pages, are unable to work with this template.

Changing suppressed namespaces

This template can be adjusted to allow or disallow suppression in different namespaces. The example below allows a template to add categories a page within the user namespace, but not templates or modules. Namespaces are delimited using either newlines or semicolons.

{{category handler | allowed_ns = user | excluded_ns = template; module}}

Use-case: templates that categorize templates

Templates are sometimes added to template documentation, such as Template:Todo, which categorizes that page under a specific todo-task. Typically, such templates are added to a template's /doc page to be transcluded onto that template's page, instead of within the <noinclude></noinclude> block of a template's page.

For example, adding {{Todo|inline=1|add documentation}} to a template's documentation adds that template to Category:Todo:add documentation, but a naïve implementation of that template will also categorize that template's /doc subpage.

{{#if: {{{inline|}}} | {{Mbox
| type = notice
| icon = Icon-Todo.png
| text = '''Todo:''' {{#if: {{{1|}}}| {{{1}}} }}
{{#if: {{{comment|}}}}}
}}
}}
{{#if: {{{1|}}} | [[Category:Todo:{{trim|{{{1}}}}}]] | [[Category:Todo]] }}

If placed on the /doc subpage for a template called SomeTemplate, the todo-category will contain these pages:

• Template:SomeTemplate (template page)
• Template:SomeTemplate/doc (template's documentation)

Since this template suppresses categories on /doc subpages, adding this template to Template:Todo prevents it from categorizing the documentation page, so only Template:SomeTemplate is categorized.

{{#if: {{{inline|}}} | {{Mbox
| type = notice
| icon = Icon-Todo.png
| text = '''Todo:''' {{#if: {{{1|}}}| {{{1}}} }}
{{#if: {{{comment|}}}}}
}}
}}
{{category handler | {{#if: {{{1|}}} | Todo:{{trim|{{{1}}}}} | Todo }}}}