Template:Category handler/doc: Difference between revisions

This is the {{tl|category handler}} meta-template.

This template makes it easy to choose in what namespaces a template should and should not categorize. And it makes it easy to use different categories in different namespaces. And this template uses a central blacklist where we can add pages and page types where templates should not auto-categorize.

=== Namespaces ===

:'''talk''' = Any talk space, such as page names that start with "Talk:", "User talk:", "File talk:" and so on.

:'''other''' = Any namespaces that were not specified as a parameter to the template. See examples below.

This template takes two or more parameters. Here's an example with the full template code for an article message box:

| text = This is a box used in articles.

}}{{category handler

| nocat = {{{nocat|}}}  <!--So "nocat=true/false" works-->

}}<noinclude>

</noinclude>

The above example uses the default settings for {{tlf|category handler}}. That means the box will categorize on pages in the following namespaces:  

This template takes one or more parameters named after the different page types as listed in section [[#Namespaces|namespaces]] above. By using those parameters you can specify exactly in which namespaces your template should categorize. Like this:

{{mbox

| text = This is a box for articles and talk pages.

| nocat = {{{nocat|}}}  <!--So "nocat=true" works-->

}}

== My new template ==

Hey guys, have you seen my new template?

Nice, isn't it?

--~~~~

Sometimes we want to use the same category in several namespaces, then do like this:

{{mbox

| text = This is a box used in several namespaces.

}}{{category handler

| other = [[Category:Somecat3]]  <!--For all other namespaces-->

| nocat = {{{nocat|}}}  <!--So "nocat=true/false" works-->

}}

In the above example we use a numbered parameter to feed one of the categories, and then we tell this template to use that numbered parameter for both the help and user space.

This template also has a parameter called '''all'''. It works like this:

{{mbox

| text = This is a box used in all namespaces.

| nocat = {{{nocat|}}}  <!--So "nocat=true/false" works-->

}}

The above example will categorize in all namespaces, but not on blacklisted pages. If you want to demonstrate that box on a page, then use "<code>nocat=true</code>" to prevent the template from categorizing.  

The all parameter can also be combined with the rest of the parameters. Like this:

{{mbox

| text = This is a box used in all namespaces.

}}{{category handler

| other = [[Category:Somecat3]]  <!--And add this in all other namespaces-->

| nocat = {{{nocat|}}}  <!--So "nocat=true/false" works-->

}}

If the above box is placed on an article, then it will add the categories "Somecat1" and "Somecat2". But on all other types of pages it will instead add "Somecat1" and "Somecat3". As the example shows, the all parameter works independently of the rest of the parameters.

This template understands the '''subpage''' parameter. Like this:

{{category handler

| subpage = no    <!--Don't categorize on subpages-->

| nocat = {{{nocat|}}}  <!--So "nocat=true/false" works-->

}}

If "<code>subpage=no</code>" then this template will ''not'' categorize on subpages. For the rare occasion you ''only'' want to categorize on subpages, then use "<code>subpage=only</code>". If '''subpage''' is empty or undefined then this template categorizes both on basepages and on subpages.

=== Blacklist ===

If you want a template to categorize on a blacklisted page, then feed "<code><nowiki>nocat = false</nowiki></code>" to the template when you place it on the page, thus skipping the blacklist check. Note that this template only categorizes if it has data for the namespace. For instance, if the basic syntax is used (see [[#Basic usage|basic usage]] above), then even if you set "<code>nocat = false</code>" the template will not categorize on a talk page, since it has no data for talk pages. But it has data for help space, so on a blacklisted help page it will categorize.

* If "<code>categories = yes</code>" this template categorizes even when on blacklisted pages.

{{category handler

| [[Category:Somecat]]

| categories = {{{categories|}}}  <!--So "categories=no" works-->

}}

=== The "category2" parameter ===

When adding this template to a template that already uses the "<code>category =</code>" logic, then you can do like this to not break any existing usage:

{{category handler

| [[Category:Somecat]]

| category2 = {{{category|¬}}}  <!--So "category =" works-->

}}

Note that the "<code>¬</code>" is necessary, it helps this template to detect if the '''category''' parameter is defined but empty, or undefined.

Besides from categories, you can feed anything else to this template, for instance some text. Like this:

{{tmbox

| text = This is a talk page message box.

| nocat = {{{nocat|}}}  <!--So "nocat=true/false" works-->

}}

When the template above is shown on anything else than a talk page, it will look like this (note the text below the box):

For testing and demonstration purposes this template can take a parameter named '''page'''. Like this:

{{category handler

| main = Category:Some cat

| page = User talk:Example

}}

In the above code we on purpose left out the brackets around the category names so we see the output on the page. No matter on what kind of page the code above is used it will return this:

You can make it so your template also understands the '''page''' parameter. That means you can test how your template will categorize on different pages, without having to actually edit those pages. Then do like this:

{{category handler

| main = Category:Some cat

| page = {{{page|}}}  <!--For testing-->

}}

=== Parameters ===

List of all parameters:

{{category handler

| [[Category:Somecat]]

| page  = {{{page|}}} / User:Example

}}

Note that empty values to the "main" ... "other" parameters have special meaning (see examples above). The "all" parameter doesn't understand numbered parameters, since there should never be a need for that.

=== Technical details ===