Modul:category tree

This module is used for generating category boilerplate templates. It is not meant to be used directly, but is to be used by a more specific template such as {{poscatboiler}}.

Parameters

The module takes the following parameters:

template=: The name of the template that uses the module. This name is used as the name of the submodule that is queried for information.
code=: The code that specifies what 'owns' the category's contents. This is usually a language code such as en, but it can also be a script code like Latn or the code of a language family.
label=: A name for the thing that is being categorised. The submodule determines how the label is interpreted, so it depends on the template being used. Many templates use it to look up data in a table, while others may interpret it as a language code of some kind.
sc=: The script code of the items to be categorised. This is usually empty, but many categories such as those used by Mandarin Chinese can split into subcategories based on script.

General workings

Every template that uses this module should have a submodule of this module with the same name as the template. This submodule should export a function named new which takes a single parameter: a table containing 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).

The module is based on the principle of two main kinds of category:

Basic categories are those for which the code= parameter is not empty. These therefore 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 all 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.

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.

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.

Data modules

Some category templates, like {{poscatboiler}}, use separate data modules to list information for a large number of categories together. The following values are generally used in these modules:

description

A plain English description for the label.

fundamental

The "fundamental" category name, which is the parent category that all umbrella categories are collected in.

sortparentumbrella

The sort key used to sort the umbrella category within the fundamental category. This generally defaults to the display name, but can be overridden with something like ** for root categories to make them easier to find.

parents

A table listing one or more parent labels of this label.

An item in the table can be either a single string, or a table containing two elements called name and sort. In the latter case, name value specifies the parent label name, while the sort value specifies the sort key to use to sort it in that category.
If a parent label begins with Category: it is interpreted as a raw category name, rather than as a label name. It can still have its own sort key as usual.

Subpages

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 == "Vörlaag" then
		return "(Dissen mal zol allenig op zieden in de Kategorie: namespace gebroekt motten worden.)"
	elseif mw.title.getCurrentTitle().nsText ~= "Kategorie" then
		error("Dissen mal kan allenig op zieden in de Kategorie: namespace gebroekt worden.")
	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("De \"template\" parameter was neet op-egovven.")
	end
	
	local template = info.template
	info.template = nil
	local current = require("Module:category tree/" .. template).new(info)
	local display = {}
	local categories = {}
	
	-- Check if the category is empty
	-- local isEmpty = mw.site.stats.pagesInCategory(mw.title.getCurrentTitle().text, "all") == 0	
	
	if not current then
		table.insert(categories, "[[Kategorie:Kategorien bruken Acht]]")
		table.insert(display, show_error(
			"t Label \"" .. (info.label or "") .. "\" dat mal " ..
			mw.getCurrentFrame():expandTemplate{title = "temp", args = {template}} ..
			" metkreeg is neet geldig. Wellicht he'j n typfoute maakt, of t label besteet nog neet. " ..
			"Um n ni'j label te maken, kö'j in de mal-dokumentatsie kieken."))
		
		-- Exit here, as all code beyond here relies on current not being nil
		return table.concat(categories, "") .. table.concat(display, "\n\n") .. "<br clear=\"all\"/>"
	end

	-- Does the category have the correct name?
	if mw.title.getCurrentTitle().text ~= current:getCategoryName() then
		table.insert(categories, "[[Kategorie:Kategorien bruken Acht]]")
		table.insert(display, show_error(
			"Met de parameters dee't met-egeven bunt an de " ..
			mw.getCurrentFrame():expandTemplate{title = "temp", args = {template}} ..
			" Vörlaag zol disse Kategorie '''[[:Kategorie:" .. current:getCategoryName() .. "]]''' motten heten."))
	end
	
	-- Generate the displayed information
	table.insert(display, show_breadcrumbs(current))
	table.insert(display, show_Bild(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

function show_error(text)
	return  mw.getCurrentFrame():expandTemplate{title = "maintenance box", args = {
		"red",
		image = "[[File:Ambox warning pn.svg|50px]]",
		title = "Den automaties genereerden inhold van disse kategorie hef fouten.",
		text = text,
		}}
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 =
			"t Label \"" .. (info.label or "") .. "\", dat mal " .. mw.getCurrentFrame():expandTemplate{title = "temp", args = {template}} .. " metkreeg is neet geldig. " ..
			"Wellicht he'j n typfoute maakt, of t label besteet nog neet. Um n ni'j label te maken, kö'j in de mal-dokumentatsie kieken."
		category = "[[Kategorie:Kategorien bruken Acht]]"
	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 '''[[:Kategorie:" .. expected_name .. "]]'''."
			category = "[[Kategorie:Kategorien bruken Acht]]"
		end
	end
	
	if errortext then
		return (category or "") .. show_error(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 parent.name then       
			if type(parent.name) == "string" then
				table.insert(categories, "[[" .. parent.name .. "|" .. parent.sort .. "]]")
			else
				local parent_name = parent.name:getCategoryName()
				table.insert(categories, "[[Kategorie:" .. parent_name .. "|" .. parent.sort .. "]]")
			end
	   else
			table.insert(categories, "[[Kategorie:Older-kategorie besteet neet]]")
	   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, "[[Kategorie:" .. 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("^Kategorie:", "")
		else
			category = "Kategorie:" .. 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

-- Zeige Bild
function show_Bild(current)
	return (current:getBild())
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
	
	table.sort(children, function(first, second) return first.sort < second.sort end)
	
	local children_list = {}
	
	for _, child in ipairs(children) do
		local child_basic = child.name:getCategoryName()
		local child_page = mw.title.new("Kategorie:" .. child_basic)
		
		if child_page.exists then
			local child_description = child.name:getDescription()
			table.insert(children_list, "* [[:Kategorie:" .. 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("Vörlaag:" .. 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("Vörlaag:" .. code .. "-categoryTOC")
		
		if TOC_template.exists then
			return mw.getCurrentFrame():expandTemplate{title = TOC_template.text, args = {}}
		end
	end
	
	return nil
end

return export