Starfleet Logistics:Category suppression

Many userboxes and other templates automatically add the pages on which they appear to various categories. This feature is not always desirable, and the process of disabling or suppressing automatic categorization is referred to as category suppression in templates. This document describes a few different methods of suppressing automatic categorization and provides examples for each method. There are no policies or strict guidelines regarding category suppression; however, this document describes the de facto methods used to implement category suppression on the English Starfleet Logistics.

Background information

Many templates and userboxes are designed to automatically add pages into one or more categories. There are many reasons why this might be beneficial. Userboxes can group users in various Starfleet Logisticsn categories based on interests. WikiProject headers group related pages to make it easier for WikiProject members to locate them. Other templates flag articles for certain actions by adding the articles to administrative categories.

This can be a really useful and powerful feature, but it can also be a little confusing if someone wants to display the template somewhere other than where it was originally intended, such as on a help page or in a template gallery. The help page or gallery would be flagged like any other page on which the template appears, and this is often not desirable. It is unlikely that a page demonstrating a deletion template should be flagged for deletion itself. Also, users may wish to place the same userbox on more than one of their pages, but probably do not wish to have each page listed multiple times in the related categories. It is preferable to suppress the automatic categorization of the page in that instance. This is referred to as category suppression.

Within the template itself, it is fairly easy to suppress such categorization problems using the <includeonly> and <noinclude> markup. However, those features do not help when displaying the template as an example on a help page or in a gallery.

At the expense of a little extra processing on the server and making the template code a little bit more difficult for humans to read, templates or a simple parser function can suppress automatic categorization in certain namespaces or anywhere when particular template attributes are used.

Several different methods of category suppression developed simultaneously over the years, so there is no single or "best" method of achieving category suppression. Some methods work better in some situations and other methods work better in other situations. Template designers are free to choose from any of the following methods to suppress automatic categories, but are requested to clearly document which method is used within the template documentation. As of May 17, 2009, new templates are requested to follow the preferred techniques (when multiple techniques achieve the same result). Older templates that are not heavily used can also be modified to use the preferred techniques, too. It is not worthwhile to adapt heavily used templates to use the preferred techniques, unless there is another compelling reason to modify the template.

Usage

Templates that use namespace-based suppression do not require any configuration by an editor to suppress automatic categorization outside of the intended namespace (e.g., article templates will not categorize talk pages or user pages).

Attribute-based suppression templates use either |nocat=true (preferred) or |categories=no (alternative) to suppress automatic categorization. Anywhere that categorization should be suppressed, just add |nocat=true or |categories=no as the last attribute for the template, and (assuming the template is implemented correctly), the template will not add the page to any categories. Refer to the documentation for each template to determine which of the two attributes to use.

Category suppression methods

Category suppression techniques fall into the following methods:

1. Based on the namespace of the page, categorization is enabled or suppressed
2. Template attributes are passed to the template to specifically suppress automatic categorization of pages
3. Blended suppression uses both of the other methods together to meet complex needs
4. Using a blacklist of pagenames that should not be categorized - e.g. see Template:Category handler

Namespace-based suppression

Overview

Templates designed to be added only to certain types of pages (articles, talk pages, categories, other templates, project pages, etc.) are likely to benefit from this method the most. Using this method, templates can automatically detect the type of page they are on, and only categorize pages that are in the correct namespace. For example, a template that flags articles needing additional references can use this method to only categorize articles and suppress categorization everywhere else the template appears, such as on template documentation pages.

Pros

• Very simple method of category suppression for templates that should only categorize a single namespace
• Easy to add the feature to a template
• Does not rely upon anyone remembering to add special attributes

Cons

• May not be a good choice for templates than can be used in more than one namespace
• Multiple namespace support is more difficult to implement correctly
• Editors may not be as familiar with this method as they are using attributes

Examples are given below.

Attribute-based suppression

Overview

