Jump to content
Menü aufrufen
Toggle preferences menu
Persönliches Menü aufrufen
Nicht angemeldet
Ihre IP-Adresse wird öffentlich sichtbar sein, wenn Sie Änderungen vornehmen.
Modul Dokumentation[view][edit][history][purge]
Diese Dokumentation wird von Modul:DataGrid/doc aus übernommen. Änderungen können auf der Diskussionsseite vorgeschlagen werden.
Function list
L 32 — parseGermanNumber
L 59 — wantsLeadImage
L 96 — stripLink
L 107 — fail
L 131 — p.parseVariants
L 152 — p.parseColumns
L 203 — p.columnAlias
L 227 — parseSortKey
L 228 — findAlias
L 269 — p.parseSort
L 296 — p.duplicateAlias
L 319 — findOperator
L 344 — p.parseFilters
L 393 — p.parseCategory
L 434 — resolveProperty
L 469 — p.buildSpec
L 493 — check
L 514 — normalize
L 591 — eyebrowPart
L 631 — eyebrowResolver
L 675 — buildSpecs
L 848 — groupColumnDefs
L 880 — translateDisplay
L 920 — p.runQuery
L 943 — p.sortRows
L 966 — p.resolveArgs
L 1025 — p.main

Baut eine interaktive, filterbare Tabelle aus einer Modul:BucketQuery-Abfrage: eine Kategorie, eine filter-Klauselliste oder beides.

Editoren nutzen dies über {{Data table}}.

Für Modul-Editoren

API

  • p.parseColumns(raw): das mehrzeilige columns-Argument in DataGridColumn[].
  • p.columnAlias(column): der Ergebnisschlüssel einer Spalte: label, sonst der Eigenschaftsname.
  • p.duplicateAlias(columns, options): der erste kollidierende Alias oder nil.
  • p.parseFilters(raw): das filter-Argument in Store-Filter; Eigenschaft = A; B ist die ODER-Form (|| wird auch akzeptiert).
  • p.parseCategory(raw): das category-Argument in einen Kategorie-Filter.
  • p.parseSort(raw, columns): das sort-Argument (kommagetrennte Schlüssel, je <Label oder Eigenschaft> [asc|desc]) in eine Präzedenzliste.
  • p.buildSpec(kind, categoryFilter, filters, columns, options): die Store.query-Spezifikation; jede Eigenschaft wird gegen Store aufgelöst, damit eine unbekannte hier fehlschlägt statt als leere Spalte.
  • p.resolveArgs(args, options): die ganze Argumenttabelle in { spec, columns, kind, sort }, oder nil plus anzeigefertige Meldung beim ersten Vertragsbruch. Modul:DataGrid/Static ruft es ebenfalls, was eine Grammatik und ein Meldungsset hinter beiden Vorlagen hält.
  • p.runQuery(spec): führt die Abfrage aus und enthält einen Infrastrukturfehler statt die Seite skriptfeheln zu lassen.
  • p.sortRows(results): ordnet die Ergebnisse nach dem Name-Alias, in Place.
  • p.main(frame): Wikitext-Einstieg.

Spaltenkinds kommen aus Store.resolve(property, kind).type: PAGE wird link, wiederholt linkList; wiederholte Nicht-PAGE-Eigenschaft valueList; INTEGER/DOUBLE number; BOOLEAN boolean; sonst smart. Ein kind= auf der Spalte übersteuert das.

Stolperfallen

  • Mit dem Entity-SMW-Backend nutzen kind=Vehicle, kind=Item, kind=Mission, kind=Location und kind=Commodity eine SMW-Abfrage statt AG Grid (Modul:DataGrid/Smw); ein fehlendes kind ist dort kein Fehler, sondern rendert im kindlosen Modus, den {{Manufacturer products}} braucht, weil die Produkte eines Herstellers Arten überspannen. Jede Spalte und jeder Filter muss auf ein Entity-Bucket-Feld auflösen, dessen deutsche Eigenschaft ein Feld allein schreibt; ein Feld eines anderen Buckets oder ein Name, dessen Eigenschaft mehrere Felder teilen, rendert als Inline-Fehler.
  • Die SMW-Tabelle unterstützt Kategorie-, Gleichheits-, Ungleichheits-, Zahlenvergleichs-, Präsenz- und ODER-Filter. Spaltendekorationen und das Lead-Bild werden nicht gerendert.
  • Die Lead-Spalten sind Seitentitel (Name), Seitenbild (Image) und gespeicherter Name (DisplayName) vor den eigenen des Editors; options.leadImage = false gibt den Image-Alias frei.
  • main ruft sortRows direkt nach runQuery; ohne sort listen Zeilen nach Seitentitel.
  • kind=bar skaliert jede Zelle gegen den größten Absolutwert ihrer Spalte über alle Zeilen, nicht pro Zelle.
  • Vollrendering (Lead-Karte, smarte Sortierung) hängt am Gadget aggridRenderers — auf diesem Wiki ohne AG-Grid-Extension laufen die SMW-Pfade.

require('strict')

