Module:Definitions

Module:Definitions

This module implements the Definitions v1 system used by Template:Def. It resolves a (Domain, Key) pair against a JSON database and outputs a small inline term with optional tooltip text.

Purpose

• Provide consistent, reusable definitions across the wiki.
• Keep usage explicit to avoid collisions (no guessing).
• Allow pages to show definitions without requiring navigation.

Usage

The public interface is the template Template:Def:

{{def|Domain|Key}}

Examples:

{{def|Stat|Vit}}
{{def|Element|Fire}}
{{def|Cast|Ground}}
{{def|Target|Summon}}

System components

1) Template:def

Page: Template:def

This template calls Module:Definitions and passes the provided parameters.

2) Module:Definitions

Page: Module:Definitions

Responsibilities:

• Load the JSON database.
• Resolve Domain and Key.
• Output HTML with sv-def classes and data-sv-def-* attributes.

Tooltip rule:

• If Definition is empty, no tooltip is shown.

Link rule:

• If Link is non-empty, the term text is rendered as a real <a> (clickable).
• If Link is empty, the term text is rendered as plain text (tooltip-only).

3) Definitions database (JSON)

Page: Module:Definitions/Definitions.json

This page is the Definitions v1 database.

Schema:

{
  "Schema": 1,
  "UpdatedAt": "YYYY-MM-DD",
  "Stat": {
    "Vit": { "Name": "Vitality", "Definition": "...", "Icon": "", "Link": "" }
  },
  "Element": {
    "Fire": { "Name": "Fire", "Definition": "", "Icon": "", "Link": "" }
  }
}

Rules:

• Top-level keys are Domains (example: Stat, Element).
• Each Domain contains Keys (example: Vit, Fire).
• Keys are CamelCase and should match the intended enum key names.
• Name and Definition are user-facing fields.
• Icon and Link may be blank.

Supported v1 domains:

• Cast
• Damage
• Element
• Aura
• Event
• Stance
• Stat
• Target

Styling

CSS is provided by TemplateStyles:

• Page: Template:def/styles.css
• Namespace: sv-def only

JavaScript

Tooltip behavior is implemented in site JavaScript:

• Page: MediaWiki:Common.js

The script reads:

• data-sv-def-tip (tooltip text)
• data-sv-def-link (reserved / optional)

Fallback behavior

• Invalid arguments render an error placeholder.
• Missing records render a missing placeholder.
• If Name is empty, the module displays a humanized version of the Key.
• If Definition is empty, tooltip behavior is disabled.
• If an icon file is missing, the module displays ? instead of a redlink image.

---

-- Module:Definitions
-- Core resolver + renderer for {{def|Domain|Key}} (Definitions v1).
--
-- Data source (static):
--   Module:Definitions/Definitions.json
--
-- JSON shape:
-- {
--   "Schema": 1,
--   "UpdatedAt": "YYYY-MM-DD",
--   "Stat":   { "Vit": { "Name":"...", "Definition":"...", "Icon":"", "Link":"" }, ... },
--   "Target": { ... },
--   ...
-- }
--
-- Notes:
-- - Domains + keys are discovered from JSON (no hardcoded domain lists).
-- - CSS namespace: ONLY "sv-def" (plus sv-def--* modifiers).
-- - Output classes: sv-def, sv-def-icon, sv-def-icon-img, sv-def-text.

local p = {}

local DATA_TITLE = "Module:Definitions/Definitions.json"

-- =============================================================================
-- Helpers
-- =============================================================================

local function trim(s)
	if type(s) ~= "string" then return "" end
	return mw.text.trim(s)
end

local function lc(s)
	return string.lower(tostring(s or ""))
end

local function enc_attr(s)
	return mw.text.encode(tostring(s or ""), '"<>&')
end

local function humanize(key)
	key = tostring(key or "")
	key = key:gsub("([a-z0-9])([A-Z])", "%1 %2")
	key = key:gsub("([A-Z]+)([A-Z][a-z])", "%1 %2")
	key = key:gsub("%s+", " ")
	return mw.text.trim(key)
end

local function find_ci(t, key)
	if type(t) ~= "table" then return nil end
	if t[key] ~= nil then return t[key] end
	local want = lc(key)
	for k, v in pairs(t) do
		if lc(k) == want then return v end
	end
	return nil
end

-- =============================================================================
-- DB load (cached)
-- =============================================================================

local DB = nil

local function load_db()
	if DB ~= nil then return DB end

	-- Preferred: Scribunto JSON loader (reliable for Module:*.json pages)
	local ok, obj = pcall(mw.loadJsonData, DATA_TITLE)
	if ok and type(obj) == "table" then
		DB = obj
		return DB
	end

	-- Fallback: raw content + jsonDecode (kept for safety)
	local title = mw.title.new(DATA_TITLE)
	if not title then
		DB = {}
		return DB
	end

	local raw = title:getContent()
	if type(raw) ~= "string" or raw == "" then
		DB = {}
		return DB
	end

	local ok2, obj2 = pcall(mw.text.jsonDecode, raw)
	if not ok2 or type(obj2) ~= "table" then
		DB = {}
		return DB
	end

	DB = obj2
	return DB
