Module:Category handler/doc: Difference between revisions

Revision as of 21:06, 2 August 2016

Latest revision as of 18:06, 19 June 2025

(18 intermediate revisions by 15 users not shown)

Line 1:

{{moduleUsed rating|betain system}}

{{high-risk|6770000+ pages, which is {{#expr:(677125500/{{NUMBEROFPAGES:R}}) round 0}}% of all}}

{{Module rating|p}}

{{cascade-protected template|page=module}}

{{Lua|Module:Category handler/data|Module:Category handler/shared|Module:Category handler/blacklist|Module:Yesno|Module:Namespace detect|Module:Arguments}}

This module implements the {{tl|category handler}} template. The category handler template helps other templates to automate both categorization and [[Wikipedia:Category suppression|category suppression]]. For information about using the category handler template in other templates, please see the '''[[Template:Category handler|template documentation]]'''. Keep reading for information about using the category handler module in other Lua modules, or for information on exporting this module to other wikis.

Line 9 ⟶ 10:

=== When not to use this module ===

For cases where a module only needs to categorise in one of the namespaces main (articles), file (images) or category, then using this module is overkill. Instead, you can simply get a title object using [[revmw:https://www.mediawiki.org/wiki/Extension:Scribunto/Lua reference manual#mw.title.getCurrentTitle#mw.title.getCurrentTitle|mw.title.getCurrentTitle]] and check the <code>nsText</code> field. For example:

<sourcesyntaxhighlight lang="lua">

local title = mw.title.getCurrentTitle()

if title.nsText == 'File' then

-- do something

end

</syntaxhighlight>

</source>

However, if your module needs to categorize in any other namespace, then we recommend you use this module, since it provides proper category suppression and makes it easy to select how to categorize in the different namespaces.

Line 24 ⟶ 25:

:'''main''' = Main/article space, as in normal Wikipedia articles.

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

:'''user, wikipedia, file ... = The other namespaces except the talk pages. Namespace aliases are also accepted. See the table below for the full list.'''

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

Line 35 ⟶ 36:

This module takes two or more parameters. Here's an example using a hello world program:

<sourcesyntaxhighlight lang="lua">

p = {}

local categoryHandler = require( 'Module:Category handler' ).main

function p.main( frame )

local result = 'Hello world!'

Line 48 ⟶ 49:

return result .. category

end

return p

</syntaxhighlight>

</source>

The above example uses the default settings for the category handler module. That means the example module will categorize on pages in the following namespaces:

:'''main''', '''file''', '''help''', '''category''', '''portal''' and '''book'''

But it will ''not'' categorize in any other namespaces, e.g.:

Line 59 ⟶ 60:

And it will ''not'' categorize on blacklisted pages. (See section [[#Blacklist|blacklist]] below.)

The reason the category handler module does not categorize in some of the namespaces is that in those namespaces most modules and templates are just demonstrated or listed, not used. Thus most modules and templates should not categorize in those namespaces.

Any module or template that is meant for one or more of the namespaces where this module categorizes can use the basic syntax as shown above.

Line 67 ⟶ 68:

This module 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:

<sourcesyntaxhighlight lang="lua">

p = {}

local categoryHandler = require( 'Module:Category handler' ).main

function p.main( frame )

local result = 'This is a module meant for articles and talk pages.'

Line 81 ⟶ 82:

return result .. category

end

return p

</syntaxhighlight>

</source>

The above module will only categorize in main and talk space. But it will not categorize on /archive pages since they are blacklisted. (See section [[#Blacklist|blacklist]] below.) And if you need to demonstrate (discuss) the module on a talkpage, then you can feed "<code>nocat='true'</code>" to prevent that template from categorizing. (See section [[#Nocat|nocat]] below.) Like this:

Line 97 ⟶ 98:

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

<sourcesyntaxhighlight lang="lua">

p = {}

local categoryHandler = require( 'Module:Category handler' ).main

function p.main( frame )

local result = 'This is a module used in several namespaces.'

Line 115 ⟶ 116:

return result .. category

end

return p

</syntaxhighlight>

</source>

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

Line 129 ⟶ 130:

The category handler module also has a parameter called '''all'''. It works like this:

<sourcesyntaxhighlight lang="lua">

p = {}

local categoryHandler = require( 'Module:Category handler' ).main

function p.main( frame )

local result = 'This is a module used in all namespaces.'

Line 142 ⟶ 143:

return result .. category

end

return p

</syntaxhighlight>

</source>

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

Line 152 ⟶ 153:

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

<sourcesyntaxhighlight lang="lua">

p = {}

local categoryHandler = require( 'Module:Category handler' ).main

function p.main( frame )

local result = 'This is a module used in all namespaces.'

Line 167 ⟶ 168:

return result .. category

end

return p

</syntaxhighlight>

</source>

If the above module 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.

Line 177 ⟶ 178:

The category handler module understands the '''subpage''' parameter. Like this:

<sourcesyntaxhighlight lang="lua">

p = {}

local categoryHandler = require( 'Module:Category handler' ).main

function p.main( frame )

local result = 'This is a module used in all namespaces.'

Line 191 ⟶ 192:

return result .. category

end

return p

</syntaxhighlight>

</source>

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.

Line 210 ⟶ 211:

* If "<code>nocat = true</code>" then this template does ''not'' categorize.

* If '''nocat''' is <code>nil</code> then this template categorizes as usual.

* If "<code>nocat = false</code>" this template categorizes even when on blacklisted pages. (See section [[#Blacklist|blacklist]] above.)

* The nocat parameter also accepts aliases for <code>true</code> and <code>false</code> as defined by [[Module:Yesno]], e.g. "yes", "y", "true", and 1 for <code>true</code>, and "no", "n", "false", and 0 for <code>false</code>.

Line 220 ⟶ 221:

For backwards compatibility this module also understands the '''categories''' parameter. It works the same as '''nocat'''. Like this:

* If "<code>categories = false</code>" then this template does ''not'' categorize.

* If '''categories''' is empty or undefined then this template categorizes as usual.

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

* The categories parameter also accepts aliases for <code>true</code> and <code>false</code> as defined by [[Module:Yesno]], e.g. "yes", "y", "true", and 1 for <code>true</code>, and "no", "n", "false", and 0 for <code>false</code>.

Line 229 ⟶ 230:

For backwards compatibility this template kind of supports the old "category =" parameter. But the parameter name "category" is already used in this module to feed category data for when in category space. So instead this template uses '''category2''' for the usage similar to '''nocat'''. Like this:

* If "<code>category2 = ''"</code>" (empty but defined), or "<code>category2 = 'no'</code>", or if '''category2''' is fed any other data (except as described in the next two points), then this template does ''not'' categorize.

* If '''category2''' is undefined or if "<code>category2 = '¬'</code>", then this template categorizes as usual.

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

Line 237 ⟶ 238:

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

<sourcesyntaxhighlight lang="lua">

p = {}

local categoryHandler = require( 'Module:Category handler' ).main

Line 253 ⟶ 254:

return p

</syntaxhighlight>

</source>

When the module code above is used on anything other than a talk page, it will look like this:

Line 269 ⟶ 270:

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

<sourcesyntaxhighlight lang="lua">

p = {}

local categoryHandler = require( 'Module:Category handler' ).main

function p.main( frame )

local category = categoryHandler{

Line 282 ⟶ 283:

return category

end

return p

</syntaxhighlight>

</source>

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:

Line 291 ⟶ 292:

| main = Category:Some cat

| talk = Category:Talk cat

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

| page = User talk:Example

}}

Line 301 ⟶ 302:

You can make it so your module 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:

<sourcesyntaxhighlight lang="lua">

p = {}

local categoryHandler = require( 'Module:Category handler' ).main

Line 316 ⟶ 317:

return p

</syntaxhighlight>

</source>

=== Parameters ===

Line 331 ⟶ 332:

* nocat = frame.args.nocat / true / false / 'yes' / 'no' / 'y' / 'n' / 'true' / 'false' / 1 / 0

* categories = frame.args.categories / false / true / 'no' / 'yes' / 'n' / 'y' / 'false' / 'true' / 0 / 1

* category2 = frame.args.category or '¬' / '' / 'no' / ''not defined'' / '¬' / 'yes'

* page = frame.args.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.

Line 346 ⟶ 347:

* [[Wikipedia:WikiProject Category Suppression]] – The WikiProject.

* [[Wikipedia:Namespace]] – Lists all the namespaces.

<noinclude>

[[Category:Module documentation pages]]

</noinclude>