Module:ItemsNav
Jump to navigation
Jump to search
This module is used to generate image maps such as Template:SS Items. The image maps are generated from the data at Module:ItemsNav/Data.
Though there is a learning curve to inputting the data, these image maps have the following advantages:
- ability to represent different upgrade states using arrows
- auto-selection of tab and upgrade state based on the current page
- Uses external links so as not to spam Special:WhatLinksHere
local p = {}
local h = {}
local File = require("Module:File")
local Franchise = require("Module:Franchise")
local Term = require("Module:Term")
local utilsCargo = require("Module:UtilsCargo")
local utilsError = require("Module:UtilsError")
local utilsLayout = require("Module:UtilsLayout")
local utilsMarkup = require("Module:UtilsMarkup")
local utilsPage = require("Module:UtilsPage")
local utilsString = require("Module:UtilsString")
local utilsTable = require("Module:UtilsTable")
local data = mw.loadData("Module:ItemsNav/Data")
local classes = {
stateContainer = "state-container",
states = "state-container__states",
state = "state-container__state",
defaultState = "state-container__state state-container__state--active",
controls = "state-container__controls state-container__controls--vertical",
stateControlForward = "state-control state-control-forward",
stateControlBack = "state-control state-control-back",
stateControlDisabled = "state-control--disabled",
}
local defaultSpacing = "8px"
local MAX_FRAME_WIDTH = 750
local currentPage = mw.title.getCurrentTitle().text
function p.Main(frame)
local isTemplatePage = frame:getParent():getTitle() == currentPage
return p.printNav(frame.args[1], frame:getParent().args[1])
end
function p.printNav(game, frameDisabled)
local gameData = data[game]
local nav = h.createNav(game, gameData)
if frameDisabled then
return nav
end
local header = "Items in " .. Franchise.link(game)
local footer = utilsMarkup.inline("Click on an item", {
caption = true,
italic = true,
})
local hasMap = #utilsTable.filter(gameData, "map") > 0
return utilsLayout.table({
styles = {
["margin"] = "1em auto",
["width"] = hasMap and "100%" or nil,
["max-width"] = (gameData.maxWidth or MAX_FRAME_WIDTH) .. "px"
},
rows = {
{
header = true,
cells = {header}
},
{
cells = {nav},
},
{
footer = true,
cells = {footer},
},
},
})
end
function h.createNav(game, data, isSubtabs)
local tabs = {}
local pages = {}
local defaultTab
for i, tabData in ipairs(data) do
local component, componentPages = h.createNavComponent(game, tabData)
tabs[i] = {
label = tabData.tab,
tooltip = tabData.tabCaption,
content = component,
}
pages = utilsTable.concat(pages, componentPages)
defaultTab = defaultTab or utilsTable.keyOf(pages, currentPage) and i
end
return utilsLayout.tabs(tabs, {
default = defaultTab or 1,
align = "center",
tabOptions = {
collapse = true,
columns = data.tabColumns or (not isSubtabs and #tabs) or nil,
},
labelOptions = {
alignVertical = "bottom",
},
contentOptions = {
contentWidth = true,
}
}), pages
end
function h.createNavComponent(game, data)
if data.subtabs then
return h.createNav(game, data.subtabs, true)
end
if data.map then
return h.createMapNav(game, data.map)
end
if data.rows then
return h.createRowsNav(game, data.rows)
end
end
function h.createRowsNav(game, data)
local html = mw.html.create("div")
:css({
["display"] = "flex"
})
local rowSpacing = data.rowSpacing or defaultSpacing
html:css({
["margin-top"] = "-" .. rowSpacing,
["flex-direction"] = "column",
["align-items"] = "stretch",
["justify-content"] = "center",
["max-width"] = data.maxWidth and data.maxWidth .. "px",
["margin-left"] = "auto",
["margin-right"] = "auto",
})
local pages = {}
local items = data.items
if type(items[1]) == "string" or type(items[1]) == "table" and items[1].page then
items = { items }
end
for _, rowItems in ipairs(items) do
local rowData = {
fileType = data.fileType,
scale = data.scale,
fileSize = data.fileSize,
spacing = data.spacing,
items = rowItems,
}
local row, rowPages = h.printRow(game, rowData)
pages = utilsTable.concat(pages, rowPages)
html:tag("div")
:wikitext(row)
:css({
["margin-top"] = rowSpacing,
})
:done()
end
return tostring(html), pages
end
function h.printRow(game, data, options)
local vertical = options and options.vertical
local styles = options and options.styles
local pages = {}
local row = mw.html.create("div")
:css({
["display"] = "flex",
["flex-wrap"] = "wrap",
["flex-direction"] = (vertical and "column") or "row",
["justify-content"] = "center",
["align-items"] = "flex-end",
["margin-top"] = "-" .. defaultSpacing,
["margin-left"] = "-" .. (data.spacing or defaultSpacing),
})
:css(styles or {})
for _, item in ipairs(data.items) do
local img = h.rowItem(game, data, item)
table.insert(pages, item)
row
:tag("div")
:wikitext(img)
:css({
["margin-top"] = defaultSpacing,
["margin-left"] = (data.spacing or defaultSpacing),
})
:done()
end
return tostring(row), pages
end
function h.rowItem(game, rowData, item)
local page, file
if type(item) == "table" and item.page then
page = item.page
file = item.image
else
page = item
end
local file = file or table.concat({game, page, rowData.fileType}, " ") .. ".png"
local img = File.image(file, {
link = page,
noBacklink = true,
caption = page,
scale = rowData.scale,
scaleUsingCargo = true,
size = rowData.fileSize,
checkExists = false, -- existence checks are too expensive at this scale
isPixelArt = true,
})
return img
end
function h.createMapNav(game, mapData)
local states, pages, defaultState = h.printMapStates(mapData)
local leftColumn
if mapData.leftColumn then
local column, columnPages = h.printRow(game, mapData.leftColumn, {
vertical = true,
styles = {
["margin-right"] = defaultSpacing,
},
})
defaultState = utilsTable.keyOf(columnPages, currentPage) or defaultState
pages = utilsTable.concat(pages, columnPages)
leftColumn = column
end
return h.printStatefulMap(states, defaultState, mapData.maxWidth, leftColumn), pages
end
function h.printMapStates(mapData)
local states = {}
local baseMapData = mapData
local baseMap, pages = h.printImageMap(mapData)
local defaultState = utilsTable.keyOf(pages, currentPage) and 1 or nil
table.insert(states, baseMap)
for i, upgradeData in ipairs(mapData.upgrades or {}) do
local upgradeMapData = h.resolveUpgradeMap(baseMapData, upgradeData)
local upgradeMap, upgradePages = h.printImageMap(upgradeMapData)
defaultState = defaultState or utilsTable.keyOf(upgradePages, currentPage) and i + 1
pages = utilsTable.concat(pages, upgradePages)
table.insert(states, upgradeMap)
baseMapData = upgradeMapData
end
return states, pages, defaultState
end
function h.resolveUpgradeMap(mapData, upgradeData)
local areas = {}
for i, area in ipairs(mapData.areas) do
local before = mapData.areas[i]
local change = upgradeData.changes[before.page]
if not change then
table.insert(areas, before)
elseif change == "" then
-- no-op
elseif type(change) == "string" then
table.insert(areas, {
area = before.area,
page = change,
display = before.display
})
else
table.insert(areas, {
area = change.area or before.area,
page = change.page or before.page,
display = change.display
})
end
end
areas = utilsTable.concat(upgradeData.areas, areas)
local upgradeMapData = {
image = upgradeData.image,
maxWidth = mapData.maxWidth,
areas = areas,
}
return upgradeMapData
end
function h.printStatefulMap(states, defaultState, maxWidth, leftColumn)
defaultState = defaultState or 1
local statesNode = mw.html.create("div")
:addClass(classes.states)
:css({
["display"] = "flex",
["align-items"] = "center",
["justify-content"] = "center",
["max-width"] = maxWidth and maxWidth .. "px",
["flex-basis"] = "80%"
})
for i, state in ipairs(states) do
local default = i == defaultState
statesNode
:tag("div")
:addClass(default and classes.defaultState or classes.state)
:css("flex", "1")
:wikitext(state)
:done()
end
local controlCss = {
["height"] = "12%",
["min-height"] = "32px",
["margin-left"] = "15%",
}
local controlsNode = mw.html.create("div")
:addClass(classes.controls)
:tag("div")
:addClass(classes.stateControlForward)
:addClass(defaultState == #states and classes.stateControlDisabled or nil)
:css(controlCss)
:wikitext("[[File:Up Arrow.png|link=]]")
:done()
:tag("div")
:addClass(classes.stateControlBack)
:addClass(defaultState == 1 and classes.stateControlDisabled or nil)
:css(controlCss)
:wikitext("[[File:Down Arrow.png|link=]]")
:done()
local stateContainer = mw.html.create("div")
:addClass(classes.stateContainer)
-- TODO: :node(mw.clone(controlsNode):css("visibility", "hidden")) --Hack to "balance" the left side and keep the content centered
:node(leftColumn)
:node(statesNode)
:node(controlsNode)
:node(leftColumn and mw.html.create("div"):css("visibility", "hidden"):node(leftColumn))
:css({
["display"] = "flex",
["justify-content"] = "center",
["margin-bottom"] = defaultSpacing,
})
return tostring(stateContainer)
end
function h.printImageMap(data)
local lines = { data.image }
local pages = {}
for _, area in ipairs(data.areas) do
local page = area.page
local href = utilsPage.fullUrl(page)
local link = ("[%s %s]"):format(href, area.display or page)
table.insert(pages, page)
table.insert(lines, area.area .. link)
end
table.insert(lines, " desc none")
lines = table.concat(lines, "\n")
local imagemap = mw.getCurrentFrame():extensionTag("imagemap", lines)
local responsiveImageMap = mw.html.create("div")
:addClass("responsive-imagemap")
:wikitext(imagemap)
return tostring(responsiveImageMap), pages
end
function p.Data(frame)
local games = {}
for _, game in ipairs(Franchise.enumGames()) do
if Franchise.canonicity(game) == "canon" and not Franchise.isRemake(game) then
table.insert(games, p.printTemplateLink(game))
local remakes = {}
for _, remake in ipairs(Franchise.remakes(game)) do
table.insert(remakes, p.printTemplateLink(remake))
end
table.insert(games, remakes)
end
end
local message = "The data on this page is used to generate the [[:Category:Item navigation templates|item nav templates]] listed below. While editing the data, use the '''Preview page with this''' form to view the navs individually.\n\n To view all item navs at once, see [[Module:ItemsNav/All]]. Note that loading this many navs will take several seconds. (This is why a global nav with all the games no longer exists — it adds too much loading time.)"
return message .. utilsMarkup.bulletList(games)
end
function p.printTemplateLink(game)
local indicator = ""
-- if not data[game] then
-- indicator = "*"
-- elseif pcall(function() p.printNav(game) end) then
-- indicator = ""
-- else
-- indicator = "[[File:TFH Red Link desperate.png|48px]]"
-- end
return "[[Template:" .. game .. " Items]]" .. indicator
end
function p.TemplateDocumentation(frame)
local game = frame.args[1]
local usageFrame = utilsMarkup.inline(string.format("{{%s Items}}", game), { nowiki = true, code = true })
local usageFrameless = utilsMarkup.inline(string.format("{{%s Items|-}}", game), { nowiki = true, code = true })
local doc = frame:expandTemplate({
title = "Module:ItemsNav/Template/Documentation",
args = {Franchise.link(game), usageFrame, usageFrameless, Franchise.shortName(game), p.printLinksTable(game)}
})
doc = doc .. "[[Category:Item navigation templates]]"
return doc
end
function p.printLinksTable(game)
local linkList, pages = h.getLinkList(game, data[game])
local invalidTermsList = h.getInvalidTermsList(game, pages)
local categoryItems = utilsPage.dpl({
category = "Items in " .. Franchise.shortName(game),
namespace = "", -- main
ordermethod = "title",
redirects = "include",
})
local itemGroups = utilsPage.dpl({
category = {"Item Groups", "Items in " .. Franchise.shortName(game)},
namespace = "", -- main
ordermethod = "title",
redirects = "include",
})
local songs = utilsPage.dpl({
category = "Songs",
namespace = "", -- main
ordermethod = "title",
redirects = "include",
})
itemGroups = utilsTable.difference(itemGroups, pages)
local omittedItems = utilsTable.difference(categoryItems, pages)
omittedItems = utilsTable.difference(omittedItems, itemGroups)
local extraItems = utilsTable.difference(pages, categoryItems)
songs = utilsTable.intersection(extraItems, songs)
extraItems = utilsTable.difference(extraItems, songs)
local omittedItemsList = h.toList(omittedItems)
local extraItemsList = h.toList(extraItems)
local itemGroupsList = h.toList(itemGroups)
local songsList = h.toList(songs)
local omittedItemsHeader = utilsMarkup.tooltip("Omitted Items", "These items are missing from the nav.")
local itemGroupsHeader = utilsMarkup.tooltip("Item Groups", "Item groups are OK to omit as long as the individual items are included.")
local definitionList = {}
if #itemGroups > 0 then
table.insert(definitionList, {itemGroupsHeader, itemGroupsList })
end
if #definitionList > 0 then
omittedItemsList = omittedItemsList .. "\n\n\n----\n" .. utilsMarkup.definitionList(definitionList)
end
if #songs > 0 then
extraItemsList = extraItemsList .. "\n\n\n----\n" .. utilsMarkup.definitionList({
{"Songs", songsList}
})
end
return utilsLayout.table({
headers = {"Links", "Invalid Terms", omittedItemsHeader, "Extra Items"},
rows = {
{
styles = {
["vertical-align"] = "top"
},
cells = {linkList, invalidTermsList, omittedItemsList, extraItemsList}
}
}
})
end
function h.getLinkList(game, tabs)
local definitionList = {}
local pages = {}
for _, tab in ipairs(tabs) do
local definition = {}
definition[1] = utilsTable.size(tabs) > 1 and tab.tab or "" -- #tabs doesn't work because of how mw.loadData works
if tab.subtabs then
local subtabList, subtabPages = h.getLinkList(game, tab.subtabs)
definition[2] = subtabList
pages = utilsTable.concat(pages, subtabPages)
elseif tab.map then
local mapItems = utilsTable.map(tab.map.areas, "page")
for _, upgrade in ipairs(tab.map.upgrades or {}) do
mapItems = utilsTable.concat(mapItems, upgrade.areas or {})
for _, v in pairs(upgrade.changes) do
if type(v) == "string" and v ~= "" or type(v) == "table" and v.page then
table.insert(mapItems, v)
end
end
end
mapItems = utilsTable.concat(mapItems, tab.map.leftColumn and tab.map.leftColumn.items)
local links = utilsTable.map(mapItems, function(item)
local itemPage = type(item) == "table" and item.page or item
return utilsMarkup.link(itemPage)
end)
local subtabPages = utilsTable.map(mapItems, function(item)
return type(item) == "table" and item.page or item
end)
table.sort(links)
definition[2] = utilsMarkup.bulletList(links)
pages = utilsTable.concat(pages, subtabPages)
elseif tab.rows then
local items = utilsTable.flatten(tab.rows.items)
items = utilsTable.map(items, function(item)
if type(item) == "table" and item.page then
return item.page
elseif type(item) == "string" then
return item
end
end)
table.sort(items)
local links = utilsTable.map(items, utilsMarkup.link)
definition[2] = utilsMarkup.bulletList(links)
pages = utilsTable.concat(pages, items)
end
table.insert(definitionList, definition)
end
return utilsMarkup.definitionList(definitionList), pages
end
function h.getInvalidTermsList(game, pages)
local invalidTermsList = {}
for _, page in ipairs(pages) do
local term = Term.fetchTerm(page, game)
term = term and string.gsub(term, "''", "") -- workaround needed as long as markup is stored in terms
if not term then
table.insert(invalidTermsList, utilsMarkup.link(page))
elseif term ~= page then
table.insert(invalidTermsList, utilsMarkup.link(page) .. "\n\n should be " .. utilsMarkup.link(term))
end
end
return utilsMarkup.bulletList(invalidTermsList)
end
function h.toList(pages)
pages = utilsTable.map(pages, utilsMarkup.link)
return utilsMarkup.bulletList(pages)
end
function p.Schemas()
return {
Data = {
type = "map",
keys = {
type = "string",
enum = Franchise.enum()
},
values = {
allOf = {
{
type = "array",
items = { _ref = "#/definitions/tab" }
},
{
type = "record",
properties = {
{
name = "maxFrameWidth",
type = "number",
default = MAX_FRAME_WIDTH,
desc = "If the nav is 'framed' in a wikitable, this determines the max width of the wikitable."
},
{
name = "tabColumns",
type = "number",
desc = "Corresponds to the paramter on [[Module:UtilsLayout#tabs]]. Determines the number of tabs per row."
},
},
},
},
},
desc = "A map of [[Data:Franchise|game codes]] to one or more image-based navs for that game. If there is more than one nav in a game, these are displayed as [[Module:UtilsLayout#tabs|tabs]]. An additional <code>colums</code> key can be used to indicate how many tabs to render per row.",
definitions = {
area = {
type = "record",
required = true,
properties = {
{
name = "area",
type = "string", -- TODO: regex
required = true,
desc = "The shape and coordinates of the area. For example: <code>rect 314 84 372 123</code>",
},
{
name = "page",
type = "string",
required = true,
desc = "The name of the page to link to."
},
{
name = "display",
default = "page",
type = "string",
desc = "The alt text for the link.",
},
},
},
upgrade = {
type = "record",
properties = {
{
name = "image",
type = "string",
required = true,
desc = "File name for the upgrade state image map.",
},
{
name = "changes",
type = "map",
keys = { type = "string" },
values = {
oneOf = {
{
type = "string",
desc = 'The new page that an area must link to. If set to empty string (<code>""</code>), the area will be unset.',
},
{
type = "record",
desc = "Override other properties of an area, namely its coordinates.",
properties = {
{ name = "area", type = "string" }, -- TODO: regex
{ name = "page", type = "string" },
{ name = "display", type = "string" },
},
},
}
},
desc = [[
Used to model state transitions for items that occupy the same inventory slot.
By default, the "upgrade state" image map has all the same areas as the previous state.
Use this property to modify which page an area links to, without having to repeat coordinates for it.
This property can also be used to 'unset' areas which are no longer applicable.
]]
},
{
name = "areas",
type = "array",
items = { _ref = "#/definitions/area", _hideSubkeys = true },
desc = "A list of new areas that are applicable to the upgrade state and its successors.",
},
},
},
imagemap = {
type = "record",
properties = {
{
name = "image",
type = "string",
required = true,
desc = "Base file name for the image map."
},
{
name = "maxWidth",
type = "number",
desc = "Maximum width in pixels for the [[Template:Responsive Imagemap|responsive image]].",
},
{
name = "areas",
type = "array",
required = true,
items = {
_ref = "#/definitions/area",
},
desc = "The clickable areas of the image map.",
},
{
name = "upgrades",
type = "array",
items = { _ref = "#/definitions/upgrade" },
desc = [[
Represents upgraded inventory states, where each state is rendered as its own imagemap that is clicked to with "upgrade" and "downgrade" arrows.
This is used in cases such as ]] .. "[[Template:OoA Items]]" .. [[, when different inventory items occupy the same inventory slot at different points in the game.
In these cases, the goal should be to represent all the items in as few "upgrade" states as possible, even if this means some items appearing together that never would in-game.
It's not feasible to represent every possible inventory state as this A) detracts from the actual purpose of navigation, and B) generates too many image maps affecting page size and loading time.
]]
},
{
name = "leftColumn",
_ref = "#/definitions/rows",
_hideSubkeys = true,
desc = "Designed specifically for [[Template:LADX Items]].",
},
},
},
rows = {
type = "record",
properties = {
{
name = "fileType",
type = "string",
required = true,
},
{
name = "scale", -- TODO: remove?
type = "number",
default = 1,
},
{
name = "fileSize", -- TODO: remove?
type = "string",
},
{
name = "spacing",
type = "string",
default = defaultSpacing,
desc = "Horizontal space between each image in the row.",
},
{
name = "rowSpacing",
type = "string",
default = defaultSpacing,
desc = "Space between rows, if there are more than one."
},
{
name = "maxWidth",
type = "number",
desc = "Maximum width in pixels for the rows. If unset, the rows will use up all available page width.",
},
{
name = "items",
required = true,
desc = [[
An array of strings representing an image row. Or, an array of rows if there are multiple rows.
The thumbnail for each file in the row is generated as follows (not taking into account the size, which is computed automatically):]]
.. "\n" .. utilsMarkup.code("[[File:<game> <item> <fileType>.png|link=<item>]]") .. [[
]],
oneOf = {
{
type = "array",
items = {
oneOf = {
{
type = "string",
},
{
type = "record",
properties = {
{
name = "image",
required = true,
type = "string",
desc = "Custom filename",
},
{
name = "page",
required = true,
type = "string",
desc = "Wiki article to link to.",
},
},
},
},
},
},
{
type = "array",
items = {
type = "array",
items = {
oneOf = {
{
type = "string"
},
{
type = "record",
properties = {
{
name = "image",
required = true,
type = "string",
desc = "Custom filename",
},
{
name = "page",
required = true,
type = "string",
desc = "Wiki article to link to.",
},
},
},
},
},
},
},
},
},
}
},
tab = {
allOf = {
{
type = "record",
properties = {
{
name = "tab",
type = "string",
required = true,
desc = "Tab label. Displayed only when game has more than one tab.",
},
{
name = "tabCaption",
type = "string",
desc = "Tooltip to be displayed for the tab.",
},
},
},
{
oneOf = {
["Image Maps"] = {
type = "record",
desc = "Generates image maps of items that mimic in-game inventory.",
properties = {
{
name = "map",
required = true,
_ref = "#/definitions/imagemap",
}
},
},
["Subtabs"] = {
type = "record",
desc = 'A nav can have one or more "subnavs". These usually map to in-game submenus. For example, see [[Template:TWW Items]], "Bag Items" tab.',
properties = {
{
name = "subtabs",
required = true,
type = "array",
items = { _ref = "#/definitions/tab" },
}
},
},
["Rows"] = {
type = "record",
desc = "Icons or sprites of items displayed in one or more [[Module:UtilsLayout#flex|rows]]. Used for items that do not appear in inventory screens.",
properties = {
{
name = "rows",
required = true,
_ref = "#/definitions/rows",
}
},
},
},
},
},
}
}
}
}
end
return p