Automatic categorization is always turned on in these templates by default. Any page on which the template appears is automatically categorized unless one of two special attributes is passed to the template. This is a good choice for templates that are used across multiple namespaces. For example, a typing-aid template that could be used in articles, talk pages, project pages, user pages, and portals might be a good choice.

Pros

• Simple and familiar method of suppressing automatic categorization upon explicit request by a page editor
• Easy to add the feature to a template
• Works across all namespaces

Cons

• Relies upon editors to remember to suppress automatic categorization on pages where category suppression is desired
• May not be the best choice for templates designed for a single namespace

Examples are given below.

Blended suppression

Overview

This is the most versatile and complicated method of suppressing categories. Using both of the previous techniques, you can combine namespace-based default categorization/suppression with attributes to change the default action on a case-by-case basis. This should not be necessary for most templates, but may be useful in some of the more complex meta-templates that combine features from several related templates into a single, large template. It adds an extra degree of difficulty in designing and maintaining the template that should only be considered for templates that are already complex (and unlikely to be edited by novice templaters) or where the two previous techniques do not provide enough control.

Pros

• Incredibly flexible and dynamic
• Complete control over both defaults and exceptions for automatic categorization and suppression
• Meta templates can support older templates designed using a variety of category suppression methods

Cons

• Additional complexity makes it difficult for less-experienced templaters to maintain
• Easy to misconfigure, which could result in widespread miscategorization or visible template errors across multiple pages
• The logic of the automatic categorization and suppression may not be obvious without clear documentation

Examples are given below.

Category suppression examples

Namespace-based suppression examples

This method is automatic and needs no parameter to invoke the suppression.

Using the {{Main other}} family of templates

