Module:category tree: difference between revisions
No edit summary |
No edit summary |
||
Line 179: | Line 179: | ||
function show_TOC(info) |
function show_TOC(info) |
||
local code = info.code or "en" |
local code = info.code or "en" |
||
local num_pages = mw.site.stats.pagesInCategory(mw.title.getCurrentTitle().text, "pages") |
local num_pages = 300 --mw.site.stats.pagesInCategory(mw.title.getCurrentTitle().text, "pages") |
||
-- No need for a TOC if all entry names can fit on one page. |
-- No need for a TOC if all entry names can fit on one page. |
Revision as of 19:43, 28 July 2014
- The following documentation is located at Module:category tree/documentation. [edit]
- Useful links: subpage list • links • transclusions • testcases • sandbox
This module is used for generating category boilerplate templates. It is not meant to be used directly. Rather, each template will have its own submodule, which handles the specifics of that template.
This documentation only covers the generics of the category tree system. If you are looking for documentation on a specific template, or on how to add or modify category information, see the documentation of that template.
Parameters
The category tree module is invoked as:
{{#invoke:category tree|show|template=name of the template|...other parameters...}}
Every template that uses this module should have a submodule of this module with the name given in the |template=
parameter. At present, only three such templates exist:
{{poscatboiler}}
uses Module:category tree/poscatboiler{{topic cat}}
uses Module:category tree/topic cat{{ws topic cat}}
uses Module:category tree/ws topic cat
The submodule should export a function named new
which takes a single parameter: a table named info
that contains the various parameters that were passed to the template initially. This function should return a new Category
object representing those parameters, or nil
if the combination of parameters was not valid (i.e. no such category exists).
General workings
The module is based on the principle of two main kinds of category:
Basic categories belong to a specific language (or similar) and are the "regular" categories. Examples are: Category:English nouns, Category:French templates, Category:nl:Linguistics, Category:English terms derived from Japanese, Category:Latin script characters.
Umbrella categories do not have a code, but contain all basic categories of their label, one for each code. These are the "by language" type categories. Examples are: Category:Nouns by language, Category:Templates by language, Category:Linguistics, Category:Terms derived from Japanese, Category:Characters by script.
Some templates also distinguish a third type of category, the fundamental category. This category is used as the parent category for umbrella categories.
Category objects
Category objects are returned by each submodule's new
function. They represent a single category in the tree. A category object has a variety of methods which may be called on it to ask for information about the category.
getBreadcrumbName
getBreadcrumbName()
Returns the name that is used for the category in the "breadcrumbs" at the top of the category page.
getDataModule
getDataModule()
Returns the name of the module which contains the data for this category. This is used to create an "edit" link on the category, which allows users to find and edit the information more easily.
canBeEmpty
canBeEmpty()
Returns true
either if the category contains pages but might be empty or if the category only contains categories, otherwise returns false
.
getCategoryName
getCategoryName()
Returns the name of the category that this category object represents.
getDescription
getDescription()
Returns the description text that is shown at the top of the category page. If the category has no description, this returns nil
.
getParents
getParents()
Returns a table of the parent categories of this category. Each element in the table is a table itself, with two elements:
.name
- One of two possibilities: An category object representing the parent category, or a string that directly specifies the name of the parent category.
.sort
- The sorting key that should be used when categorizing the current category in the parent.
If the category has no parents, this returns nil
.
If there are two or more parent categories, the first will be used to generate the breadcrumbs that are displayed at the top of the category page. For example, Category:English language is in numerous categories (All languages, West Germanic languages, Latin script languages, Braille script languages, and so on), but the first category, All languages, is the one displayed in the breadcrumbs: Fundamental » All languages » English language.
getChildren
getChildren()
Returns a table of the child categories of this category. Each element in the table is a category object representing the child category. If the category has no children, this returns nil
.
getUmbrella
getUmbrella()
Returns a category object for the current category's corresponding umbrella category. If the current category is already an umbrella category, this returns nil
. It also returns nil
if the category has no umbrella category.
getAppendix
getAppendix()
Returns an appendix link (such as Appendix:French verbs) if the page exists, else returns nil
.
getTOCTemplateName
getTOCTemplateName()
Returns the title for a template used as table of contents with the namespace prefix.
The table of contents is designed for categories with terms in a certain language, The TOC template should be a small, one-line template; a larger template will be used if available with the suffix /full. For example, if getTOCTemplateName() returns Template:en-categoryTOC, {{en-categoryTOC}}
will be used as the small table of contents template (for categories with more than 200 but less than 2500 entries) and {{en-categoryTOC/full}}
as the full table of contents template (for categories with more than 2500 entries).
If the function returns nil
, no such template will be used.
local export = {}
-- The main entry point.
-- This is the only function that can be invoked from a template.
function export.show(frame)
if mw.title.getCurrentTitle().nsText == "Template" then
return "(This template should be used on pages in the Category: namespace.)"
elseif mw.title.getCurrentTitle().nsText ~= "Category" then
error("This template/module can only be used on pages in the Category: namespace.")
end
local args = frame.args
-- Get all the parameters and the label data
local info = {}
for key, val in pairs(args) do
info[key] = val; if info[key] == "" then info[key] = nil end
end
if not info.template then
error("The \"template\" parameter was not specified.")
end
local template = info.template
info.template = nil
-- Check if the category is empty
local categories = {}
if mw.site.stats.pagesInCategory(mw.title.getCurrentTitle().text, "all") == 0 then
table.insert(categories, "[[Category:Empty categories]]")
end
-- Does the category have the correct name?
local current = require("Module:category tree/" .. template).new(info)
local errormessage = check_name(current, template, info)
if errormessage then
return table.concat(categories, "") .. errormessage
end
-- Generate the displayed information
local display = {}
table.insert(display, show_breadcrumbs(current))
table.insert(display, show_description(current))
table.insert(display, show_children(current))
table.insert(display, show_TOC(info))
show_categories(current, categories)
return table.concat(categories, "") .. table.concat(display, "\n\n") .. "<br clear=\"all\"/>"
end
-- Check the name of the current page, and return an error if it's not right.
function check_name(current, template, info)
local errortext = nil
local category = nil
if not current then
errortext =
"The label \"" .. (info.label or "") .. "\" given to the " .. mw.getCurrentFrame():expandTemplate{title = "temp", args = {template}} .. " template is not valid. " ..
"You may have mistyped it, or it simply has not been created yet. To add a new label, please consult the documentation of the template."
category = "[[Category:Categories with invalid label]]"
else
local expected_name = current:getCategoryName()
if expected_name ~= mw.title.getCurrentTitle().text then
errortext = "Based on the parameters given to the " .. mw.getCurrentFrame():expandTemplate{title = "temp", args = {template}} .. " template, this category should be called '''[[:Category:" .. expected_name .. "]]'''."
category = "[[Category:Categories with incorrect name]]"
end
end
if errortext then
return (category or "") .. mw.getCurrentFrame():expandTemplate{title = "maintenance box", args = {
"red",
image = "[[File:Ambox warning pn.svg|50px]]",
title = "The automatically-generated contents of this category has errors.",
text = errortext,
}}
else
return nil
end
end
-- Show the parent categories that the current category should be placed in.
function show_categories(current, categories)
local parents = current:getParents()
if not parents then
return
end
for _, parent in ipairs(parents) do
if type(parent.name) == "string" then
table.insert(categories, "[[" .. parent.name .. "|" .. parent.sort .. "]]")
else
local parent_name = parent.name:getCategoryName()
table.insert(categories, "[[Category:" .. parent_name .. "|" .. parent.sort .. "]]")
end
end
-- Also put the category in its corresponding "umbrella" or "by language" category.
local umbrella = current:getUmbrella()
if umbrella then
if type(umbrella) == "string" then
table.insert(categories, "[[" .. umbrella .. "|" .. current:getCategoryName() .. "]]")
else
table.insert(categories, "[[Category:" .. umbrella:getCategoryName() .. "|" .. current:getCategoryName() .. "]]")
end
end
end
-- Show navigational "breadcrumbs" at the top of the page.
function show_breadcrumbs(current)
local steps = {}
-- Start at the current label and move our way up the "chain" from child to parent, until we can't go further.
while current do
local category = nil
local display_name = nil
if type(current) == "string" then
category = current
display_name = current:gsub("^Category:", "")
else
category = "Category:" .. current:getCategoryName()
display_name = current:getBreadcrumbName()
end
display_name = mw.getContentLanguage():ucfirst(display_name)
table.insert(steps, 1, "» [[:" .. category .. "|" .. display_name .. "]]")
-- Move up the "chain" by one level.
if type(current) == "string" then
current = nil
else
current = current:getParents()
if current then
current = current[1].name
end
end
end
return "<small>" .. table.concat(steps, " ") .. "</small>"
end
-- Show a short description text for the category.
function show_description(current)
return (current:getDescription() or "") .. mw.getCurrentFrame():expandTemplate{title = "edit", args = {current:getDataModule(), type = "sup"}}
end
-- Show a list of child categories.
function show_children(current)
local children = current:getChildren()
if not children then
return nil
end
local children_list = {}
for _, child in ipairs(children) do
local child_basic = child:getCategoryName()
local child_page = mw.title.new("Category:" .. child_basic)
if child_page.exists then
local child_description = child:getDescription()
table.insert(children_list, "* [[:Category:" .. child_basic .. "]]: " .. child_description)
end
end
return table.concat(children_list, "\n")
end
-- Show a table of contents with links to each letter in the language's script.
function show_TOC(info)
local code = info.code or "en"
local num_pages = 300 --mw.site.stats.pagesInCategory(mw.title.getCurrentTitle().text, "pages")
-- No need for a TOC if all entry names can fit on one page.
if num_pages > 200 then
-- This category is very large, see if there is an "extended" version of the TOC.
if num_pages > 2500 then
local TOC_template_extended = mw.title.new("Template:" .. code .. "-categoryTOC/full")
if TOC_template_extended.exists then
return mw.getCurrentFrame():expandTemplate{title = TOC_template_extended.text, args = {}}
end
end
local TOC_template = mw.title.new("Template:" .. code .. "-categoryTOC")
if TOC_template.exists then
return mw.getCurrentFrame():expandTemplate{title = TOC_template.text, args = {}}
end
end
return nil
end
return export