--- Generic browse-table component on AG Grid (Extension:AGGrid). Reads a
--- Store spec on either backend: `category` (direct membership, `A; B` for
--- disjunction), `filter` (one clause per line) and `kind` (which manifest
--- answers for a name two manifests declare) become a spec run by
--- Module:BucketQuery on Bucket and by Module:Entity/Store's SMW reader on
--- SMW (property names canonicalized first, vocab values translated back to
--- their stored German for display); result rows and manifest types drive
--- the AG Grid rowData + columnDefs.
---
--- Column model: a single card lead (thumbnail + linked name, optional eyebrow
--- from a column flagged `eyebrow`), then one column per editor line. An eyebrow
--- column feeds the lead card and is not emitted as its own column. Each
--- remaining editor column is classified from its manifest type: PAGE becomes a
--- link column (aggridLink), or a link list (aggridLinkList) when repeated; a
--- repeated non-PAGE property becomes a value list; INTEGER/DOUBLE becomes a
--- numeric column; BOOLEAN becomes the tri-state icon column; anything else is
--- plain (the gadget's scwSmart type). `kind=effect|bar|boolean` overrides the
--- classification. A `filter`-flagged column gets the extension's set filter,
--- which splits each cell into one option per value.

local Util
local aggrid
local yesno = require('Module:Yesno')
local BucketQuery = require('Module:BucketQuery')
-- The German-number grammar lives with the SMW number authority
-- (Entity/StructuredData/Smw, beside its germanNumber serializer): the filter
-- literal and the stored value it compares against share one definition, so
-- the two grammars cannot drift apart. Required lazily, like every
-- SMW-backend dependency: the Bucket path never loads the crosswalk.
local function parseGermanNumber(s)
	return require('Module:Entity/StructuredData/Smw').parseGermanNumber(s)
end

local p = {}

-- Result-row keys for the lead columns buildSpec adds ahead of the editor's own.
local IMAGE_ALIAS = 'Image'
local NAME_ALIAS = 'Name'
local DISPLAY_ALIAS = 'DisplayName'

--- @class DataGridOptions
--- @field leadImage? boolean  `false` drops the Image lead column and frees its
--- alias for an editor column. Module:DataGrid/Static passes it, because a
--- wikitable's image is a column the editor places; the grid's lead card is the
--- image, so the grid never does.
--- @field primary? string  Base table the Store query roots on, default `entity`.
--- Deliberately not an editor-facing `{{Data table}}` parameter: rooting on the
--- wrong table silently changes which rows exist rather than erroring. A table
--- whose subject is not an Entity page sets it (Module:Maintenance roots on
--- `maintenance`, because filtering a joined bucket makes that join INNER and
--- rooting on `entity` would drop every page with no Entity row).

--- Whether a caller keeps the Image lead column. No options at all is the grid's
--- shape: all three lead columns, `Image` reserved.
--- @param options DataGridOptions|nil
--- @return boolean
local function wantsLeadImage(options)
	return options == nil or options.leadImage ~= false
end

-- `kind=` values Store's manifests disambiguate on.
local KINDS = {
	Vehicle = true,
	Item = true,
	Commodity = true,
	Location = true,
	Mission = true,
	Company = true,
	['Wearable set'] = true,
}

local NUMBER_FORMAT = { style = 'number' }

-- Operator patterns. findOperator (below) picks whichever of these starts
-- earliest in the line, so a relational operator inside the VALUE (e.g. "Name
-- = A<=B") never pre-empts an earlier "=". List order only breaks a tie
-- between two candidates starting at the same position ("<=" over "<", ">="
-- over ">"): longer wins.
local OPERATORS = { '<=', '>=', '!=', '=', '<', '>' }
local NUMERIC_OPS = { ['<'] = true, ['<='] = true, ['>'] = true, ['>='] = true }

-- Lead card geometry. The lead flexes to absorb any leftover horizontal space
-- (the data columns auto-size to content, so short tables would otherwise leave a
-- ragged gap on the right); LEAD_WIDTH is its floor, not a fixed width. Rows are
-- compact when the card is just thumbnail + name, taller when an eyebrow adds a
-- second line.
local LEAD_WIDTH = 260
local ROW_HEIGHT = 48
local EYEBROW_ROW_HEIGHT = 60

--- Strip `[[…]]`/`[[:…]]` wikilink markup to its target, else trim the value as-is.
--- @param value string
--- @return string
local function stripLink(value)
	local inner = value:match('^%[%[:?(.-)%]%]$')
	if inner then
		value = inner:match('^([^|]*)') or inner
	end
	return mw.text.trim(value)
end

--- Wrap an error message in the module's inline-error markup.
--- @param msg string
--- @return string
local function fail(msg)
	return '<strong class="error">Module:DataGrid: ' .. mw.text.nowiki(msg) .. '</strong>'
end

--- @class DataGridColumn
--- @field property string
--- @field label? string
--- @field size? string    Parsed for forward-compatibility; unused (see README).
--- @field filter? boolean
--- @field eyebrow? boolean Promote this column into the lead card's eyebrow.
--- @field kind? string  Override the auto-classified column kind (e.g. `effect`, `bar`).
--- @field variants? table<string, string>  For `kind=badge`: value -> badge variant.
--- @field good? string  For `kind=bar`: 'higher' | 'lower', the direction that helps.
--- @field group? string  Header this column sits under; consecutive matches nest together.
--- @field prefix? string  For `eyebrow`: joined before the value, no space ("1" -> "S1").
--- @field suffix? string  For `eyebrow`: unit appended after a space ("5" -> "5 charges").
--- @field suffix1? string  The `suffix` to use when the value is exactly 1 ("1 charge").

--- Parse a `variants` modifier, `Value:variant, Value:variant`, into a map from
--- cell value to badge variant (`success`, `warning` or `error`; the gadget
--- renders any other name as a neutral pill). The value is split from its variant
--- at the last colon, so a value may itself contain one.
--- @param raw string
--- @return table<string, string>
function p.parseVariants(raw)
	local variants = {}
	for pair in mw.text.gsplit(raw, ',', true) do
		local value, variant = mw.text.trim(pair):match('^(.-)%s*:%s*([^:]-)$')
		if value and value ~= '' and variant ~= '' then
			variants[value] = variant
		end
	end
	return variants
end

--- Parse the multi-line `columns` value. Carried over from Module:DataTableLua:
--- one column per non-blank line; within a line, `;`-separated clauses where the
--- first is the property and the rest are modifiers (`label=X`, `size=X`,
--- `kind=X`, `good=higher|lower`, `group=X`, `prefix=X`, `suffix=X`, `suffix1=X`,
--- `variants=Value:variant, ...`, or the bare flags `filter` / `eyebrow`).
--- `eyebrow` promotes the column into the lead card instead of rendering it as its
--- own column. `good` applies to `kind=bar` only, naming the direction that helps
--- the reader. Unknown clauses are ignored. Empty-property lines drop.
--- @param raw string
--- @return DataGridColumn[]
function p.parseColumns(raw)
	local columns = {}
	for line in (tostring(raw or '') .. '\n'):gmatch('([^\n]*)\n') do
		line = mw.text.trim(line)
		if line ~= '' then
			local column = {}
			local isFirst = true
			for clause in (line .. ';'):gmatch('([^;]*);') do
				clause = mw.text.trim(clause)
				if isFirst then
					column.property = clause
					isFirst = false
				elseif clause ~= '' then
					local key, value = clause:match('^(.-)%s*=%s*(.*)$')
					if key == 'label' then
						column.label = value
					elseif key == 'size' then
						column.size = value
					elseif key == 'kind' then
						column.kind = value
					elseif key == 'good' then
						column.good = value
					elseif key == 'group' then
						column.group = value
					elseif key == 'prefix' then
						column.prefix = value
					elseif key == 'suffix' then
						column.suffix = value
					elseif key == 'suffix1' then
						column.suffix1 = value
					elseif key == 'variants' then
						column.variants = p.parseVariants(value)
					elseif clause == 'filter' then
						column.filter = true
					elseif clause == 'eyebrow' then
						column.eyebrow = true
					end
				end
			end
			if column.property and column.property ~= '' then
				columns[#columns + 1] = column
			end
		end
	end
	return columns
end

--- The result-row key for an editor column: its `label`, else the property name
--- verbatim.
--- @param column DataGridColumn
--- @return string
function p.columnAlias(column)
	if column.label and column.label ~= '' then
		return column.label
	end
	return column.property
end

--- @class DataGridSort
--- @field alias string  The matching column's result-row key (`columnAlias`).
--- @field direction 'asc'|'desc'

--- Parse one sort key: `<label or property> [asc|desc]`, direction defaulting to
--- `asc`. The name matches a column's alias (`columnAlias`) or its raw `property`,
--- so `sort=Subtype` still finds a column relabelled `label=Type`, or `Name` for
--- the lead card, which no editor column may be named (`duplicateAlias`). A name may
--- itself contain spaces (e.g. "Weapon class"), so the whole string is tried as a
--- bare name first; only when that fails is the trailing word split off as the
--- direction. An `eyebrow` column is excluded from matching: it is folded into the
--- lead card rather than getting its own spec, so naming one is an error
--- (`no column named`), not a silent no-op.
--- @param raw string  trimmed, non-empty
--- @param columns DataGridColumn[]
--- @return DataGridSort|nil key
--- @return string|nil error  ready to display as-is
local function parseSortKey(raw, columns)
	local function findAlias(name)
		if name == NAME_ALIAS then
			return NAME_ALIAS
		end
		for _, column in ipairs(columns) do
			if not column.eyebrow then
				local alias = p.columnAlias(column)
				if alias == name or column.property == name then
					return alias
				end
			end
		end
		return nil
	end
	local alias = findAlias(raw)
	if alias then
		return { alias = alias, direction = 'asc' }, nil
	end
	local name, word = raw:match('^(.-)%s+(%S+)$')
	if not name then
		return nil, 'sort "' .. raw .. '": no column named ' .. raw
	end
	alias = findAlias(name)
	if not alias then
		return nil, 'sort "' .. name .. '": no column named ' .. name
	end
	if word ~= 'asc' and word ~= 'desc' then
		return nil, 'sort "' .. word .. '": direction must be asc or desc'
	end
	return { alias = alias, direction = word }, nil
end

--- Parse the `sort` argument: comma-separated keys in priority order, each
--- `<label or property> [asc|desc]` (see `parseSortKey`). Blank keys are skipped.
--- A column named twice is an error: AG Grid would keep only one of its keys. A
--- label containing a comma is not expressible: the separator wins, so such a
--- column is named by its property.
--- @param raw string|nil
--- @param columns DataGridColumn[]
--- @return DataGridSort[]|nil sort  nil for an empty (or absent) `raw`
--- @return string|nil error  ready to display as-is
function p.parseSort(raw, columns)
	local keys, seen = {}, {}
	for part in mw.text.gsplit(tostring(raw or ''), ',', true) do
		part = mw.text.trim(part)
		if part ~= '' then
			local key, err = parseSortKey(part, columns)
			if err then
				return nil, err
			end
			if seen[key.alias] then
				return nil, 'sort "' .. key.alias .. '": column named twice'
			end
			seen[key.alias] = true
			keys[#keys + 1] = key
		end
	end
	if #keys == 0 then
		return nil, nil
	end
	return keys, nil
end

--- The first editor column whose alias collides with another column or with a lead
--- key. Store keys rows by alias, so a collision silently drops a column's data.
--- @param columns DataGridColumn[]
--- @param options DataGridOptions|nil
--- @return string|nil  the offending alias, or nil when all are unique
function p.duplicateAlias(columns, options)
	local seen = { [NAME_ALIAS] = true, [DISPLAY_ALIAS] = true }
	if wantsLeadImage(options) then
		seen[IMAGE_ALIAS] = true
	end
	for _, column in ipairs(columns) do
		local alias = p.columnAlias(column)
		if seen[alias] then
			return alias
		end
		seen[alias] = true
	end
	return nil
end

--- Finds the operator a filter line splits on: whichever OPERATORS candidate
--- starts earliest in the line (so an operator-shaped substring inside the
--- VALUE never pre-empts an earlier one, e.g. "Name = A<=B" splits on the
--- first "="); among candidates tied at the same start position, the longest
--- wins ("<=" over "<", "!=" over "=").
--- @param line string
--- @return string|nil op
--- @return integer|nil at  1-based index the match starts at
local function findOperator(line)
	local bestOp, bestAt
	for _, candidate in ipairs(OPERATORS) do
		local at = line:find(candidate, 1, true)
		if at and (bestAt == nil or at < bestAt or (at == bestAt and #candidate > #bestOp)) then
			bestOp, bestAt = candidate, at
		end
	end
	return bestOp, bestAt
end

--- Parse the multi-line `filter` value. One clause per non-blank line:
--- `Property = Value`, `Property = A; B`, `Property != Value`, `Property = +`,
--- `Property <op> Number` for <, <=, >, >=. `||` is also accepted for the Or
--- form (it arrives from an editor's `{{!}}{{!}}`); `;` is preferred because a
--- raw `|` cannot survive inside a template parameter. The property name and
--- every value are entity-decoded, so a `{{PAGENAME}}`-derived value
--- (`Klaus &#38; Werner`) matches Bucket's stored text.
--- A value containing `;` is not expressible: the separator wins.
--- A relational value stays the editor's literal: which grammar reads it
--- (dot decimal or German comma/grouping) is decided in buildSpec, where the
--- field's type and the backend are known.
--- @param raw string|nil
--- @return table[]|nil filters  Store filter entries
--- @return string|nil error  the first line that does not parse
function p.parseFilters(raw)
	local filters = {}
	for line in (tostring(raw or '') .. '\n'):gmatch('([^\n]*)\n') do
		line = mw.text.trim(line)
		if line ~= '' then
			local property, op, rest
			local bestOp, at = findOperator(line)
			if bestOp then
				property, op, rest = mw.text.trim(line:sub(1, at - 1)), bestOp, mw.text.trim(line:sub(at + #bestOp))
				-- Decode BEFORE splitting on ";": an HTML entity's own syntax ends in
				-- ";" (e.g. "&#38;"), so splitting first would fragment it.
				property = mw.text.decode(property, true)
				rest = mw.text.decode(rest, true)
			end
			if not property or property == '' or rest == '' then
				return nil, line
			end
			if op == '=' and rest == '+' then
				filters[#filters + 1] = { property, '+' }
			elseif op == '=' and (rest:find(';', 1, true) or rest:find('||', 1, true)) then
				local any = {}
				for chunk in (rest .. ';'):gmatch('([^;]*);') do
					for part in (chunk .. '||'):gmatch('(.-)||') do
						part = stripLink(part)
						if part ~= '' then
							any[#any + 1] = { property, '=', part }
						end
					end
				end
				if #any == 0 then
					return nil, line
				end
				filters[#filters + 1] = { any = any }
			elseif NUMERIC_OPS[op] then
				filters[#filters + 1] = { property, op, rest }
			else
				filters[#filters + 1] = { property, op, stripLink(rest) }
			end
		end
	end
	return filters, nil
end

--- Parse `category`: names separated by `;` (or legacy `||`, which arrives
--- from an editor's `{{!}}{{!}}`), direct membership only. Names are
--- entity-decoded, so a `{{PAGENAME}}`-derived name matches a real category.
--- @param raw string|nil
--- @return string|table|nil filter
--- @return string|nil error  a part carrying a `|` or `+depth` modifier
function p.parseCategory(raw)
	raw = mw.text.trim(tostring(raw or ''))
	if raw == '' then
		return nil, nil
	end
	-- Decode BEFORE splitting on ";": an HTML entity's own syntax ends in ";"
	-- (e.g. "&#38;"), so splitting first would fragment it.
	raw = mw.text.decode(raw, true)
	local parts = {}
	for chunk in (raw .. ';'):gmatch('([^;]*);') do
		for part in (chunk .. '||'):gmatch('(.-)||') do
			part = mw.text.trim(part)
			if part:find('|', 1, true) or part:find('+depth', 1, true) then
				return nil, part
			end
			if part ~= '' then
				parts[#parts + 1] = 'Category:' .. part
			end
		end
	end
	if #parts == 0 then
		return nil, raw
	end
	if #parts == 1 then
		return parts[1], nil
	end
	return { any = parts }, nil
end

--- Resolves a column or filter name to its manifest entry: the manifest's
--- display name first (the cross-wiki surface), then, on the SMW backend
--- only, the German property label the crosswalk writes, which is that
--- wiki's editor surface. A kindless table on SMW resolves through the
--- fail-closed entity-bucket-only mode instead (a manifest name another
--- bucket owns must refuse there, not blend kinds through one SMW property).
--- buildSpec and buildSpecs both resolve through here, so a German label
--- classifies its column the same way it validates.
--- @param name string
--- @param kind string|nil
--- @return table|nil entry
--- @return string|nil error  a German label's resolution refusal
local function resolveProperty(name, kind)
	local smw = require('Module:Entity/StructuredData').backend() == 'smw'
	if kind == nil and smw then
		-- The crosswalk raises on a name it must refuse (a field another
		-- bucket owns, a property two fields share); carry that message out as
		-- this function's own error shape.
		local ok, resolved = pcall(require('Module:DataGrid/Smw').resolveColumn, name, nil)
		if not ok then
			return nil, tostring(resolved)
		end
		return resolved
	end
	local entry = BucketQuery.resolve(name, kind)
	if entry == nil and smw then
		-- The crosswalk raises on a German label shared by fields with
		-- different vocabularies that the kind cannot resolve; carry that
		-- message out as this function's own error shape.
		local ok, resolved = pcall(require('Module:DataGrid/Smw').resolveColumn, name, kind)
		if not ok then
			return nil, tostring(resolved)
		end
		entry = resolved
	end
	return entry
end

--- The Store spec for a table. Resolves every column so a bad name is an error
--- the editor sees, not an empty column.
--- @param kind string|nil
--- @param categoryFilter string|table|nil
--- @param filters table[]
--- @param columns DataGridColumn[]
--- @param options DataGridOptions|nil
--- @return table|nil spec
--- @return string|nil error
function p.buildSpec(kind, categoryFilter, filters, columns, options)
	local lead = { { builtin = 'page_name', as = NAME_ALIAS } }
	if wantsLeadImage(options) then
		lead[#lead + 1] = { property = 'Image', as = IMAGE_ALIAS }
	end
	lead[#lead + 1] = { property = 'Name', as = DISPLAY_ALIAS }
	local spec = {
		primary = options and options.primary or nil,
		kind = kind,
		filters = {},
		columns = lead,
		limit = 1000,
	}
	if categoryFilter then
		spec.filters[1] = categoryFilter
	end
	-- `op` is given only for a filter clause: a relational operator over a
	-- non-numeric entry or `!=` over a repeated one is a static contract
	-- violation, caught here rather than surfacing as a Store runtime error.
	-- On the SMW backend the German property label also resolves, because it
	-- is that wiki's editor surface; the Bucket backend keeps manifest-only
	-- names so the AG path never sees a name it cannot query.
	local german = require('Module:Entity/StructuredData').backend() == 'smw'

	local function check(property, op)
		local entry, err = resolveProperty(property, kind)
		if entry == nil then
			return err or "unknown property '" .. property .. "'"
		end
		if NUMERIC_OPS[op] and entry.type ~= 'INTEGER' and entry.type ~= 'DOUBLE' then
			return '"' .. property .. '" is not numeric; ' .. op .. ' needs a number column'
		end
		if op == '!=' and entry.repeated then
			return '"' .. property .. '" is a list; != cannot be applied'
		end
		return nil, entry
	end

	-- A numeric field's filter value becomes a Bucket-scale Lua number here,
	-- because only now is the field's type known: the German editor surface
	-- writes de format (parseGermanNumber), the Bucket backend a dot decimal
	-- (tonumber, relational only - Bucket's SQL layer coerces its own equality
	-- strings). Every other value keeps its string: a text field's
	-- numeric-looking value must never coerce. An unparseable literal is an
	-- editor error, not a silently rescaled condition.
	local function normalize(property, op, value)
		local err, entry = check(property, op)
		if err then
			return nil, err
		end
		local numericEquality = german
			and op == '='
			and entry.bucket == 'item_component'
			and (entry.field == 'pitch' or entry.field == 'yaw')
		if value == nil or entry.type ~= 'INTEGER' and entry.type ~= 'DOUBLE' and not numericEquality then
			return value
		end
		if op ~= '=' and op ~= '!=' and not NUMERIC_OPS[op] then
			return value
		end
		if type(value) == 'number' then
			return value
		end
		if not german and not NUMERIC_OPS[op] then
			return value
		end
		-- No grammar fallback: a dot decimal the German parser cannot read is
		-- rejected, not re-read in the other wiki's grammar.
		local n
		if german then
			n = parseGermanNumber(value)
		else
			n = tonumber(value)
		end
		if n == nil then
			return nil,
				'"' .. tostring(value) .. '" is not a number' .. (german and ' (German format: 1,5 or 1.000)' or '')
		end
		return n
	end
	for _, column in ipairs(columns) do
		local err = check(column.property)
		if err then
			return nil, err
		end
		spec.columns[#spec.columns + 1] = { property = column.property, as = p.columnAlias(column) }
	end
	for _, f in ipairs(filters) do
		local normalized = f.any and { any = {} } or nil
		for _, sub in ipairs(f.any and f.any or { f }) do
			local value, err = normalize(sub[1], sub[2], sub[3])
			if err then
				return nil, err
			end
			local copy = { sub[1], sub[2], value }
			if normalized then
				normalized.any[#normalized.any + 1] = copy
			else
				normalized = copy
			end
		end
		spec.filters[#spec.filters + 1] = normalized
	end
	return spec, nil
end

--- One eyebrow column's value as `{ text, href? }`: a linked label for a PAGE
--- property, else plain text. `page` decides which, since a plain-text
--- property's raw value must never be treated as a page title. No icon — the
--- brand glyph is PledgeVehicleGrid-specific. nil when the value is empty.
---
--- A composed eyebrow strips the column headers that would otherwise say what a
--- number is — "S1 · 1 · Active" tells a reader nothing — so `prefix` and `suffix`
--- put the unit back. They join differently on purpose, matching how each is
--- actually written: `prefix` has NO space, because Star Citizen writes a size as
--- "S1"; `suffix` takes one, because a unit is a separate word ("5 charges",
--- "60 s"). `suffix1` is the singular, used when the value is exactly 1 — most
--- passive modules have one charge, so "1 charges" would be wrong on more rows
--- than it is right.
--- @param result table
--- @param part table  { alias, page, prefix?, suffix?, suffix1? }
--- @return table|nil
local function eyebrowPart(result, part)
	local value = result[part.alias]
	if part.page then
		local target, display = Util.pageTarget(value)
		if target then
			local link = aggrid.link(target, display)
			return {
				text = (link and link.text) or display or target,
				href = link and link.href,
			}
		end
	end
	local text = Util.toText(value)
	if text == nil or text == '' then
		return nil
	end
	local suffix = part.suffix
	if suffix and part.suffix1 and tonumber(text) == 1 then
		suffix = part.suffix1
	end
	if suffix and suffix ~= '' then
		text = text .. ' ' .. suffix
	end
	if part.prefix and part.prefix ~= '' then
		text = part.prefix .. text
	end
	return { text = text }
end

--- The lead card's eyebrow resolver, closed over every `eyebrow` column's key.
--- Several columns compose one line — "Active · 5 charges · 60 s" — so the specs a
--- reader needs to identify a row travel in the lead instead of costing a column
--- each. Only a single part keeps its link: a composed line has no one target.
---
--- `filterPart` is the column the lead's set filter keys on, surfaced separately as
--- `full` (the Card kind's set-filter value). Without it the whole composed line
--- would become the filter option, which is one option per row.
--- @param parts table[]  { alias, page, prefix?, suffix?, suffix1? }
--- @param filterPart table|nil
--- @return fun(result: table): table|nil
local function eyebrowResolver(parts, filterPart)
	Util = require('Module:AGGridColumns/Util')
	aggrid = require('mw.ext.aggrid')
	return function(result)
		local rendered = {}
		local single
		for _, part in ipairs(parts) do
			local resolved = eyebrowPart(result, part)
			if resolved then
				rendered[#rendered + 1] = resolved.text
				single = (#rendered == 1) and resolved or nil
			end
		end
		if #rendered == 0 then
			return nil
		end
		local text = table.concat(rendered, ' · ')
		local full = text
		if filterPart then
			-- The filter keys on ONE column, not the composed line, which would give an
			-- option per row. It uses that column's DECORATED text, so a size filter
			-- lists "S1" — the term a reader recognises — rather than a bare "1".
			local resolved = eyebrowPart(result, filterPart)
			full = resolved and resolved.text or nil
		end
		return {
			text = text,
			full = full,
			href = single and single.href or nil,
		}
	end
end

--- Build the AGGridColumns column specs for this query: a single card lead
--- (thumbnail + linked name, optional eyebrow), then one spec per editor column,
--- classified from its manifest type. A column flagged `eyebrow` feeds the lead
--- card and is not emitted as its own column.
--- @param results table[]
--- @param columns DataGridColumn[]
--- @param eyebrowColumns DataGridColumn[]
--- @param pinLead boolean
--- @param kind string|nil
--- @param sort DataGridSort[]|nil  Each key applied to the spec whose `label` matches its `alias`.
--- @return table[]
local function buildSpecs(results, columns, eyebrowColumns, pinLead, kind, sort)
	Util = require('Module:AGGridColumns/Util')
	aggrid = require('mw.ext.aggrid')
	local leadSpec = {
		kind = 'card',
		field = 'lead',
		header = NAME_ALIAS,
		titleLabel = NAME_ALIAS,
		imageLabel = IMAGE_ALIAS,
		displayLabel = DISPLAY_ALIAS,
		filterOn = 'title',
		filter = 'agTextColumnFilter',
	}
	-- Sizing. Unpinned, the lead grows to fill horizontal slack left by the
	-- content-sized data columns, so rows span the full container instead of ending
	-- short; LEAD_WIDTH floors it. Pinned, it takes that as a FIXED width: a pinned
	-- column lives outside AG Grid's centre viewport, where flex has nothing to flex
	-- against, and the two together leave the column unpinned.
	--
	-- Pinning keeps the lead on screen while the data columns scroll under it.
	-- Sideways scrolling is not what makes a wide table unusable; losing track of
	-- which row you are reading is. Opt-in, because pinning splits the viewport and
	-- draws a divider even when nothing overflows.
	if pinLead then
		leadSpec.pinned = 'left'
		leadSpec.width = LEAD_WIDTH
	else
		leadSpec.flex = 1
		leadSpec.minWidth = LEAD_WIDTH
	end
	if eyebrowColumns[1] then
		local parts, filterPart = {}, nil
		for _, column in ipairs(eyebrowColumns) do
			local entry = resolveProperty(column.property, kind)
			local part = {
				alias = p.columnAlias(column),
				page = entry.type == 'PAGE',
				prefix = column.prefix,
				suffix = column.suffix,
				suffix1 = column.suffix1,
			}
			parts[#parts + 1] = part
			if column.filter and not filterPart then
				filterPart = part
			end
		end
		leadSpec.eyebrow = eyebrowResolver(parts, filterPart)
		-- A `filter`-flagged eyebrow moves the lead's filter off the name and onto
		-- that value as a checkbox set — "show me only the Active modules". The name
		-- stays searchable through the grid's quickSearch box, so nothing is lost.
		if filterPart then
			leadSpec.filterOn = 'eyebrow'
			leadSpec.filter = 'aggridSet'
		end
	end
	local specs = { leadSpec }
	local groups = { false }
	for i, column in ipairs(columns) do
		if not column.eyebrow then
			groups[#specs + 1] = (column.group ~= nil and column.group ~= '') and column.group or false
			local alias = p.columnAlias(column)
			local header = (column.label and column.label ~= '') and column.label or column.property
			if column.kind == 'effect' then
				-- Dietary-effect badge list: each value classified by Module:DietaryEffect;
				-- the set filter splits the cell into one option per effect.
				specs[#specs + 1] = {
					kind = 'badgeList',
					field = 'c' .. i,
					header = header,
					label = alias,
					classify = require('Module:DietaryEffect').gridClassify,
					filter = 'aggridSet',
				}
			elseif column.kind == 'bar' then
				-- Bars are scaled on the column, so the spec carries the largest
				-- magnitude in it; a per-cell scale would make two rows incomparable,
				-- which is the whole point of drawing them.
				local max = 0
				for _, result in ipairs(results) do
					local n = Util.toNumber(result[alias])
					if n ~= nil and math.abs(n) > max then
						max = math.abs(n)
					end
				end
				specs[#specs + 1] = {
					kind = 'signedBar',
					field = 'c' .. i,
					header = header,
					label = alias,
					good = column.good,
					max = max,
				}
			elseif column.kind == 'boolean' then
				-- Tri-state boolean: each value classified by Module:Boolean,
				-- rendered icon-only; the set filter keys on "Yes"/"No".
				specs[#specs + 1] = {
					kind = 'boolean',
					field = 'c' .. i,
					header = header,
					label = alias,
					filter = 'aggridSet',
				}
			elseif column.kind == 'badge' then
				-- A pill per value, coloured by the column's `variants`; the kind's
				-- set filter and sort key on the text.
				specs[#specs + 1] = {
					kind = 'badge',
					field = 'c' .. i,
					header = header,
					label = alias,
					variants = column.variants,
				}
			elseif column.kind == 'date' then
				-- An ISO date: the kind brings AG Grid's date filter and date type.
				specs[#specs + 1] = {
					kind = 'date',
					field = 'c' .. i,
					header = header,
					label = alias,
					filter = column.filter and 'aggridSet' or nil,
				}
			else
				local entry = resolveProperty(column.property, kind)
				local filter = column.filter and 'aggridSet' or 'agTextColumnFilter'
				local spec = { field = 'c' .. i, header = header, label = alias }
				if entry.type == 'PAGE' then
					spec.kind = entry.repeated and 'linkList' or 'link'
					spec.filter = filter
				elseif entry.repeated then
					spec.kind = 'valueList'
					spec.filter = filter
				elseif entry.type == 'INTEGER' or entry.type == 'DOUBLE' then
					spec.kind = 'number'
					spec.format = NUMBER_FORMAT
					spec.filter = column.filter and 'aggridSet' or nil
				elseif entry.type == 'BOOLEAN' then
					spec.kind = 'boolean'
					spec.filter = 'aggridSet'
				else
					spec.kind = 'smart'
					spec.filter = filter
				end
				specs[#specs + 1] = spec
			end
		end
	end
	-- Every kind's buildColDef passes `sort` through to AG Grid's initial-sort key,
	-- so setting it on the matching spec is enough regardless of column kind.
	-- `sortIndex` (0-based precedence among the sorted columns) reaches the column
	-- def through AGGridColumns.buildColumnDefs. The lead card, specs[1], answers
	-- to NAME_ALIAS.
	for n, key in ipairs(sort or {}) do
		for i, spec in ipairs(specs) do
			if (i == 1 and NAME_ALIAS or spec.label) == key.alias then
				spec.sort = key.direction
				spec.sortIndex = n - 1
				break
			end
		end
	end
	return specs, groups
end

--- Nest runs of consecutive columns that share a `group` into AG Grid column
--- groups. Grouping is what turns nine unfamiliar stat names into the two or three
--- questions a reader actually has ("what does the rock do", "what do I take
--- home"), so it is a header row, not decoration.
---
--- Only CONSECUTIVE matches nest: a group is a position in the table, and letting
--- non-adjacent columns join one would silently reorder the editor's columns.
--- @param defs table[]
--- @param groups (string|false)[]  aligned with defs
--- @return table[]
local function groupColumnDefs(defs, groups)
	local out = {}
	local i = 1
	while i <= #defs do
		local group = groups[i]
		if not group then
			out[#out + 1] = defs[i]
			i = i + 1
		else
			local children = {}
			while i <= #defs and groups[i] == group do
				children[#children + 1] = defs[i]
				i = i + 1
			end
			out[#out + 1] = { headerName = group, children = children }
		end
	end
	return out
end

--- On the SMW backend, vocab columns read back as English machine tokens
--- (Entity/Store/Smw translates them for the machine consumers: cohort
--- filters, Navplates); a grid cell is a human surface, so each vocab
--- column's values map back to the German its writer stores before any cell
--- builds. Vocab's pass-through is the contract: a token with no German pair
--- stays verbatim, exactly what the datatable printed. Every downstream
--- surface keys on the translated text (cells, set filters, sort, quick
--- search, an editor's variants map), so the grid reads German throughout.
--- @param results table[]  rows, translated in place
--- @param columns DataGridColumn[]
--- @param kind string|nil
--- @return table[]  the same table
local function translateDisplay(results, columns, kind)
	local smwStore = require('Module:Entity/StructuredData/Smw')
	local Vocab = require('Module:Entity/Vocab')
	local resolveColumn = require('Module:DataGrid/Smw').resolveColumn
	for _, column in ipairs(columns) do
		local entry = resolveColumn(column.property, kind)
		local vocab = entry and smwStore.vocab(entry.field, entry.bucket)
		if vocab then
			local alias = p.columnAlias(column)
			for _, result in ipairs(results) do
				local value = result[alias]
				if type(value) == 'string' then
					result[alias] = Vocab.toGerman(vocab, value)
				elseif type(value) == 'table' then
					for i, v in ipairs(value) do
						if type(v) == 'string' then
							value[i] = Vocab.toGerman(vocab, v)
						end
					end
				end
			end
		end
	end
	return results
end

--- Runs the Store query: BucketQuery's on the Bucket backend, and
--- Entity/Store's SMW reader on SMW, with the spec's property names
--- canonicalized to manifest display names first (the one spelling the Store
--- reader resolves). Catches an infrastructure failure (a Bucket
--- QueryException, the per-query execution limit, the per-page budget, an
--- unregistered bucket during a staged deploy, or an SMW query-layer error)
--- instead of letting it script-error the page: every programming mistake
--- (an unknown property, a bad operator) is already caught by buildSpec
--- before this runs, so a failure here is infrastructure, not an editing
--- mistake. An Rdbms DBQueryError (the self-join class) is not catchable from
--- Lua and still propagates.
--- @param spec table
--- @return table[]|nil results
--- @return string|nil err
function p.runQuery(spec)
	local query = BucketQuery.query
	if require('Module:Entity/StructuredData').backend() == 'smw' then
		spec = require('Module:DataGrid/Smw').canonicalSpec(spec)
		query = require('Module:Entity/Store').query
	end
	local ok, results = pcall(query, spec)
	if not ok then
		return nil, results
	end
	return results, nil
end

--- Public for sibling grid renderers (PledgeVehicleGrid): the SMW rows'
--- English machine tokens Germanized for a human surface.
p.translateDisplay = translateDisplay

--- Sort query results by the `Name` alias (the `page_name` builtin), byte
--- comparison, so a table opens in page-title order (Bucket otherwise returns
--- store order). AG Grid's initial `sort=` sort overrides the visible order
--- regardless, so this is unconditional.
--- @param results table[]
--- @return table[] results  the same table, sorted in place
function p.sortRows(results)
	table.sort(results, function(a, b)
		return (a[NAME_ALIAS] or '') < (b[NAME_ALIAS] or '')
	end)
	return results
end

--- @class DataGridRequest
--- @field spec table  the Module:BucketQuery query spec
--- @field columns DataGridColumn[]  the editor's columns, in order
--- @field kind string|nil
--- @field sort DataGridSort[]|nil

--- Resolve a {{Data table}} argument table into the Store spec and the parsed
--- columns. Every contract violation comes back as a ready-to-display message,
--- in the order an editor meets them (unsupported argument, kind, category,
--- filter, columns, properties, sort). Shared with Module:DataGrid/Static so the
--- two templates accept one grammar and report one set of failures; `options`
--- is how that caller drops the Image lead column it renders itself.
--- @param args table
--- @param options DataGridOptions|nil  passed on to duplicateAlias and buildSpec
--- @return DataGridRequest|nil request
--- @return string|nil error
function p.resolveArgs(args, options)
	if args.conditions and mw.text.trim(args.conditions) ~= '' then
		return nil, '"conditions" is not supported; use "filter" (see Template:Data table)'
	end

	local kind = mw.text.trim(args.kind or '')
	if kind == '' then
		kind = nil
	elseif not KINDS[kind] then
		return nil, 'unknown kind "' .. kind .. '"'
	end

	local categoryFilter, badCategory = p.parseCategory(args.category)
	if badCategory then
		return nil, 'category "' .. badCategory .. '": use plain names separated by ";"; membership is direct only'
	end

	local filters, badLine = p.parseFilters(args.filter)
	if badLine then
		return nil,
			'filter line "'
				.. badLine
				.. '" is not Property = Value, Property = A; B, Property != Value, Property = + or Property <op> Number'
	end

	if not categoryFilter and #filters == 0 then
		return nil, 'provide "category" or "filter"'
	end

	local columns = p.parseColumns(args.columns)
	if #columns == 0 then
		return nil, 'no columns defined'
	end

	local duplicate = p.duplicateAlias(columns, options)
	if duplicate then
		return nil, 'duplicate column "' .. duplicate .. '"'
	end

	local spec, badSpec = p.buildSpec(kind, categoryFilter, filters, columns, options)
	if badSpec then
		return nil, badSpec
	end

	local sort, badSort = p.parseSort(args.sort, columns)
	if badSort then
		return nil, badSort
	end

	return { spec = spec, columns = columns, kind = kind, sort = sort }, nil
end

--- Entry point for {{Data table}}. Reads `category`, `filter`, `kind`, `columns`,
--- `pinlead` and `sort` from the parent frame, runs the Store query, builds the
--- grid, and returns it preceded by the styles load.
--- @param frame mw.frame
--- @param options DataGridOptions|nil  Caller-side options; {{Data table}} passes
--- none. A module wrapping this one uses it to set `primary` (Module:Maintenance).
--- @return string
function p.main(frame, options)
	local getArgs = require('Module:Arguments').getArgs
	local args = getArgs(frame)

	local request, badArgs = p.resolveArgs(args, options)
	if badArgs then
		return fail(badArgs)
	end
	local columns, kind, sort = request.columns, request.kind, request.sort
	local backend = require('Module:Entity/StructuredData').backend()
	if backend == 'smw' then
		-- Only kinds the crosswalk covers render; the gate stays ahead of any
		-- query, so a kind outside the set is an editor error rather than a
		-- Store failure. A missing kind is not an error: it renders in the
		-- entity-bucket-only mode ({{Manufacturer products}}: a manufacturer's
		-- products span kinds), whose resolution refusals reach the editor as
		-- the query error below.
		local smw = require('Module:DataGrid/Smw')
		if kind ~= nil and not smw.supportsKind(kind) then
			return fail(
				'kind "'
					.. kind
					.. '" has no SMW table; set kind to one of '
					.. table.concat(smw.supportedKinds(), ', ')
			)
		end
		-- Staged deploy: this wiki enables Extension:AGGrid in config, so the
		-- modules must be able to land before it and survive its removal. Without
		-- the extension (mw.ext.aggrid fails to require) the page keeps the SMW
		-- datatable {{Data table/static}} serves, not a script error; the grid
		-- takes over the moment the extension answers. Remove with the staging.
		if not pcall(require, 'mw.ext.aggrid') then
			local ok, result = pcall(smw.render, frame, request.spec, columns, sort)
			return ok and result or fail(tostring(result))
		end
	elseif backend ~= 'bucket' then
		return fail('unknown structured-data backend: ' .. tostring(backend))
	end
	local AGGridColumns = require('Module:AGGridColumns')

	-- Every `eyebrow` column composes the lead card's second line, in the order the
	-- editor wrote them.
	local eyebrowColumns = {}
	for _, column in ipairs(columns) do
		if column.eyebrow then
			eyebrowColumns[#eyebrowColumns + 1] = column
		end
	end
	local pinLead = yesno(args.pinlead, false)

	local results, queryErr = p.runQuery(request.spec)
	if queryErr then
		return fail('the query could not be run: ' .. tostring(queryErr))
	end
	p.sortRows(results)
	if backend == 'smw' then
		-- The Bucket wiki's rows already hold the editor-facing surface
		-- verbatim; the SMW reader's English tokens are a machine contract.
		translateDisplay(results, columns, kind)
	end

	local specs, groups = buildSpecs(results, columns, eyebrowColumns, pinLead, kind, sort)
	local gridOptions = {
		columnDefs = groupColumnDefs(AGGridColumns.buildColumnDefs(specs), groups),
		rowData = AGGridColumns.buildRowData(results, specs),
		quickSearch = true,
		expand = true,
		pagination = false,
		rowHeight = eyebrowColumns[1] and EYEBROW_ROW_HEIGHT or ROW_HEIGHT,
		autoSizeStrategy = { type = 'fitCellContents' },
		defaultColDef = { sortable = true, resizable = true },
	}

	local styles = frame:extensionTag({
		name = 'templatestyles',
		args = { src = 'Module:DataGrid/styles.css' },
	})

	return styles .. '<div class="t-datagrid">' .. aggrid.render(gridOptions) .. '</div>'
end

-- Test-only exports. Not part of the public API.
p._internal = {
	buildSpecs = buildSpecs,
	groupColumnDefs = groupColumnDefs,
	eyebrowResolver = eyebrowResolver,
	parseGermanNumber = parseGermanNumber,
	translateDisplay = translateDisplay,
}

return p
Cookies helfen uns bei der Bereitstellung dieses Wikis. Durch die Nutzung des Star Citizen Wiki erklärst du dich damit einverstanden, dass wir Cookies speichern.