มอดูล:Class

คู่มือการใช้งานมอดูล[ดู] [แก้] [ประวัติ] [ล้างแคช]

การใช้งาน

มอดูลนี้ใช้ แม่แบบ:Class, แม่แบบ:Class/icon และแม่แบบ:Class/colour.

เอกสารประกอบสำหรับมอดูล:Class/definition.json

ต่อไปนี้เป็นบันทึกที่แสดงเอกสารแบบจำลองสำหรับคำจำกัดความคลาส JSON

• วัตถุ JSON ระดับบนสุดประกอบด้วยวัตถุจำนวนหนึ่ง วัตถุแต่ละชิ้นเป็นคำจำกัดความของคลาสหรือนามแฝง คีย์คือ "รหัสคลาส" ที่สามารถใช้เป็นอินพุตได้ คีย์ที่มีคำจำกัดความของคลาสคือรหัสคลาสมาตรฐาน รหัสคลาสควรเป็นตัวพิมพ์เล็ก (ยกเว้นรหัสพิเศษ DEFAULT) และรหัสคลาสมาตรฐานจนถึงขณะนี้เป็นตัวอักษรอย่างเคร่งครัด (bplus ไม่ใช่b+)
• นามแฝงควรเป็นอ็อบเจ็กต์ที่มีคุณสมบัติหนึ่งอย่างเท่านั้น alias ซึ่งประกอบด้วยสตริงโค้ดคลาสมาตรฐาน
• คำจำกัดความของคลาสสามารถมีคุณสมบัติได้หลายประการ ดังนี้

  categoryRoot

  (สตริง) รากของชื่อหมวดหมู่สำหรับบทความในคลาสคุณภาพ ตัวอย่างเช่น หมวดหมู่ระดับบนสุดสำหรับบทความเด่นคือ หมวดหมู่:บทความระดับคัดสรร และหมวดหมู่ระดับหัวเรื่องอาจมีอยู่ที่ "หมวดหมู่:บทความระดับคัดสรร" ดังนั้นรากของหมวดหมู่คือ FA-Class

  colour

(วัตถุ) วัตถุที่มีคุณสมบัติที่เกี่ยวข้องกับสี โดยค่าแต่ละค่าภายในนั้นควรเป็นสตริงที่สามารถใช้เป็นค่าสี CSS ได้ เช่น #6699ff

• base

  (สตริง) สตริงสีที่สะท้อนสีพื้นหลังพื้นฐาน

  textOnBlack

  (สตริง) สตริงสีที่สะท้อนสีที่เหมาะสมสำหรับใช้กับข้อความบนพื้นหลังสีดำ

  textOnWhite

  (สตริง) สตริงสีที่สะท้อนสีที่เหมาะสมสำหรับใช้กับข้อความบนพื้นหลังสีขาว

  icon

  (วัตถุ) วัตถุที่มีคุณสมบัติที่เกี่ยวข้องกับไอคอน:

  file

  (สตริง) ชื่อไฟล์ที่ไม่มี File: คำนำหน้า ควรจัดรูปแบบด้วยเครื่องหมายขีดล่าง เช่น Featured_article_star.svg

  default

  (บูล) ว่าควรแสดงไอคอนตามค่าเริ่มต้นหรือไม่ โดยปกติแล้วอันดับคุณภาพสูงเท่านั้นที่จะแสดงไอคอนตามค่าเริ่มต้น

  requiresAttribution

  (บูล) true หาก file คุณสมบัติอ้างอิงถึงไฟล์ที่ไม่ใช่สาธารณสมบัติหรือได้รับอนุญาตภายใต้ CC0 เมื่อไฟล์เป็น PD/CC0 และด้วยเหตุนี้คุณสมบัติ false จึงถูกปิดใช้งานการลิงก์รูปภาพและข้อความอื่น ซึ่งดีต่อการเข้าถึงรูปภาพที่เน้นการตกแต่งโดยเฉพาะ

  labels

  (วัตถุ) วัตถุที่มีสตริงป้ายกำกับ คุณสมบัติป้ายกำกับทั้งหมดเป็นเพียงการเบื้องต้นเท่านั้น

  adjective

  (สตริง) สตริงป้ายกำกับที่อธิบายคำคุณศัพท์ซึ่งสามารถใช้เพื่ออธิบายหน้าที่มีคลาสนี้ ควรใช้ตัวพิมพ์เล็กหรือตัวพิมพ์ใหญ่ในชื่อเรื่อง คุณสมบัตินี้ยังอยู่ในขั้นทดลอง

  full

  (สตริง) สตริงป้ายกำกับที่อธิบายวลีคำนามที่อาจใช้เพื่ออธิบายหน้าที่มีคลาสนี้ ควรใช้ตัวพิมพ์เล็กหรือตัวพิมพ์ใหญ่ในชื่อเรื่อง คุณสมบัตินี้เป็นเพียงการคาดเดา

  short

  (สตริง) สตริงป้ายกำกับที่อธิบายชื่อย่อของคลาสที่สามารถใช้ในบริบทต่างๆ ได้ โดยบ่อยครั้งอาจเป็นแบบเดียวกับรหัสคลาส แต่โดยปกติแล้วควรใช้ตัวพิมพ์ใหญ่ (เช่น Redirect หรือ GA) กฎเกณฑ์เฉพาะอย่างหนึ่งที่นำเข้าสู่คุณสมบัตินี้คือรหัสคลาส unassessed ใช้ ??? ป้ายกำกับย่อ คุณสมบัตินี้เป็นเพียงการคาดเดาเท่านั้น

  tooltip

  (สตริง) สตริงป้ายกำกับพร้อมคำอธิบายเครื่องมือที่ควรใช้เพื่ออธิบายคลาสหากต้องการรายละเอียดเพิ่มเติม คุณสมบัตินี้เป็นทางเลือกและอาจควรระบุเฉพาะเมื่อจำเป็นเท่านั้น

  page

  (สตริง) ชื่อหน้าเต็มของหน้าวิกิที่อธิบายคลาสคุณภาพ โดยควรจัดรูปแบบด้วยช่องว่าง เช่น วิกิพีเดีย:บทความคัดสรร

