Module:HoverTooltip

Documentation for this module may be created at Module:HoverTooltip/doc

-- <pre> -- Module - HoverTooltip
--[==============================================================================[  
This module contains functions to format and return content for with this wiki's
  'hover' toolip templates. Descriptions for keywords and glossary terms are
  stored in the sub-module HoverTooltip/Keywords.
]==============================================================================]

-- load Dev wiki utility modules
local getArgs = require('Dev:Arguments').getArgs

--=======================================
--[==[Load Data Tables]==]

local data = mw.loadData("Module:HoverTooltip/Keywords")

local keywords = data.keywords
local glossary = data.glossary

-- -----------------------------------------------------
--[======[Non-Invokable Functions ]======]
-- These functions cannot be accessed from wiki articles or templates. They are
--   used by other parts of this module.
-- See 'Invokable Functions' section below for accessable functions.

-- Lookup and return keyword description
function getDescription(kw)
    kw = string.lower(kw)
    if not keywords[kw] then -- check against keyword list
        return "Error, the '" .. kw .. "' keyword is not in the database. Check spelling."
    end
    
    kw = keywords[kw]
    return kw
end


-- Build combined tooltip text
function kwText(t, display)
        local tooltip = {}
        local temp = {}
   
        -- clean up keywords (ex. add Destiny to Revenge), if using the
        -- default (hover tooltip) output
        if display == "default" then t = kwFix(t) end
        table.sort(t)
        
        for i,v in ipairs(t) do
            local tip = getDescription(v)
            
            -- fix for instances of multiple spellings for the same keyword
            -- (ex. Curse & Curses)
            -- place descriptions as indexes in temp table to check against
            if not temp[tip] then 
                temp[tip] = i
                table.insert(tooltip, tip)
            end
        end
        
        -- build combined tooltip text
        display = display or 'default'
        if display == 'table' then
            tooltip = table.concat(tooltip, "\n|-\n|")
            tooltip = [=[
{| class = "article-table" style="width:100%;"
|-
|]=] .. tooltip .. [=[

|}]=]
        else
            tooltip = table.concat(tooltip, "<br /><br />")
        end
        return tooltip
end

-- Clean up requested keywords for special cases
function kwFix(t)
    -- build table with keywords as index for easier lookup
    -- also combines multiple entries of the same keyword
    -- NOTE: does NOT fix multiple spellings of the same keyword
    --       this is done later by discarding multiples of the same description
    local kwIndex = {}
    for i,v in ipairs(t) do
        kwIndex[string.lower(v)] = ''
    end
    
    -- if BOTH Night & Nightfall, remove redundant description
    if kwIndex['night'] and kwIndex['nightfall'] then
       kwIndex['nightfall'] = nil
    end
    
    -- if BOTH Mentor & Student, remove redundant description
    if kwIndex['mentor'] and kwIndex['student'] then
       kwIndex['student'] = nil
    end
    
    -- if BOTH Black Market & Market, remove redundant description
    if kwIndex['black market'] and kwIndex['market'] then
       kwIndex['market'] = nil
    end
    
    -- if Revenge, add Destiny
    if kwIndex['revenge'] and not kwIndex['destiny'] then
       kwIndex['destiny'] = ''
    end
    
    -- if Berserk, add Reckless
    if kwIndex['berserk'] and not kwIndex['reckless'] then
       kwIndex['reckless'] = ''
    end
    
    -- rebuild keyword table
    t = {}
    local index = 0
    for i,v in pairs(kwIndex) do
        index = index + 1
        t[index] = i
    end
    
    return t
end

-- convert string list into a table list
--   use for named template parameters which may contain one or more values
function listToTable(string, pattern)
    local table1 = {} -- first pass, remove text between parentheses ()
    local table2 = {} -- second pass, split text using separator
    local tableCombined
    local capture = '%(([^%(%)]*)%)'
    local seperator = pattern or ','
    local n -- throwaway variable for gsub returns
    
    -- strip any surrounding brackets ('[' and ']'), used elsewhere to skip categorization by keyword values in the parameter
    string = string.gsub(string, "[%[%]]", "")
    
    -- capture text tagged with parantheses, place into table1
	for value in string.gmatch(string, capture) do
		table.insert(table1, value)
	end
    
    -- remove captured text from the string
    string, n = string.gsub(string, capture .. ',', '')
    string, n = string.gsub(string, capture, '')
        
    -- split text at commas, place into table2
    table2 = mw.text.split(string, seperator)
    
    -- combine tables
    tableCombined = mergeTables(table1, table2)
        
    -- clean excess whitespace
    for i,v in pairs(tableCombined) do
        tableCombined[i] = mw.text.trim(v)
        -- remove 'whitespace' values
        if tableCombined[i] == '' then table.remove(tableCombined, i) end
    end
    
    return tableCombined
