Модул:category tree

Ин модул аст, ки барои тавлид намудани категорияи дегхонаи қолибҳои судӣ истифода бурда мешавад. Ин аст, маънои онро надорад, ки бевосита истифода бурда шавад. Баръакс, ҳар як шаблон хоҳад модули зерсохторњо худ, ки сарукордошта хусусияти, ки ба шаблон доранд.

Ин ҳуҷҷатҳо танҳо системаи категорияи дарахти фаро мегирад. Агар шумо дар ҷустуҷӯи хуҷҷатҳо бар Шаблон мушаххас, ё дар бораи чӣ гуна ба илова ё тағйир маълумоти гурӯҳ, ба ҳуҷҷати ки шаблон дид.

Параметрҳо

Модули категорияи дарахт аст, мехонданд:

{{#invoke:category tree|show|template=name of the template|...other parameters...}}

Ҳар шаблон, ки истифода мебарад ин модул бояд модули мазкур бо номи дода, дар шаблон = параметри доранд. як миз бо номи маълумоти, ки дорои параметрҳои гуногун, ки дар аввал ба шаблон гузашт карда шуданд: як миз бо номи маълумоти, ки дорои параметрҳои гуногун, ки дар аввал ба шаблон гузашт карда шуданд: Ин модул зерсохторҳо бояд вазифаи номи нав, ки мегирад параметр ягона содирот.

Аксари шаблонҳои мепазирем ва аз ин маҳмўи умумии нишондиҳандаҳои. Дар параметри бо як Шаблон ба модули гузашт, ки аз тарафи шаблон муайян дар алоҳидагӣ, то на ҳар шаблон ҳатман хоҳад истифода ҳамаи ин. {{famcatboiler}} барои мисол, танҳо коди= параметри ба модул мегузарад.

code=

Рамзи, ки мувофиқи он чӣ 'соҳибӣ' мундариҷаи категорияи мекунад. Ин аст, ки одатан як рамзи забон ба монанди en, балки аз он низ метавонад рамзи скрипт мисли Latn ё кодекси оила забон, вобаста ба, ки чӣ тавр ба Шаблон махсус ба он муносибат аст.

label=

Номи барои чизе аст, ки ҳоло гурӯҳбандӣ кард. Дар зербанди модул муайян, ки чӣ тавр аз муҳимтарин тафсир аст, то онро ба шаблон истифода вобаста аст. Бисёр шаблонҳои аз он истифода диҳад, то маълумоти дар як миз, дар ҳоле ки дигарон онро ҳамчун рамзи забон ягон гиёҳи тафсир кунад.

sc=

Рамзи скрипт намудани адад ба категорияи шавад. Ин аст, ки одатан холӣ, вале бисёре аз гурӯҳҳои ба монанди онҳое, истифода Мандарин Чин метавонад ба зергурӯҳҳо тақсим асоси скрипт.

Кории умумӣ

Модули мазкур дар бораи принсипи ду намуди асосии гурӯҳ асос ёфтааст:

Basic категорияҳои касоне ҳастанд, ки барои он code= параметри аст, холӣ нест. Пас, ин ба забони махсус (ё монанд) тааллуқ ва категорияҳои «мунтазам» мебошанд. Мисолҳо ҳастанд: Category:English nouns, Category:French templates, Category:nl:Linguistics, Category:Шартҳои англисӣ даст аз ҷопонӣ, Category:Ҳарфҳои алифбои лотинӣ.

Umbrella категорияҳои як рамзи надоранд, вале дорои ҳамаи категорияҳои асосии нишонаи онҳо, барои ҳар як кодекси. Инҳо аз ҳониби забони" категорияҳои навъи мебошанд. Намунаҳои аз инҳо иборатанд:Category:Nouns by language, Category:Templates by language, Category:Linguistics, Category:Шартҳои даст аз ҷопонӣ, Category:Ҳарфҳое, бо скрипт.

Баъзе қолибҳои низ як навъи категорияи сеюм, ба категорияи асосии фарқ карда наметавонед. Ин гурӯҳ ҳамчун категорияи волидайн барои категорияҳои чатр истифода бурда мешавад.

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.

---

local export = {}
local m_languages = require('Module:languages')
local m_utilities = require('Module:utilities')

-- 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 template = frame.args["template"]
	
	if not template or template == "" then
		error("The \"template\" parameter was not specified.")
	end
	
	local submodule = require("Module:category tree/" .. template)
	
	-- Get all the parameters and the label data
	local current
	
	if submodule.new_main then
		current = submodule.new_main(frame)
	else
		local info = {}
		
		for key, val in pairs(frame.args) do
			info[key] = val; if info[key] == "" then info[key] = nil end
		end
	
		info.template = nil
		current = submodule.new(info, true)
	end

	local boxes = {}
	local display = {}
	local categories = {}
	
	-- Check if the category is empty
	local isEmpty = mw.site.stats.pagesInCategory(mw.title.getCurrentTitle().text, "all") == 0
	
	-- Are the parameters valid?
	if not current then
		table.insert(categories, "[[Category:Categories with invalid label]]")
		table.insert(categories, isEmpty and "[[Category:Empty categories]]" or nil)
		table.insert(display, show_error(
			"The label 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."))
		
		-- Exit here, as all code beyond here relies on current not being nil
		return table.concat(categories, "") .. table.concat(display, "\n\n")
	end
	
	-- Does the category have the correct name?
	if mw.title.getCurrentTitle().text ~= current:getCategoryName() then
		table.insert(categories, "[[Category:Categories with incorrect name]]")
		table.insert(display, show_error(
			"Based on the parameters given to the " ..
			mw.getCurrentFrame():expandTemplate{title = "temp", args = {template}} ..
			" template, this category should be called '''[[:Category:" .. current:getCategoryName() .. "]]'''."))
	end
	
	-- Add cleanup category for empty categories
	if isEmpty and not current:canBeEmpty() then
		table.insert(categories, "[[Category:Empty categories]]")
	end
	
	if current:isHidden() then
		table.insert(categories, "__HIDDENCAT__")
	end
	
	table.insert(boxes, show_catfix(current))
	table.insert(boxes, show_editlink(current))
	table.insert(boxes, show_pagelist(current))
	
	-- Generate the displayed information
	table.insert(display, show_breadcrumbs(current))
	table.insert(display, show_description(current))
	table.insert(display, show_appendix(current))
	table.insert(display, show_children(current))
	table.insert(display, show_TOC(current))
	
	show_categories(current, categories)
	
	return table.concat(categories, "") .. table.concat(boxes, "\n") .. "\n" .. table.concat(display, "\n\n")
end

function show_error(text)
	return  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 = 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 =
			"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
		
	end
	
	if errortext then
		return (category or "") .. show_error(errortext)
	else
		return nil
	end
end

function show_catfix(current)
	if not current._lang or current._lang:getCode() == "he" or current._lang:getCode() == "ar" then
		return nil
	end
	
	return m_utilities.catfix(current._lang, (sc and require("Module:scripts").getByCode(info.sc) or nil))
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
			if not (current._lang and current:getCategoryName() == mw.getContentLanguage():ucfirst(current._lang:getCategoryName())) and not (current._sc and current:getCategoryName():find(mw.getContentLanguage():ucfirst(current._sc:getCategoryName()), nil, true)) and current:getInfo().code then
				require("Module:debug").track("category tree/string")
			end
			
			table.insert(categories, "[[" .. parent.name .. "|" .. parent.sort .. "]]")
		else
			table.insert(categories, "[[Category:" .. parent.name:getCategoryName() .. "|" .. 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

function show_editlink(current)
	return
		"<div class=\"noprint plainlinks\" style=\"float: right; clear: both; margin: 0 0 .5em 1em; background: #f9f9f9; border: 1px #aaaaaa solid; padding: 5px; font-weight: bold;\">[" ..
		mw.getCurrentFrame():callParserFunction{name = "fullurl", args = {current:getDataModule(), action = "edit"}} ..
		" Edit category data]</div>"
end

function show_pagelist(current)
	local namespace = ""
	local info = current:getInfo()
	
	if info.label == "citations" or info.label == "citations of undefined terms" then
		namespace = "Citations"
	elseif info.code then
		local lang = require("Module:languages").getByCode(info.code)
		
		if lang then
			if lang:getType() == "reconstructed" then
				namespace = "Reconstruction"
			elseif lang:getType() == "appendix-constructed" then
				namespace = "Appendix"
			end
		end
	end
	
	local recent = mw.getCurrentFrame():callParserFunction{
		name = "#tag",
		args = {
			"DynamicPageList",
			"category=" .. mw.title.getCurrentTitle().text .. "\n" ..
			"namespace=" .. namespace .. "\n" ..
			"count=10\n" ..
			"mode=ordered\n" ..
			"ordermethod=categoryadd\n" ..
			"order=descending"
		}
	}
	
	local oldest = mw.getCurrentFrame():callParserFunction{
		name = "#tag",
		args = {
			"DynamicPageList",
			"category=" .. mw.title.getCurrentTitle().text .. "\n" ..
			"namespace=" .. namespace .. "\n" ..
			"count=10\n" ..
			"mode=ordered\n" ..
			"ordermethod=lastedit\n" ..
			"order=ascending"
		}
	}
	
	return [=[
{| class="wikitable" style="float: right; clear: both; margin: 0 0 .5em 1em;"
! Recent additions to the category
|-
| style="font-size:0.9em;" | ]=] .. recent .. [=[

|-
! Oldest pages ordered by last edit
|-
| style="font-size:0.9em;" | ]=] .. oldest .. [=[

|}]=]
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 "")
end

function show_appendix(current)
	local appendix
	
	if current.getAppendix then
		appendix = current:getAppendix()
	end
	
	if appendix then
		return "For more information, see [[" .. appendix .. "]]."
	else
		return nil
	end
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("Category:" .. child_basic)
		
		if child_page.exists then
			local child_description = child.name: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(current)
	local code = current:getInfo().code
	
	if not code or not require("Module:languages").getByCode(code) then
		return nil
	end
	
	-- If category can be empty, then it only contains subcategories.
	local hasPages = not current:canBeEmpty()
	
	local titleText = mw.title.getCurrentTitle().text
	
	local inCategory

	if hasPages then
		inCategory = mw.site.stats.pagesInCategory(titleText, "pages")
	else
		inCategory = mw.site.stats.pagesInCategory(titleText, "subcats")
	end
	
	-- No need for a TOC if all pages or subcategories can fit on one page.
	if inCategory > 200 then
		-- This category is very large, see if there is an "extended" version of the TOC.
		if inCategory > 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