• ในขณะนี้ยังไม่มีคำจำกัดความว่าคุณสมบัติใดที่อาจเป็นข้อบังคับ หรือเป็นทางเลือกสำหรับคำจำกัดความของคลาส และสำหรับตอนนี้อาจจะปลอดภัยที่สุดที่จะถือว่าคุณสมบัติ "ป้ายกำกับ" นั้นเป็นข้อบังคับ
• วัตถุพิเศษ DEFAULT ซึ่งใช้ตัวพิมพ์ใหญ่เพื่อแยกออกจากคีย์อื่น ๆ จะกำหนดค่าเริ่มต้นที่สามารถใช้ได้โดยควรเป็นวัตถุที่สมบูรณ์ (คุณสมบัติทั้งหมดบังคับ) หรือเป็นนามแฝงของวัตถุที่สมบูรณ์ในกรณีของวิกิพีเดียภาษาอังกฤษ นามแฝงนี้ปัจจุบันเป็นนามแฝงของ unassessed คำจำกัดความของคลาส

Object model notes

-- This module implements [[แม่แบบ:Class]], [[แม่แบบ:Class/icon]] and
-- [[แม่แบบ:Class/colour]].

local mArguments -- lazily loaded
local definitions = mw.loadJsonData('มอดูล:Class/definition.json')

local p = {}

--------------------------------------------------------------------------------
-- Local configuration and messages
--------------------------------------------------------------------------------

local cfg = {
	defaultCode = 'DEFAULT',
	classPrefix = 'assess-',
	globalClass = 'assess',
	defaultClassSuffix = 'default',
	unboldClassSuffix = 'unbold',
	catRootFormat = '%s %s',
	catTopicFormat = '%s %s articles',
	catBasicFormat = '%s articles',
	categoryFormat = '[[:Category:%s|%s]]',
	templateLocation = 'แม่แบบ:Class',
	iconTemplateLocation = 'แม่แบบ:Class/icon',
	colourTemplateLocation = 'แม่แบบ:Class/colour',
	stylesLocation = 'มอดูล:Class/styles.css',
	baseColourPath = {'colour', 'base'},
	iconPath = {"icon", "file"},
	iconDefaultPath = {"icon", "default"},
	iconAttribPath = {"icon", "requiresAttribution"},
	fullLabelPath = {"labels", "full"},
	shortLabelPath = {"labels", "short"},
	categoryRootPath = {"categoryRoot"},
	tooltipPath = {"labels", "tooltip"},
	yes = "yes",
	no = "no", 
	argumentNames = {
		class = "class",
		style = "style"
	},
	getOptions = {
		--First item is localized argument name, second is case-sensitivity
		bold = {"bold", false},
		header = {"header", false},
		image = {"image", false},
		rowspan = {"rowspan", false},
		fullcategory = {"fullcategory", true},
		category = {"category", true},
		topic = {"topic", true}
	}
}

--------------------------------------------------------------------------------
-- Argument helper functions
--------------------------------------------------------------------------------

local function getRawArgs(frame, wrapper)
	--Retrieves the arguments from the frame
	mArguments = mArguments or require('มอดูล:Arguments')
	return mArguments.getArgs(frame, {
		wrappers = wrapper,
		trim = false,
		removeBlanks = false
	})
end

local function makeInvokeFunction(func, wrapper)
	--Wraps a general function into an invokable version
	return function (frame)
		local args = getRawArgs(frame, wrapper)
		return func(args)
	end
end

--------------------------------------------------------------------------------
-- String helper functions
--------------------------------------------------------------------------------

local function trim(str)
	--Trims strings, passes through non-strings without modification
	return (type(str) == 'string') and mw.text.trim(str) or str
end

local function normalizeValue(val)
	--Normalizes strings, particularly class codes
	if type(val) == 'string' then val = trim(val):lower() end
	if val == '' then val = nil end
	return val
end

local function ucfirst(str)
	--Capitalizes the first character of a string
	return mw.ustring.upper(mw.ustring.sub(str, 1, 1)) .. mw.ustring.sub(str, 2)