end

-- Create a table of another table's keys
function keysToTable(t)
    local keyset={}
    local n=0

    for k,v in pairs(t) do
        n=n+1
        keyset[n]=k
    end

    return keyset
end

-- Combine two tables together. Merge any values with non-number keys, append 
--   the rest to the end of the 1st table
function mergeTables(t1, t2)
    -- error correct for nil arguments
    if t1 and not t2 then return t1 end
    if t2 and not t1 then return t2 end
    
    -- throw error if an argument isn't a table
    if type(t1) ~= 'table' or type(t2) ~= 'table' then
       error("Module:HoverTooltip - 'mergeTables' requires two tables. It was given a "
        .. type(t1) .. " and a " .. type(t2) .. ".")
    end
    
    -- error correct for empty table arguments
    local keys1 = keysToTable(t1)
    if not keys1[1] then return t2 end
    
    local keys2 = keysToTable(t2)
    if not keys2[1] then return t1 end
    
    -- find max numerical key for the first table
    local keyMax = 0
    for k,_ in ipairs(t1) do
        if type(k) == 'number' and k >= keyMax then
            keyMax = k
        end
    end
    
    -- combine tables
    for k,v in ipairs(t2) do
        if type(k) == 'number' then -- append # keyed values to end
            keyMax = keyMax + 1
            t1[keyMax] = v
        else --                        merge/add anything else
            t1[k] = v
        end
    end
    
    return t1
end

--=======================================
--[==[Invokable Functions]==]
-- These Frame Object functions can be called from a wiki article or template 
--   with the syntax: {{#invoke:ModuleName|functionName|arg1|arg2|...}}
local p = {}

-- Main function for the 'KeywordHover' wiki template.
-- Returns description for one or more keywords.
--   Finds keywords listed in 'keywords' parameter, otherwise any unnamed
--     parameters in the parent template will be checked for descriptions.
--   Optional parameter 'single = true' forces only the first unnamed parameter
--     to be returned - for use in in-line text hover tooltips.
function p.keywordTip(frame)
    local args = getArgs(frame) -- clean the arguments using Module:Arguments on the dev wiki
    
    local kw = {} -- table to hold keywords
    local display = args.display or 'default'
    display = string.lower(display)
    
    -- test for input
    if args['keywords'] then
    
        -- get list of keywords (string value)
        kw = args['keywords']
        
        -- convert to table
        kw = listToTable(kw)
        
        -- get & return tooltip(s)
        kw = kwText(kw, display)
        
        return kw
    elseif args['namedOnly'] == 'true' then
 
        -- if the parameter 'namedOnly == true' is specified, then return
        -- nothing, skipping unnamed parameters (use for 'Card' or similar
        -- templates, where processing unnamed parameters is unwanted) 
        return
    elseif args[1] then
    
        -- use first argument only, if 'single = true' is specified
        if args['single'] == 'true' then
            kw[1] = args[1]  
            
        else
            kw = args
        end
        
        -- get & return tooltip(s)
        kw = kwText(kw, display)
        
        return kw
    else
        return "Error, no keyword was specified."
    end
end

-- Returns token card images
--   Meant to be displayed below keyword description tooltips.
function p.tokenTip(frame)
    local args = getArgs(frame)
    
    -- get list of images (string value)
    local tImg = args['tokens'] or ''
    
    -- test for input
    if tImg == '' then
        return "Error, no images were specified."
    else
        -- convert to table
        tImg = listToTable(tImg)
        
        -- convert image names to image wikitext calls
        table.sort(tImg)
        for i,image in ipairs(tImg) do
            tImg[i] = "[[File:Token - " .. image .. ".png|250px|link=" .. image 
                      .. "|alt=" .. image .. " Token]]"
        end
        
        -- combine images for tooltip
        tImg = table.concat(tImg, "<br />")
        return tImg
    end
end

-- Check parent template for either the 'keywords' or 'tokens' named parameters.
--   For cases such as the 'Card' template, where use with an #ifeq parser check
--   may avoid adding extraneous hover html and css if not needed.
function p.checkParams(frame)
    local args = getArgs(frame)
    
    local kwChk = args['keywords'] or ''
    local imgChk = args['tokens'] or ''
    
    if kwChk == '' and imgChk == '' then
        return 'false'
    else
        return 'true'
    end
end    

-- -----------------------------------------------------
return p
-- </pre> [[Category:Eternal Wiki Modules]]