Модуль:Category handler

Документация

[просмотр|править|история|]

This module implements the{{category handler}}template. The category handler template helps other templates to automate both categorization andcategory suppression.For information about using the category handler template in other templates, please see thetemplate 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.

Use from other Lua modules

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 usingmw.title.getCurrentTitleand check thensTextfield. For example:

localtitle=mw.title.getCurrentTitle()
iftitle.nsText=='File'then
-- do something
end

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.

Namespaces

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

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.

List of possible namespace parameters

(excludingtalkandother)

Namespace	Aliases
main
участник	user,у,u,участница
википедия	project,вп,wikipedia,wp
файл	file,изображение,image
mediawiki
шаблон	template,ш,t
справка	help
категория	category,к
портал
инкубатор	и
проект	про
арбитраж	ак,arbcom
timedtext
модуль	module

Basic usage

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

p={}
localcategoryHandler=require('Module:Category handler').main

functionp.main(frame)
localresult='Hello world!'
localcategory=categoryHandler{
'[[Category:Somecat]]',
nocat=frame.args.nocat-- So "nocat=true/false" works
}
category=categoryor''-- Check that we don't have a nil value for the category variable.
returnresult..category
end

returnp

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,portalandbook

But it willnotcategorize in any other namespaces, e.g.:

talk,user,wikipedia,mediawiki,template...

And it willnotcategorize on blacklisted pages. (See sectionblacklistbelow.)

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.

Advanced usage

This module takes one or more parameters named after the different page types as listed in sectionnamespacesabove. By using those parameters you can specify exactly in which namespaces your template should categorize. Like this:

p={}
localcategoryHandler=require('Module:Category handler').main

functionp.main(frame)
localresult='This is a module meant for articles and talk pages.'
localcategory=categoryHandler{
main='[[Category:Somecat1]]',-- Categorize in main (article) space
talk='[[Category:Somecat2]]',-- Categorize in talk space
nocat=frame.args.nocat-- So "nocat=true/false" works
}
category=categoryor''-- Check that we don't have a nil value for the category variable.
returnresult..category
end

returnp

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

