وحدة:Category handler

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

It helps other templates to automate both categorization and category suppression.

Already when used with its default settings this template prevents auto-categorization in some namespaces and on some pages where we usually don't want categorization. Thus even the most basic usage like "{{category handler|[[تصنيف:Somecat]]}}" sees to it that templates don't auto-categorize in the wrong places.

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.

When not to use this template

If a template only needs to categorize in one of the namespaces main (articles), file (images) or category, then using this template is overkill. Then instead use one of {{main other}}, {{file other}}, or {{category other}}. But if your template needs to categorize in any other namespace, then we recommend you use this template, since it provides proper category suppression and makes it easy to select how to categorize in the different namespaces.

Namespaces

This template detects and groups all the different namespaces used on Wikipedia into several types. These types are used as parameter names in this template.

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, mediawiki, template, help, category, portal and book = The other namespaces except the talk pages.

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

Basic usage

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

{{Ambox
| text = This is a box used in articles.
}}{{category handler
| [[تصنيف:Somecat]]
| nocat = {{{nocat|}}}   <!--So "nocat=true/false" works-->
}}<noinclude>
{{Documentation}}
<!--Add categories to the /doc subpage-->
</noinclude>

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

main, file, help, category, portal and book

But it will not categorize in the following namespaces:

talk, user, wikipedia, mediawiki and template

And it will not categorize on blacklisted pages. (See section blacklist below.)

The reason this template does not categorize in some of the namespaces is that in those namespaces most templates are just demonstrated or listed, not used. Thus most templates should not categorize in those namespaces.

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

Advanced usage

This template takes one or more parameters named after the different page types as listed in section 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.
}}{{category handler
| main = [[تصنيف:Somecat1]]   <!--Categorize in main (article) space-->
| talk = [[تصنيف:Somecat2]]   <!--Categorize in talk space-->
| nocat = {{{nocat|}}}   <!--So "nocat=true" works-->
}}

The above box will only categorize in main and talk space. But it will not categorize on /archive pages since they are blacklisted. (See section blacklist below.) And if you need to demonstrate (discuss) that box on a talkpage, then you can feed "nocat=true" to prevent that template from categorizing. (See section The "nocat" parameter below.) Like this:

== My new template ==
Hey guys, have you seen my new template?
{{mytemp|nocat=true}}
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
| main  = [[تصنيف:Somecat1]]
| 1     = [[تصنيف:Somecat2]]   <!--For help and user space-->
| help  = 1
| user  = 1
| talk  =     <!--No categories on talk pages-->
| other = [[تصنيف: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 understands the numbered parameters 1 to 10.

The other parameter defines what should be used in the remaining namespaces that have not explicitly been fed data.

Note the empty but defined talk parameter. That stops this template from showing what has been fed to the other parameter, when in talk space.

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

{{mbox
| text = This is a box used in all namespaces.
}}{{category handler
| all = [[تصنيف:Somecat1]]   <!--Categorize 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 "nocat=true" to prevent the template from categorizing.

We suggest avoiding the all parameter, since templates should preferably only categorize in the namespaces they need to.

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
| all   = [[تصنيف:Somecat1]]   <!--Categorize in all namespaces-->
| main  = [[تصنيف:Somecat2]]   <!--And add this in main space-->
| other = [[تصنيف: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.

Subpages

This template understands the subpage parameter. Like this:

{{category handler
| subpage = no    <!--Don't categorize on subpages-->
| wikipedia = [[تصنيف:Somecat]]
| nocat = {{{nocat|}}}   <!--So "nocat=true/false" works-->
}}

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

Blacklist

This template has a blacklist of the pages and page types where templates should not auto-categorize. Thus templates that use this meta-template will for instance not categorize on /archive pages and on the subpages of Wikipedia:Template messages.

If you want a template to categorize on a blacklisted page, then feed "nocat = false" 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 above), then even if you set "nocat = false" 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.

The blacklist is in the sub-template {{category handler/blacklist}}. To see or update the blacklist, go there.

The "nocat" parameter

This template understands the nocat parameter:

• If "nocat = true" then this template does not categorize.
• If nocat is empty or undefined then this template categorizes as usual.
• If "nocat = false" this template categorizes even when on blacklisted pages. (See section blacklist above.)

Templates that use {{category handler}} should forward nocat, so they too understand nocat. The code "nocat = {{{nocat|}}}" shown in the examples on this page does that.

The "categories" parameter

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

• If "categories = no" then this template does not categorize.
• If categories is empty or undefined then this template categorizes as usual.
• If "categories = yes" this template categorizes even when on blacklisted pages.

When adding this template to a template that already uses the "categories = no" logic, then you can do the following to not break any existing usage:

{{category handler
| [[تصنيف:Somecat]]
| nocat = {{{nocat|}}}   <!--So "nocat=true/false" works-->
| categories = {{{categories|}}}   <!--So "categories=no" works-->
}}

The "category2" parameter

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

• If "category2 =" (empty but defined), or "category2 = no", 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 "category2 = ¬", then this template categorizes as usual.
• If "category2 = yes" this template categorizes even when on blacklisted pages.

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

{{category handler
| [[تصنيف:Somecat]]
| nocat = {{{nocat|}}}   <!--So "nocat=true/false" works-->
| category2 = {{{category|¬}}}   <!--So "category =" works-->
}}

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

Categories and text

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.
}}{{category handler
| talk = [[تصنيف:Somecat]]
| other = :::::This template should only be used on talk pages.
| 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):

This template should only be used on talk pages.

That text will not show on blacklisted pages, so don't use this method to show any important information. Feeding "nocat = true" to the template hides the text, just as it suppresses any categories.

The "page" parameter

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

{{category handler
| main = Category:Some cat
| talk = Category:Talk cat
| nocat = {{{nocat|}}}   <!--So "nocat=true/false" works-->
| 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:

Category:Talk cat

The page parameter makes this template behave exactly as if on that page. Even the blacklist works. The pagename doesn't have to be an existing page.

If the page parameter is empty or undefined, the name of the current page determines the result.

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
| talk = Category:Talk cat
| nocat = {{{nocat|}}}   <!--So "nocat=true/false" works-->
| page = {{{page|}}}   <!--For testing-->
}}

Parameters

List of all parameters:

{{category handler
| [[تصنيف:Somecat]]
| subpage = no / only
| 1 =
...
| 10 =
| all = [[تصنيف:Somecat]] / Text
| main = 1 / ... / 10 / [[تصنيف:Somecat]] / Text
...
| other = 1 / ... / 10 / [[تصنيف:Somecat]] / Text

| nocat = {{{nocat|}}} / true / false
| categories = {{{categories|}}} / no / yes
| category2 = {{{category|¬}}} / 'empty' / no / 'not defined' / ¬ / yes

| 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

The centralised category suppression blacklist is in the sub-template {{category handler/blacklist}}. To see or update the blacklist, go there.

For its internal parameter processing, this template uses the sub-template {{category handler/numbered}}.

For more technical details see the talk page.

See also

• Wikipedia:Category suppression – The how-to guide.
• Wikipedia:WikiProject Category Suppression – The WikiProject.
• Wikipedia:Namespace – Lists all the namespaces.

---

--------------------------------------------------------------------------------
--                                                                            --
--                              CATEGORY HANDLER                              --
--                                                                            --
--      This module implements the {{category handler}} template in Lua,      --
--      with a few improvements: all namespaces and all namespace aliases     --
--      are supported, and namespace names are detected automatically for     --
--      the local wiki. This module requires [[Module:Namespace detect]]      --
--      and [[Module:Yesno]] to be available on the local wiki. It can be     --
--      configured for different wikis by altering the values in              --
--      [[Module:Category handler/config]], and pages can be blacklisted      --
--      from categorisation by using [[Module:Category handler/blacklist]].   --
--                                                                            --
--------------------------------------------------------------------------------

-- Load required modules
local yesno = require('Module:Yesno')

-- Lazily load things we don't always need
local mShared, mappings

local p = {}

--------------------------------------------------------------------------------
-- Helper functions
--------------------------------------------------------------------------------

local function trimWhitespace(s, removeBlanks)
	if type(s) ~= 'string' then
		return s
	end
	s = s:match('^%s*(.-)%s*$')
	if removeBlanks then
		if s ~= '' then
			return s
		else
			return nil
		end
	else
		return s
	end
end

--------------------------------------------------------------------------------
-- CategoryHandler class
--------------------------------------------------------------------------------

local CategoryHandler = {}
CategoryHandler.__index = CategoryHandler

function CategoryHandler.new(data, args)
	local obj = setmetatable({ _data = data, _args = args }, CategoryHandler)
	
	-- Set the title object
	do
		local pagename = obj:parameter('demopage')
		local success, titleObj
		if pagename then
			success, titleObj = pcall(mw.title.new, pagename)
		end
		if success and titleObj then
			obj.title = titleObj
			if titleObj == mw.title.getCurrentTitle() then
				obj._usesCurrentTitle = true
			end
		else
			obj.title = mw.title.getCurrentTitle()
			obj._usesCurrentTitle = true
		end
	end

	-- Set suppression parameter values
	for _, key in ipairs{'nocat', 'categories'} do
		local value = obj:parameter(key)
		value = trimWhitespace(value, true)
		obj['_' .. key] = yesno(value)
	end
	do
		local subpage = obj:parameter('subpage')
		local category2 = obj:parameter('category2')
		if type(subpage) == 'string' then
			subpage = mw.ustring.lower(subpage)
		end
		if type(category2) == 'string' then
			subpage = mw.ustring.lower(category2)
		end
		obj._subpage = trimWhitespace(subpage, true)
		obj._category2 = trimWhitespace(category2) -- don't remove blank values
	end
	return obj
end

function CategoryHandler:parameter(key)
	local parameterNames = self._data.parameters[key]
	local pntype = type(parameterNames)
	if pntype == 'string' or pntype == 'number' then
		return self._args[parameterNames]
	elseif pntype == 'table' then
		for _, name in ipairs(parameterNames) do
			local value = self._args[name]
			if value ~= nil then
				return value
			end
		end
		return nil
	else
		error(string.format(
			'invalid config key "%s"',
			tostring(key)
		), 2)
	end
end

function CategoryHandler:isSuppressedByArguments()
	return
		-- See if a category suppression argument has been set.
		self._nocat == true
		or self._categories == false
		or (
			self._category2
			and self._category2 ~= self._data.category2Yes
			and self._category2 ~= self._data.category2Negative
		)

		-- Check whether we are on a subpage, and see if categories are
		-- suppressed based on our subpage status.
		or self._subpage == self._data.subpageNo and self.title.isSubpage
		or self._subpage == self._data.subpageOnly and not self.title.isSubpage
end

function CategoryHandler:shouldSkipBlacklistCheck()
	-- Check whether the category suppression arguments indicate we
	-- should skip the blacklist check.
	return self._nocat == false
		or self._categories == true
		or self._category2 == self._data.category2Yes
end

function CategoryHandler:matchesBlacklist()
	if self._usesCurrentTitle then
		return self._data.currentTitleMatchesBlacklist
	else
		mShared = mShared or require('Module:Category handler/shared')
		return mShared.matchesBlacklist(
			self.title.prefixedText,
			mw.loadData('Module:Category handler/blacklist')
		)
	end
end

function CategoryHandler:isSuppressed()
	-- Find if categories are suppressed by either the arguments or by
	-- matching the blacklist.
	return self:isSuppressedByArguments()
		or not self:shouldSkipBlacklistCheck() and self:matchesBlacklist()
end

function CategoryHandler:getNamespaceParameters()
	if self._usesCurrentTitle then
		return self._data.currentTitleNamespaceParameters
	else
		if not mappings then
			mShared = mShared or require('Module:Category handler/shared')
			mappings = mShared.getParamMappings(true) -- gets mappings with mw.loadData
		end
		return mShared.getNamespaceParameters(
			self.title,
			mappings
		)
	end
end

function CategoryHandler:namespaceParametersExist()
	-- Find whether any namespace parameters have been specified.
	-- We use the order "all" --> namespace params --> "other" as this is what
	-- the old template did.
	if self:parameter('all') then
		return true
	end
	if not mappings then
		mShared = mShared or require('Module:Category handler/shared')
		mappings = mShared.getParamMappings(true) -- gets mappings with mw.loadData
	end
	for ns, params in pairs(mappings) do
		for i, param in ipairs(params) do
			if self._args[param] then
				return true
			end
		end
	end
	if self:parameter('other') then
		return true
	end
	return false
end

function CategoryHandler:getCategories()
	local params = self:getNamespaceParameters()
	local nsCategory
	for i, param in ipairs(params) do
		local value = self._args[param]
		if value ~= nil then
			nsCategory = value
			break
		end
	end
	if nsCategory ~= nil or self:namespaceParametersExist() then
		-- Namespace parameters exist - advanced usage.
		if nsCategory == nil then
			nsCategory = self:parameter('other')
		end
		local ret = {self:parameter('all')}
		local numParam = tonumber(nsCategory)
		if numParam and numParam >= 1 and math.floor(numParam) == numParam then
			-- nsCategory is an integer
			ret[#ret + 1] = self._args[numParam]
		else
			ret[#ret + 1] = nsCategory
		end
		if #ret < 1 then
			return nil
		else
			return table.concat(ret)
		end
	elseif self._data.defaultNamespaces[self.title.namespace] then
		-- Namespace parameters don't exist, simple usage.
		return self._args[1]
	end
	return nil
end

--------------------------------------------------------------------------------
-- Exports
--------------------------------------------------------------------------------

local p = {}

function p._exportClasses()
	-- Used for testing purposes.
	return {
		CategoryHandler = CategoryHandler
	}
end

function p._main(args, data)
	data = data or mw.loadData('Module:Category handler/data')
	local handler = CategoryHandler.new(data, args)
	if handler:isSuppressed() then
		return nil
	end
	return handler:getCategories()
end

function p.main(frame, data)
	data = data or mw.loadData('Module:Category handler/data')
	local args = require('Module:Arguments').getArgs(frame, {
		wrappers = data.wrappers,
		valueFunc = function (k, v)
			v = trimWhitespace(v)
			if type(k) == 'number' then
				if v ~= '' then
					return v
				else
					return nil
				end
			else
				return v
			end
		end
	})
	return p._main(args, data)
end

return p