end

-- =============================================================================
-- Domain + record resolution (dynamic)
-- =============================================================================

local function norm_domain(db, domain)
	domain = trim(domain)
	if domain == "" then return nil end

	-- Exact match first
	if type(db[domain]) == "table" then
		return domain
	end

	-- Case-insensitive match across top-level keys that are tables
	local want = lc(domain)
	for k, v in pairs(db) do
		if type(v) == "table" and lc(k) == want then
			return k
		end
	end

	return nil
end

local function get_record(db, domain, key)
	local dom = db[domain]
	if type(dom) ~= "table" then return nil end
	return find_ci(dom, key)
end

-- =============================================================================
-- Icon rendering
-- - Blank icon: render nothing (no generic dot/circle)
-- - Missing file: render "?" badge (no redlink image)
-- =============================================================================

local function icon_html(icon)
	icon = trim(icon)

	if icon == "" then
		return ""
	end

	local fileTitle = icon
	if not fileTitle:match("^[Ff]ile:") then
		fileTitle = "File:" .. fileTitle
	end

	local t = mw.title.new(fileTitle)
	if not t or not t.exists then
		return '<span class="sv-def-icon sv-def-icon--missing" aria-hidden="true">?</span>'
	end

	return '<span class="sv-def-icon-img">[[' .. fileTitle .. '|15px|link=]]</span>'
end

-- =============================================================================
-- Link rendering
-- - If Link is present, render a real <a href="...">
-- - If Link is blank, render plain text
-- =============================================================================

local function link_to_href(link)
	link = trim(link)
	if link == "" then return nil end

	-- External
	if link:match("^https?://") or link:match("^//") then
		return link
	end

	-- Internal: allow "Page#Fragment"
	local page, frag = link:match("^(.-)#(.*)$")
	if not page then
		page = link
		frag = nil
	end

	local t = mw.title.new(page)
	if not t then
		return nil
	end

	local url = t:localUrl()
	if frag and frag ~= "" then
		url = url .. "#" .. mw.uri.anchorEncode(frag)
	end

	return url
end

local function text_html(name, link)
	name = tostring(name or "")
	local href = link_to_href(link)
	if href then
		return '<a class="sv-def-text" href="' .. enc_attr(href) .. '">' .. mw.text.nowiki(name) .. '</a>'
	end
	return '<span class="sv-def-text">' .. mw.text.nowiki(name) .. '</span>'
end

-- =============================================================================
-- Render
-- =============================================================================

local function _render(domain, key)
	local db = load_db()
	domain = norm_domain(db, domain)
	key = trim(key)

	if not domain or key == "" then
		return '<span class="sv-def sv-def--error">?</span>'
	end

	local rec = get_record(db, domain, key)

	local name, defn, icon, link = "", "", "", ""
	if type(rec) == "table" then
		name = trim(rec.Name)
		defn = trim(rec.Definition)
		icon = trim(rec.Icon)
		link = trim(rec.Link)
	end

	if name == "" then
		name = humanize(key)
	end

	local d_lc = lc(domain)

	-- Missing record: show a visible hint but NO tooltip/link data.
	if rec == nil then
		return
			'<span class="sv-def sv-def--missing sv-def--' .. enc_attr(d_lc) .. '"' ..
				' data-sv-def-domain="' .. enc_attr(domain) .. '"' ..
				' data-sv-def-key="' .. enc_attr(key) .. '"' ..
			'>' ..
				'<span class="sv-def-icon sv-def-icon--missing" aria-hidden="true">?</span>' ..
				'<span class="sv-def-text">' .. mw.text.nowiki(name) .. '</span>' ..
			'</span>'
	end

	local attrs = {
		'class="sv-def sv-def--' .. enc_attr(d_lc) .. '"',
		'data-sv-def-domain="' .. enc_attr(domain) .. '"',
		'data-sv-def-key="' .. enc_attr(key) .. '"',
	}

	-- Only include tooltip/link attributes when populated.
	if defn ~= "" then
		attrs[#attrs + 1] = 'data-sv-def-tip="' .. enc_attr(defn) .. '"'
	end
	if link ~= "" then
		attrs[#attrs + 1] = 'data-sv-def-link="' .. enc_attr(link) .. '"'
	end

	local title_attr = (defn ~= "") and (' title="' .. enc_attr(defn) .. '"') or ""

	return
		'<span ' .. table.concat(attrs, " ") .. title_attr .. '>' ..
			icon_html(icon) ..
			text_html(name, link) ..
		'</span>'
end

-- =============================================================================
-- Public API
-- =============================================================================

function p.def(frame)
	local a = frame.args or {}
	return _render(a[1] or a.Domain or a.domain, a[2] or a.Key or a.key)
end

-- Supports BOTH:
-- 1) Wikitext: {{#invoke:Definitions|render|Stat|Vit}}
-- 2) Lua: p.render("Stat","Vit")
function p.render(a, b)
	if type(a) == "table" then
		local args = a.args or {}
		return _render(args[1], args[2])
	end
	return _render(a, b)
end

return p