• For automatic categorization of articles (main space) and category suppression everywhere else:
  • {{Main other|[[Category:Example]]|<!-- Don't categorize when not in main (article) space. -->}}
• For all talk pages (Talk:, User talk:, File talk:, and other talk namespaces):
  • {{Talk other|[[Category:Example]]|<!-- Don't categorize when not in talk space. -->}}
• For template pages (Template: namespace):
  • <includeonly>{{Template other|[[Category:Example]]|<!-- Don't categorize when not in template space. -->}}</includeonly>

If your template categorizes in template space, then you need to surround the categorization code with <includeonly></includeonly>, otherwise your template itself will be categorized.

There are also {{user other}}, {{Starfleet Logistics other}}, {{file other}}, {{help other}}, {{category other}} and {{portal other}} to handle the other namespaces.

Using the {{Namespace detect}} template

If automatic categorization/suppression is desired in multiple namespaces or if you need different categories to be used in different namespaces, use the powerful {{Namespace detect}} template:

<includeonly>{{Namespace detect
| main = [[Category:Article category]]
| talk = [[Category:Talk category]]
| template = [[Category:Template category]]
| other = <!-- Don't categorize when not in main, talk, or template space --> }}</includeonly>

Using parser functions

Using the {{Main other}} family of templates is the easiest way to enable namespace-based category suppression, but you can also use the #ifeq or #switch parser functions to accomplish the same thing.

• Here is a simple example for automatic categorization of articles (Main namespace) and category suppression everywhere else using the #ifeq parser function:

{{#ifeq:{{NAMESPACE}}|{{ns:0}}|[[Category:Article category]]|<!-- Don't categorize when not in main (article) space. -->}}

• Another example of automatic categorization/suppression in multiple namespaces with different categories using the #switch parser function:

<includeonly>{{#switch:{{NAMESPACE}}
| =[[Category:Article category]]
| Talk = [[Category:Talk category]]
| Template = [[Category:Template category]]
| #default = <!-- Don't categorize when not in main, talk, or template space --> }}</includeonly>

Attribute-based suppression examples

The following technique is the recommended standard technique for the attribute-based category suppression method.

• Use |nocat=false to enable automatic categorization (in cases where the default would be to suppress it)
• Use |nocat=, |nocat=true, or |nocat=anything else to suppress categorization

In other words, setting "nocat" to anything other than "false" (even to nothing) will result in no categorization.

Unfortunately, category suppression attribute names were not previously standardized, resulting in several variations. The following attribute names that are commonly used to indicate when category suppression should be performed are:

• |nocat=true — the recommended standard technique
• |categories=no — does the same thing but is no longer the recommended attribute
• |category= — an alternative method but not recommended for most situations (reasons discussed below)

An example using |nocat= where the default is to automatically categorize

<includeonly>{{#ifeq: {{lc:{{{nocat|false}}}}} | false |
[[Category:Example]]
|<!-- Category suppressed -->}}</includeonly>

• The {{#ifeq: {{lc:{{{nocat|false}}}}} is a parser function that determines the answer to the question, "Was an attribute named nocat passed to this template?" If not, it assumes a default value of "false".
• The next part, | false |, compares the value of nocat to false to see if they match (i.e., if nocat was explicitly set to false or defaulted to false). A match would indicate that category suppression should not be disabled (i.e., automatic categorization should take place).
• If there is a match, then display the category or categories entered between the pipe symbols ("|").
• Remember to change the category name "Example" to the correct category. You may add more than one category if appropriate.
• The pipe symbol and HTML comment (|<!-- Category suppressed -->) are optional information to help editors understand what the template is doing, but may be omitted to save space and bandwidth.
• The final braces (}}) end the parser function.

An example using |categories=no to suppress categorization

<includeonly>{{#ifeq: {{lc:{{{categories}}}}} | no ||
[[Category:Example]]}}</includeonly>

• The {{#ifeq: {{lc:{{{categories}}}}} | no is a parser function that determines the answer to the question, "Was an attribute named categories passed to this template with the value set to no?" (lc: converts all text to lowercase for easier matching)
• The next part, ||, displays nothing (i.e., it suppresses the category) if the answer to that question is true.
• The rest is the code normally used to display the category, but it only appears if the answer to the question is false (i.e., there was not such an attribute set to no).
• Remember to change the category name "Example" to the correct category.
• The final }} ends the parser function.

Implementation notes

• |nocat=true and |categories=no were designed to accomplish the same thing, but their apparent logic is reversed (one uses "true" and the other uses "no", yet both enable category suppression). Since |categories=no is less obvious (it relies upon negation to enable a feature), and since some templates use an attribute named "categories" for other purposes, "|nocat=" is the preferred attribute name to use for this feature in all new templates (and older ones if someone is willing to go back and update the older templates).
• Templates designed prior to May 17, 2007 that used |nocat= may work a little differently than described here. They may only recognize "|nocat=true", and other values might be misinterpreted.
• Older templates may not use the lc: parser function to force attribute values to all lowercase characters for easier matching; therefore, it is recommended that editors always use lowercase values to be safe.

The category= attribute

|category= is used by some templates to avoid having to use the #ifeq parser function. Since the attribute name "category" is commonly used for other purposes in many templates (as is "categories" to a lesser degree), "category" is not a recommended attribute name for this purpose. For that reason and others, this technique is not discussed here. Note that |nocat= can serve exactly the same purpose and is the recommended alternative.

Blended suppression examples

Blended suppression combines both attribute-based and namespace-based suppression methods within a single template. Because it combines both methods, the complexity is doubled. Please be sure that you fully understand both of the other methods before attempting to use the blended method in a template.

There are multiple ways that blending can be accomplished. The following example is the way that Willscrlt prefers to implement blended suppression (which should work for most cases and is recommended for consistency).

The process is to first check for attributes that would indicate that categories should be suppressed. If category suppression is requested by the attribute, it overrides any default categorization based on the namespace. If no attribute specification is found, then use the default categorization based on the namespace. If the attribute explicitly requests category suppression not be used, then use the default categorization based on the namespace, unless the default is to not categorize. If the default is to not categorize, then use the demospace attribute to override the default and display the category anyway. Together, these options give template developers considerable control over automatic categorization and category suppression at the expense of more complex template code.

A complete example

<includeonly>{{#ifeq: {{lc:{{{nocat|false}}}}} | false |
{{Namespace detect
| main = [[Category:Article category]]
| talk = [[Category:Talk category]]
| template = [[Category:Template category]]
| other = {{#ifeq: {{lc:{{{nocat|false}}}}} | true |
[[Category:Other category]]
| <!-- Unless nocat=true, don't categorize when not in main, talk, or template space --> }} }}
|<!-- Category suppressed by nocat attribute -->}}</includeonly>

• The {{#ifeq: {{lc:{{{nocat|false}}}}} is a parser function that determines the answer to the question, "Was an attribute named nocat passed to this template?" If not, it assumes a default value of "false".
• The next part, | false |, compares the value of nocat to false to see if they match (i.e., if nocat was explicitly set to false or defaulted to false). A match would indicate that category suppression should not be disabled (i.e., automatic categorization should take place).
• If there is a match, then the namespace is determined using the {{Namespace detect}} template.
  • If the page is in the main (article) namespace (| main = ), categorize the page under [[Category:Article category]].
  • If the page is in any of the talk namespaces (| talk = ), categorize the page under [[Category:Talk category]].
  • If the page is in the template namespace (| template = ), categorize the page under [[Category:Template category]].
  • If the page is in any other namespace (| other = ), the categorization depends on the value of nocat.
    • If nocat is explicitly set to "true" ({{#ifeq: {{lc:{{{nocat|false}}}}}), then categorize the page under [[Category:Other category]].
    • Otherwise, display nothing other than an optional HTML comment (the pipe symbol and HTML comment (| <!-- Unless nocat=true, don't categorize when not in main, talk, or template space -->) are optional information to help editors understand what the template is doing, but may be omitted to save space and bandwidth)
• If there is no match, then display nothing other than an optional HTML comment (the pipe symbol and HTML comment (|<!-- Category suppressed by nocat attribute -->) are optional information to help editors understand what the template is doing, but may be omitted to save space and bandwidth)
• Remember to change the various category names ("Article category", "Talk category", "Template category", "Other category") to appropriate categories. You may add more than one category if appropriate.
• {{Namespace detect}} understands many more namespaces than shown here, and you can use whichever namespaces are appropriate for your situation. The "main", "talk", and "template" namespaces shown here are only examples of how you can use this feature.

Supporting older implementations in meta templates

If you are attempting to create a meta template (a template that combines the features of two or more templates into a single template), you may need to support more than one method of category suppression, because editors may use different methods of requesting category suppression depending on the original template syntax.

The following method checks for either of the two common attributes (|nocat=true and |categories=no) and suppresses automatic categorization if either is set to suppress.

<includeonly>{{#ifexpr: {{
#ifeq: {{lc:{}}} | true | 1 | 0 }} + {{
#ifeq: {{lc:{{{categories|yes}}}}} | no | 1 | 0 }} < 1 |
[[Category:Example]]
|<!-- Category suppressed -->}}</includeonly>

• The {{#ifexpr:}} is a parser function that evaluates an arithmetic expression (like "0+0=0" or "1+0=1"). In this case it evaluates the output of two other parser functions.
  • The first function checks if nocat was set explicitly to "true". If it was, the output is the number one. Otherwise, the output is zero.
  • The second function checks if categories was set explicitly to "no". If it was, the output is the number one. Otherwise, the output is zero.
• The #ifexpr function adds the output of the two functions together (possible results are zero [0+0=0], one [1+0=1 or 0+1=1], or two [1+1=2]).
• If the result is less than one (i.e., neither attribute was set to suppress automatic categorization), then the categories are displayed.
• If the result was greater than or equal to one, then display nothing other than an optional HTML comment (the pipe symbol and HTML comment (|<!-- Category suppressed -->) are optional information to help editors understand what the template is doing, but may be omitted to save space and bandwidth)

See also

• Starfleet Logistics:WikiProject Category Suppression
• mw:Help:Extension:ParserFunctions
• mw:Help:Parser functions in templates
• mw:Help:Templates