Module:SMWTable/doc

This is the documentation subpage of Module:SMWTable. It contains usage information that is not part of the underlying module.

This helper module is used when authoring other modules that render tables from SMW queries.

local SMWTable = require("Module:SMWTable")

Usage

To create a table, first create a new SMWTable instance:

local myTable = return SMWTable.new({
  selection = "Gunbreaker's Arm",
  queryOptions = {
    sort = "Has level requirement,Has item level,Has canonical name",
    limit = 999,
  },
  attributes = {
    class = "table sortable",
  },
})

Next, call the column method to add columns to the table, providing a definition for each column via helper functions:

myTable
  :column(SMWTable.nameAndIconColumn({label = "Item"}))
  :column(SMWTable.textColumn({property = "Has level requirement", label = "Level"}))
  :column(SMWTable.textColumn({property = "Has item level", label = "Item level"}))
  :column(SMWTable.classJobRequirementColumn())
  :column(SMWTable.weaponDamageColumn())
  :column(SMWTable.materiaSlotsColumn())
  :column(SMWTable.attributeBonusesColumn())

Or by providing a column definition directly:

myTable:column({
  label = "My column",
  printouts = {
    ["Has some property"] = "",
  },
  render = function(row)
    return "Value is " .. row["Has some property"]
  end
})

Finally, render the table by returning it from your module's entrypoint function:

local p = {}
function p.main()
  return myTable
end
return p

Class: SMWTable

Constructor

local mySMWTable = SMWTable.new({
  selection: string,
  queryOptions?: table,
  attributes?: table,
  caption?: string,
})

Creates a new table builder instance. Takes a single argument with named options. Returns a single value, the new SMWTable instance.

selection

The query selection string, passed through directly to {{#ask:}}.

queryOptions

Optional. Additional named parameters to be passed through to {{#ask:}}, particularly useful for setting sort/order.

attributes

Optional. Attributes attached to the table when it is rendered. Most commonly used to set class and/or style to customize the table's appearance, make it sortable, etc.

Default: { class = "table" }

caption

Optional. Wikitext for the table caption, if provided.

Method: column

mySMWTable:column({
  label: string,
  printouts: table,
  render: function,
})

Adds a column to the table. Columns are rendered in the order they are added to the builder, from left to right. Takes a single column definition table which defines what data the column will display and how it will be displayed. Column definitions must have all of the following keys:

label

The header text displayed for this column.

printouts

A table describing the SMW properties that this column will display. Keys of this table are SMW property names, and the value for each key is SMW printout customization data for that property, or otherwise an empty string.

render

A function which takes a single argument, a single row of SMW data as a table, and renders the value of this column for the given row.

The printouts and render keys work together to define the properties necessary to render the column, and then render each row individually based on the requested data. For example, a simple column definition which displays an item's canonical name wrapped in quotation marks might look like:

mySMWTable:column({
  label = "Canonical name",
  printouts = {
    ["Has canonical name"] = "",
  },
  render = function(row)
    return '"' .. row["Has canonical name"] .. '"'
  end
})

This column definition requests one property as part of the query: Has canonical name. No special formatting is required, so the corresponding value in the printouts table is simply the empty string. Then, to render the value for each row, the render function concatenates quotation marks around the current row's property value.

More complicated columns may require multiple properties, chained properties, and/or printout formatting directives in order to achieve their function. For example, consider a table of crafting recipes with a column that displays the recipe's ingredients:

local myTable = SMWTable.new({
  selection = "[[Has context::Recipe]]",
  queryOptions = {limit = 1},
})
myTable:column({
  label = "Ingredients",

  printouts = {
    -- "Has ingredient" is a Record property, so we can query its subproperties
    -- "Has ingredient name" uses # to prevent automatic linking of the item
    ["Has ingredient.Has ingredient name"] = "#",
    ["Has ingredient.Has ingredient quantity"] = "",
  },

  render = function(row)
    -- "Has ingredient" can also have more than one value, for recipes with more than one ingredient
    -- Ensure the values we're working with are arrays so we can handle multiple ingredients
    local names = row["Has ingredient name"]
    local quantities = row["Has ingredient quantity"]
    if type(names) == "string" then
      names = {names}
      quantities = {quantities}
    end

    -- Assemble the column value
    local out = ""
    for i, name in ipairs(names) do  -- Loop over all ingredient names
      if out ~= "" then
        
        out = out .. "<br>"  -- Separate ingredients with a line break
      end
      -- Display the ingredient name and the corresponding quantity
      out = out .. name .. " x" .. quantities[i]
    end
  end
})

This table would render the crafting recipe for Raisins like so:

Ingredients
Lowland Grapes x1 Fire Shard x1

Method: __tostring

tostring(mySMWTable)

Renders the table to wikitext. This is a metamethod that is invoked when the SMWTable instance is cast to a string (via tostring(), the .. operator, ...)

Static method: textColumn

mySMWTable:column(SMWTable.textColumn({
  property: string,
  label?: string,
  default?: string,
  valuesep?: string,
}))

Returns a column definition that displays the value of a string property.

property

Property name, e.g. "Has canonical name".

label

Optional. Heading text for the column.

Default: Property name.

default

Optional. Default value to render when a row does not have a value for the property.

valuesep

Optional. Separator used when a row has multiple values for the property.

Default: ", "

Static method: materiaSlotsColumn

TODO