end

--------------------------------------------------------------------------------
-- Definition helper functions
--------------------------------------------------------------------------------

local function getDefinition(code)
	--Retrieves the definition and canonical class code for a given code.
	--Returns two values: the definition object and the canonical class code
	--string.
	local canonicalCode = normalizeValue(code)
	if code == cfg.defaultCode then canonicalCode = code end
	local class = definitions[canonicalCode]
	while class and class.alias do
		canonicalCode = class.alias
		class = definitions[class.alias]
	end
	if not class then
		return nil, nil
	end
	return class, canonicalCode
end

local function getDefault()
	--Shortcut function for retrieving the default definition
	return getDefinition(cfg.defaultCode) end

local function getProperty(class, default, map)
	--Retrieves a given property from a string given a class definition, a
	--default class definition, and a map for the path to traverse through the
	--class object. The map should be a sequential table of string property
	--names, e.g. {"colour", "base"} would retrieve someClass.colour.base
	local prop, dProp = class, default
	for k, v in ipairs(map) do
		prop = ((type(prop) == 'table') or nil) and prop[v]
		dProp = ((type(dProp) == 'table') or nil) and dProp[v]
	end
	if prop == nil then prop = dProp end
	return prop
end

--------------------------------------------------------------------------------
-- Color functions
--------------------------------------------------------------------------------

function p._colour(code)
	--Retrieves the base colour for a given code
	return getProperty(getDefinition(code), getDefault(), cfg.baseColourPath)
end

function p.colour(frame)
	--Retrieves the base colour for a given code; is invokable
	local args = getRawArgs(frame, cfg.colourTemplateLocation)
	-- Nowiki tags prevent output beginning with "#" from triggering bug 14974.
	return frame:extensionTag('nowiki', p._colour(args[1]))
end

--------------------------------------------------------------------------------
-- Icon functions
--------------------------------------------------------------------------------

function p._icon(args)
	--Retrieves an icon image and formats it as wikitext
	local class = getDefinition(args[cfg.argumentNames.class] or args[1])
	local default = getDefault()
	local file = getProperty(class, default, cfg.iconPath)
	local label = 
		getProperty(class, default, cfg.tooltipPath) or
		ucfirst(getProperty(class, default, cfg.fullLabelPath))
	local attrib = getProperty(class, default, cfg.iconAttribPath)
	local size = args.size or '16px'
	local span = mw.html.create('span')

	span
		:cssText(args[cfg.argumentNames.style])
		:attr('title', label)
		:wikitext(
			string.format(
				'[[File:%s|%s|' .. size .. '%s|class=noviewer|alt=]]',
				file,
				label,
				attrib and '' or '|link='
			)
		)
	return tostring(span)
end

p.icon = makeInvokeFunction(p._icon, cfg.iconTemplateLocation)
--Invokable version of p._icon

--------------------------------------------------------------------------------
-- Class functions
--------------------------------------------------------------------------------

function p._class(args)
	--Parses its arguments into a table cell with an optional icon, a name
	--linked to an appropriate category, and appropriate colour styling
	local classDef, classCode =
		getDefinition(args[cfg.argumentNames.class] or args[1])
	local default = getDefault()
	local iconDefault = getProperty(classDef, default, cfg.iconDefaultPath)
	local shortLabel = getProperty(classDef, default, cfg.shortLabelPath)
	local categoryRoot = getProperty(classDef, default, cfg.categoryRootPath)
	--o is short for "options", go for "get options". Bool true → case-sensitive
	local o, go = {}, cfg.getOptions
	for k, v in pairs(go) do
		o[k] = v[2] and trim(args[v[1]]) or normalizeValue(args[v[1]])
	end

	local cell = mw.html.create(o.header and 'th' or 'td')
	--image=yes forces icon, image=no disables it, otherwise checks default
	local icon = iconDefault and (o.image ~= cfg.no) or (o.image == cfg.yes)
	icon = icon and p.icon(args) .. ' ' or ''

	local category
	if o.fullcategory then
		category = o.fullcategory
	elseif o.category then
		category = string.format(cfg.catRootFormat, categoryRoot, o.category)
	elseif o.topic then
		category = string.format(cfg.catTopicFormat, categoryRoot, o.topic)
	else
		category = string.format(cfg.catBasicFormat, categoryRoot)
	end
	local text = string.format(cfg.categoryFormat, category, shortLabel)
	cell
		:addClass(cfg.globalClass)
		:addClass(
			o.bold == cfg.no and cfg.classPrefix .. cfg.unboldClassSuffix or nil
		)
		:addClass(cfg.classPrefix .. (classCode or cfg.defaultClassSuffix))
		:attr('rowspan', tonumber(o.rowspan))
		:wikitext(mw.getCurrentFrame():extensionTag{ name = 'templatestyles', args = {src = cfg.stylesLocation} }, icon, text)

	return tostring(cell)
end

p.class = makeInvokeFunction(p._class, cfg.templateLocation)
--Invokable version of p._class

return p