Modul:DataGrid
Aus Star Citizen Wiki
Weitere Optionen
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 mehrzeiligecolumns-Argument inDataGridColumn[].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): dasfilter-Argument in Store-Filter;Eigenschaft = A; Bist die ODER-Form (||wird auch akzeptiert).p.parseCategory(raw): dascategory-Argument in einen Kategorie-Filter.p.parseSort(raw, columns): dassort-Argument (kommagetrennte Schlüssel, je<Label oder Eigenschaft> [asc|desc]) in eine Präzedenzliste.p.buildSpec(kind, categoryFilter, filters, columns, options): dieStore.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 demName-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=Locationundkind=Commodityeine SMW-Abfrage statt AG Grid (Modul:DataGrid/Smw); ein fehlendeskindist 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 = falsegibt denImage-Alias frei. mainruftsortRowsdirekt nachrunQuery; ohnesortlisten Zeilen nach Seitentitel.kind=barskaliert 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 & 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. "&"), 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. "&"), 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