== My new module ==
Hey guys, have you seen my new module?
{{#invoke:mymodule|main|nocat=true}}
Nice, isn't it?
--~~~~

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

p={}
localcategoryHandler=require('Module:Category handler').main

functionp.main(frame)
localresult='This is a module used in several namespaces.'
localcategory=categoryHandler{
main='[[Category:Somecat1]]',
[1]='[[Category:Somecat2]]',-- For help and user space
help=1,
user=1,
talk='',-- No categories on talk pages
other='[[Category:Somecat3]]',-- For all other namespaces
nocat=frame.args.nocat-- So "nocat=true/false" works
}
category=categoryor''-- Check that we don't have a nil value for the category variable.
returnresult..category
end

returnp

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.

The category handler module understands an unlimited number of numbered parameters.

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

Note the empty but definedtalkparameter. That stops this module from showing what has been fed to theotherparameter, when in talk space.

The category handler module also has a parameter calledall.It works like this:

p={}
localcategoryHandler=require('Module:Category handler').main

functionp.main(frame)
localresult='This is a module used in all namespaces.'
localcategory=categoryHandler{
all='[[Category:Somecat1]]',-- Categorize in all namespaces
nocat=frame.args.nocat-- So "nocat=true/false" works
}
category=categoryor''-- Check that we don't have a nil value for the category variable.
returnresult..category
end

returnp

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 "nocat=true"to prevent the template from categorizing.

We suggest avoiding theallparameter, since modules and 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:

p={}
localcategoryHandler=require('Module:Category handler').main

functionp.main(frame)
localresult='This is a module used in all namespaces.'
localcategory=categoryHandler{
all='[[Category:Somecat1]]',-- Categorize in all namespaces
main='[[Category:Somecat2]]',-- And add this in main space
other='[[Category:Somecat3]]',-- And add this in all other namespaces
nocat=frame.args.nocat-- So "nocat=true/false" works
}
category=categoryor''-- Check that we don't have a nil value for the category variable.
returnresult..category
end

returnp

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.

Subpages

The category handler module understands thesubpageparameter. Like this:

p={}
localcategoryHandler=require('Module:Category handler').main

functionp.main(frame)
localresult='This is a module used in all namespaces.'
localcategory=categoryHandler{
subpage='no'-- Don't categorize on subpages
wikipedia='[[Category:Somecat]]',
nocat=frame.args.nocat-- So "nocat=true/false" works
}
category=categoryor''-- Check that we don't have a nil value for the category variable.
returnresult..category
end

returnp

If "subpage='no'"then this template willnotcategorize on subpages. For the rare occasion youonlywant to categorize on subpages, then use "subpage='only'".Ifsubpageis empty or undefined then this template categorizes both on basepages and on subpages.

Blacklist

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

If you want a template to categorize on a blacklisted page, then feed "nocat = false"to the module when you place it on the page, thus skipping the blacklist check. Note that this module only categorizes if it has data for the namespace. For instance, if the basic syntax is used (seebasic usageabove), 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 located in the configuration tablecfg.blacklistnear the top of the module code.

The "nocat" parameter

This module understands thenocatparameter:

• If "nocat = true"then this template doesnotcategorize.
• Ifnocatisnilthen this template categorizes as usual.
• If "nocat = false"this template categorizes even when on blacklisted pages. (See sectionblacklistabove.)
• The nocat parameter also accepts aliases fortrueandfalseas defined byModule:Yesno,e.g. "yes", "y", "true", and 1 fortrue,and "no", "n", "false", and 0 forfalse.

Modules and templates that use{{category handler}}should forwardnocat,so they too understandnocat.The code "nocat = frame.args.nocat"shown in the examples on this page does that.

The "categories" parameter

For backwards compatibility this module also understands thecategoriesparameter. It works the same asnocat.Like this:

• If "categories = false"then this template doesnotcategorize.
• Ifcategoriesis empty or undefined then this template categorizes as usual.
• If "categories = true"this template categorizes even when on blacklisted pages.
• The categories parameter also accepts aliases fortrueandfalseas defined byModule:Yesno,e.g. "yes", "y", "true", and 1 fortrue,and "no", "n", "false", and 0 forfalse.

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 module to feed category data for when in category space. So instead this template usescategory2for the usage similar tonocat.Like this:

• If "category2 = ''"(empty but defined), or"category2 = 'no'",or ifcategory2is fed any other data (except as described in the next two points), then this template doesnotcategorize.
• Ifcategory2is undefined or if "category2 = '¬'",then this template categorizes as usual.
• If "category2 = 'yes'"this template categorizes even when on blacklisted pages.

Categories and text

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

p={}
localcategoryHandler=require('Module:Category handler').main

functionp.main(frame)
localresult='This is a module used on talk pages.'
localcategory=categoryHandler{
talk='[[Category:Somecat]]',
other='<p class= "error" >This module should only be used on talk pages.</p>',
nocat=frame.args.nocat-- So "nocat=true/false" works
}
category=categoryor''-- Check that we don't have a nil value for the category variable.
returnresult..category
end

returnp

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

This is a module 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 module can take a parameter namedpage.Like this:

p={}
localcategoryHandler=require('Module:Category handler').main

functionp.main(frame)
localcategory=categoryHandler{
main='Category:Some cat',
talk='Category:Talk cat',
nocat=frame.args.nocat,-- So "nocat=true/false" works
page='User talk:Example'
}
returncategory
end

returnp

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

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

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

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

p={}
localcategoryHandler=require('Module:Category handler').main

functionp.main(frame)
localcategory=categoryHandler{
main='Category:Some cat',
talk='Category:Talk cat',
nocat=frame.args.nocat,-- So "nocat=true/false" works
page=frame.args.page-- For testing
}
returncategory
end

returnp

Parameters

List of all parameters:

• First positional parameter - for default settings
• subpage = 'no' / 'only'
• 1, 2, 3...
• all = '[[Category:Somecat]]' / 'Text'
• main = 1, 2, 3... / '[[Category:Somecat]]' / 'Text'
• ...
• other = 1, 2, 3... / '[[Category:Somecat]]' / 'Text'
• 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.

Exporting to other wikis

This module can be exported to other wikis by changing the configuration values in thecfgtable. All the variable values are configurable, so after the configuration values have been set there should be no need to alter the main module code. Details of each configuration value are included in the module code comments. In addition, this module requiresModule:Namespace detectto be available on the local wiki.

See also

• {{Category handler}}– for using this module with templates, rather than Lua modules.
• Wikipedia:Category suppression– The how-to guide.
• Wikipedia:WikiProject Category Suppression– The WikiProject.
• Wikipedia:Namespace– Lists all the namespaces.

Во избежание поломок страниц, использующих этот модуль, экспериментируйте впесочнице(создать)илипесочнице для модулей.
Пожалуйста, добавляйте категории на подстраницу/doc.Подстраницы этого модуля.

--------------------------------------------------------------------------------
-- --
-- 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
localyesno=require('Module:Yesno')

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

localp={}

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

localfunctiontrimWhitespace(s,removeBlanks)
iftype(s)~='string'then
returns
end
s=s:match('^%s*(.-)%s*$')
ifremoveBlanksthen
ifs~=''then
returns
else
returnnil
end
else
returns
end
end

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

localCategoryHandler={}
CategoryHandler.__index=CategoryHandler

functionCategoryHandler.new(data,args)
localobj=setmetatable({_data=data,_args=args},CategoryHandler)

-- Set the title object
do
localpagename=obj:parameter('demopage')
localsuccess,titleObj
ifpagenamethen
success,titleObj=pcall(mw.title.new,pagename)
end
ifsuccessandtitleObjthen
obj.title=titleObj
iftitleObj==mw.title.getCurrentTitle()then
obj._usesCurrentTitle=true
end
else
obj.title=mw.title.getCurrentTitle()
obj._usesCurrentTitle=true
end
end

-- Set suppression parameter values
for_,keyinipairs{'nocat','categories'}do
localvalue=obj:parameter(key)
value=trimWhitespace(value,true)
obj['_'..key]=yesno(value)
end
do
localsubpage=obj:parameter('subpage')
localcategory2=obj:parameter('category2')
iftype(subpage)=='string'then
subpage=mw.ustring.lower(subpage)
end
iftype(category2)=='string'then
subpage=mw.ustring.lower(category2)
end
obj._subpage=trimWhitespace(subpage,true)
obj._category2=trimWhitespace(category2)-- don't remove blank values
end
returnobj
end

functionCategoryHandler:parameter(key)
localparameterNames=self._data.parameters[key]
localpntype=type(parameterNames)
ifpntype=='string'orpntype=='number'then
returnself._args[parameterNames]
elseifpntype=='table'then
for_,nameinipairs(parameterNames)do
localvalue=self._args[name]
ifvalue~=nilthen
returnvalue
end
end
returnnil
else
error(string.format(
'invalid config key "%s" ',
tostring(key)
),2)
end
end

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

-- Check whether we are on a subpage, and see if categories are
-- suppressed based on our subpage status.
orself._subpage==self._data.subpageNoandself.title.isSubpage
orself._subpage==self._data.subpageOnlyandnotself.title.isSubpage
end

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

functionCategoryHandler:matchesBlacklist()
ifself._usesCurrentTitlethen
returnself._data.currentTitleMatchesBlacklist
else
mShared=mSharedorrequire('Module:Category handler/shared')
returnmShared.matchesBlacklist(
self.title.prefixedText,
mw.loadData('Module:Category handler/blacklist')
)
end
end

functionCategoryHandler:isSuppressed()
-- Find if categories are suppressed by either the arguments or by
-- matching the blacklist.
returnself:isSuppressedByArguments()
ornotself:shouldSkipBlacklistCheck()andself:matchesBlacklist()
end

functionCategoryHandler:getNamespaceParameters()
ifself._usesCurrentTitlethen
returnself._data.currentTitleNamespaceParameters
else
ifnotmappingsthen
mShared=mSharedorrequire('Module:Category handler/shared')
mappings=mShared.getParamMappings(true)-- gets mappings with mw.loadData
end
returnmShared.getNamespaceParameters(
self.title,
mappings
)
end
end

functionCategoryHandler: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.
ifself:parameter('all')then
returntrue
end
ifnotmappingsthen
mShared=mSharedorrequire('Module:Category handler/shared')
mappings=mShared.getParamMappings(true)-- gets mappings with mw.loadData
end
forns,paramsinpairs(mappings)do
fori,paraminipairs(params)do
ifself._args[param]then
returntrue
end
end
end
ifself:parameter('other')then
returntrue
end
returnfalse
end

functionCategoryHandler:getCategories()
localparams=self:getNamespaceParameters()
localnsCategory
fori,paraminipairs(params)do
localvalue=self._args[param]
ifvalue~=nilthen
nsCategory=value
break
end
end
ifnsCategory~=nilorself:namespaceParametersExist()then
-- Namespace parameters exist - advanced usage.
ifnsCategory==nilthen
nsCategory=self:parameter('other')
end
localret={self:parameter('all')}
localnumParam=tonumber(nsCategory)
ifnumParamandnumParam>=1andmath.floor(numParam)==numParamthen
-- nsCategory is an integer
ret[#ret+1]=self._args[numParam]
else
ret[#ret+1]=nsCategory
end
if#ret<1then
returnnil
else
returntable.concat(ret)
end
elseifself._data.defaultNamespaces[self.title.namespace]then
-- Namespace parameters don't exist, simple usage.
returnself._args[1]
end
returnnil
end

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

localp={}

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

functionp._main(args,data)
data=dataormw.loadData('Module:Category handler/data')
localhandler=CategoryHandler.new(data,args)
ifhandler:isSuppressed()then
returnnil
end
returnhandler:getCategories()
end

functionp.main(frame,data)
data=dataormw.loadData('Module:Category handler/data')
localargs=require('Module:Arguments').getArgs(frame,{
wrappers=data.wrappers,
valueFunc=function(k,v)
v=trimWhitespace(v)
iftype(k)=='number'then
ifv~=''then
returnv
else
returnnil
end
else
returnv
end
end
})
returnp._main(args,data)
end

returnp