Module:RecipeView

--- @module RecipeView local RecipeView = {}

--region Private member variables

beginning = "" middle = "" ending = ""

local imgS = mw.getCurrentFrame:expandTemplate{ title = "ImgS" } local imgM = mw.getCurrentFrame:expandTemplate{ title = "ImgM" } local imgL = mw.getCurrentFrame:expandTemplate{ title = "ImgL" }

local stars = { [0] = mw.getCurrentFrame:expandTemplate{ title = "0Star" }, [1] = mw.getCurrentFrame:expandTemplate{ title = "1Star" }, [2] = mw.getCurrentFrame:expandTemplate{ title = "2Star" }, [3] = mw.getCurrentFrame:expandTemplate{ title = "3Star" } }

--endregion

--region Private constants

local INDEX_OPTION_STACK_SIZE = "stackSize" local INDEX_OPTION_GOOD_NAME = "name" local INDEX_OPTION_GOOD_ICON = "icon"

local PARAMETER_DISPLAY_OVERRIDE_LIST = "list"

local MAX_INGREDIENTS = 3 local DEFAULT_RESULT_HEADER = "Result"

-- wikitable classes for tables local CLASS_WIKITABLE_SORTABLE_COLLAPSIBLE = "wikitable sortable mw-collapsible"

-- Shortcut markup that's easier for Lua string concatenations local BR = " " local NBSP = " " local BOLD = "'''"

-- Page anchors for links local LINK_ANCHOR_PRODUCT = "#Product" local LINK_ANCHOR_INGREDIENT = "#Ingredient"

--endregion

--region Private methods

--- --- Formats seconds as mm:ss format, with leading zeros where necessary. --- ---@param seconds number of seconds to reformat (if any, can be nil) ---@return string representing mm:ss time format, or empty string if not needed local function formatTime(seconds)

if not seconds or seconds == 0 then return "" end

local minutes = math.floor(seconds/60) local remainingSeconds = seconds % 60 return string.format("%02d:%02d", minutes, remainingSeconds) end

--- --- Formats a standard link to a building. Does not invoke the template, but it --- could be modified to do so in the future. --- ---@param buildingName string the display name of the building ---@param buildingIcon string the filename for the icon ---@param iconSize string representing the desired size of the icon ---@return string an assembled link, with icon (if large enough) and text link to page local function buildingLink(buildingName, buildingIcon, iconSize)

if not buildingIcon or not iconSize or not buildingName then error("Building parameters cannot be nil.") end

-- Skip the smallest icons for the building links. local iconPart = "" if iconSize > imgS then iconPart = "" .. NBSP end

local linkPart = "" .. buildingName .. ""

return iconPart .. linkPart end

--- --- Formats a standard link to a resource. Does not invoke the template, but it --- could be modified to do so in the future. --- ---@param resourceName string the display name of the good ---@param resourceIcon string the filename for the icon ---@param iconSize string representing the desired size of the icon ---@param linkAnchor string an anchor on the page, if needed ---@return string an assembled link, with icon and text link to page local function resourceLink(resourceName, resourceIcon, iconSize, linkAnchor)

if not resourceName or not resourceIcon or not iconSize then error("Resource parameters cannot be nil.") end

if not linkAnchor then linkAnchor = "" end

local iconPart = "" local linkPart = "" .. resourceName .. ""

return iconPart .. NBSP .. linkPart end

--- --- Writes wikimarkup for showing stars in parenthesis, useful for in-line --- recipe references, like "Apothecary (★★)" or "Grain (★)" --- ---@param gradeStars number of stars to show ---@return string wiki markup showing stars in parentheses local function parenStars(gradeStars)

local starsPart = stars[gradeStars]

if not starsPart or starsPart == "" then return "" end

return "(" .. starsPart .. ")" end

--- --- Creates a header row under the provided MediaWiki HTML table entity. --- ---@param tableNode table MediaWiki HTML table entity ---@param numIngredients number of ingredient columns ---@param finalColumnName string the title for the final/result column. local function makeStandardRecipeTableHeaderRow(tableNode, numIngredients, finalColumnName)

-- Use generic defaults if they are not provided. if not numIngredients then numIngredients = MAX_INGREDIENTS end if not finalColumnName then finalColumnName = DEFAULT_RESULT_HEADER end

local row = tableNode:tag("tr")

row:tag("th"):wikitext("Building"):done row:tag("th"):wikitext("Efficiency"):done

for i = 1, math.min(numIngredients, MAX_INGREDIENTS) do		local numbering = "" if numIngredients > 1 then numbering = "#" .. i .. NBSP end row:tag("th"):wikitext("Ingredient" .. NBSP .. numbering .. "options"):done end

row:tag("th"):wikitext(finalColumnName):done

row:done:newline end

--- --- Returns a standard MediaWiki HTML table entity created with standard --- display and interactivity classes. --- ---@return table standard MediaWiki HTML table entity local function startNewWikiTable

return mw.html.create("table"):addClass(CLASS_WIKITABLE_SORTABLE_COLLAPSIBLE):newline end

--- --- Returns a standard MediaWiki HTML table entity created with no classes or --- interactivity, making it invisible, for layout purposes only. --- ---@return table invisible MediaWiki HTML table entity local function startNewInvisibleTable

return mw.html.create("table"):newline end

--- --- Makes the content of the building column under the provided HTML table row --- entity. --- ---@param htmlTableRow table MediaWiki HTML table row entity ---@param buildingName string the name of the building ---@param buildingIcon string the filename for the icon local function makeBuildingColumn(htmlTableRow, buildingName, buildingIcon)

htmlTableRow:tag("td"):wikitext(buildingLink(buildingName, buildingIcon, imgL)):done:newline end

--- --- Makes the content of the recipe efficiency column under the provided HTML --- table row entity. --- ---@param htmlTableRow table MediaWiki HTML table row entity ---@param gradeStars number the stars of efficiency ---@param productionTime string the formatted for display time local function makeEfficiencyColumn(htmlTableRow, gradeStars, productionTime)

htmlTableRow:tag("td"):attr('data-sort-value', gradeStars) :wikitext(stars[gradeStars] .. BR .. productionTime):done:newline end

--- --- Pads the table row with empty cells depending on how many ingredient groups --- are in the recipe from which this is called vs. the number of ingredient --- columns in the table overall. --- ---@param htmlTableRow table MediaWiki HTML table row entity ---@param numIngredientInRecipe number of ingredient groups in the recipe ---@param numIngredientsTotal number of ingredient groups in the table overall local function makeFillerBlankCells(htmlTableRow, numIngredientInRecipe, numIngredientsTotal)

if numIngredientInRecipe < numIngredientsTotal then htmlTableRow:tag("td"):wikitext("—"):done makeFillerBlankCells(htmlTableRow, numIngredientInRecipe + 1, numIngredientInRecipe) end end

--- --- Makes the row and fills it with content. Puts the row into the provided --- HTML table entity. --- --- Needs option information structured in a table, like this: --- optionTable = { --- 	[INDEX_OPTION_STACK_SIZE] = 9, --- 	[INDEX_OPTION_GOOD_NAME] = "Display Name", --- 	[INDEX_OPTION_GOOD_ICON] = "Icon_filename.png" --- } --- ---@param htmlTable table MediaWiki HTML table entity ---@param optionTable table of one good's option data: stack size, name, icon local function makeOptionRow(htmlTable, optionTable)

local row = htmlTable:tag("tr") row:tag("td"):wikitext(BOLD .. optionTable[INDEX_OPTION_STACK_SIZE] .. BOLD):done row:tag("td"):wikitext(resourceLink(optionTable[INDEX_OPTION_GOOD_NAME], optionTable[INDEX_OPTION_GOOD_ICON], imgM, LINK_ANCHOR_PRODUCT)):done row:done:newline end

--- --- Makes the content of the result column under the provided HTML table row --- entity. Agnostic of whether the result is a product or a service. --- ---@param htmlTableRow table MediaWiki HTML table row entity ---@param resultStackSize number of results provided by the recipe ---@param resultName string the display name of the result ---@param resultIcon string the filename of the result's icon local function makeResultColumn(htmlTableRow, resultStackSize, resultName, resultIcon)

local stackSizePart = "" if resultStackSize and resultStackSize > 0 then stackSizePart = BOLD .. resultStackSize .. BOLD .. NBSP end local iconAndLinkPart = resourceLink(resultName, resultIcon, imgL, LINK_ANCHOR_INGREDIENT)

htmlTableRow:tag("td"):attr('data-sort-value', resultName) :wikitext(stackSizePart .. iconAndLinkPart):done:newline end

--endregion

--region Public methods

--- --- Initializes the table, populates the caption, and writes and header row, --- all appropriate for a table focusing on ingredients at one building. --- --- The default is a wikitable output. With the displayOverride flag, this --- method will instead make a list. --- ---@param ingredientName string the name of the ingredient this table is based on ---@param buildingName string the name of the building ---@param displayOverride string a flag for the output type if not the default ---@param numRecipes number of recipes that will be in this table, if it's known ---@param numIngredients number of columns that will be written to this table, if known ---@param finalColumnName string the header label of the last column function RecipeView.startViewForIngredientAndBuilding(ingredientName, buildingName, displayOverride, numRecipes, numIngredients, finalColumnName)

-- These should never be nil at runtime. if not ingredientName then error("Parameter is invalid for ingredient name.") end if not buildingName then error("Parameter is invalid for building name.") end -- Use generic defaults if they are not provided. if not numRecipes then numRecipes = "All" end

local newNode if displayOverride == PARAMETER_DISPLAY_OVERRIDE_LIST then newNode = mw.html.create("ul") else newNode = startNewWikiTable newNode:tag("caption"):wikitext(numRecipes .. " recipes that require " .. ingredientName .. " in the " .. buildingName .. "."):done:newline

makeStandardRecipeTableHeaderRow(newNode, numIngredients, finalColumnName) end

beginning = newNode -- Return value is not used by the Controller, but for debugging. return newNode end

--- --- Initializes the table, populates the caption, and writes and header row, --- all appropriate for a table focusing on ingredients. --- --- The default is a wikitable output. With the displayOverride flag, this --- method will instead make a list. --- ---@param ingredientName string the name of the ingredient this table is based on ---@param displayOverride string a flag for the output type if not the default ---@param numRecipes number of recipes that will be in this table, if it's known ---@param numIngredients number of columns that will be written to this table, if known ---@param finalColumnName string the header label of the last column function RecipeView.startViewForIngredient(ingredientName, displayOverride, numRecipes, numIngredients, finalColumnName)

-- These should never be nil at runtime. if not ingredientName then error("Parameter is invalid for ingredient name.") end -- Use generic defaults if they are not provided. if not numRecipes then numRecipes = "All" end

local newNode if displayOverride == PARAMETER_DISPLAY_OVERRIDE_LIST then newNode = mw.html.create("ul") else newNode = startNewWikiTable newNode:tag("caption"):wikitext(numRecipes .. " recipes that require " .. ingredientName .. "."):done:newline

makeStandardRecipeTableHeaderRow(newNode, numIngredients, finalColumnName) end

beginning = newNode -- Return value is not used by the Controller, but for debugging. return newNode end

--- --- Initializes the table, populates the caption, and writes and header row, --- all appropriate for a table focusing on a product. --- --- The default is a wikitable output. With the displayOverride flag, this --- method will instead make a list. --- ---@param productName string the name of the product this table is based on ---@param displayOverride string a flag for the output type if not the default ---@param numRecipes number of recipes that will be in this table, if it's known ---@param numIngredients number of columns that will be written to this table, if known ---@param finalColumnName string the header label of the last column function RecipeView.startViewForProduct(productName, displayOverride, numRecipes, numIngredients, finalColumnName)

-- These should never be nil at runtime. if not productName then error("Parameter is invalid for product name.") end -- Use generic defaults if they are not provided. if not numRecipes then numRecipes = "All" end

local newNode if displayOverride == PARAMETER_DISPLAY_OVERRIDE_LIST then newNode = mw.html.create("ul") else newNode = startNewWikiTable newNode:tag("caption"):wikitext(numRecipes .. " recipes that produce " .. productName .. "."):done:newline

makeStandardRecipeTableHeaderRow(newNode, numIngredients, finalColumnName) end

beginning = newNode -- Return value is not used by the Controller, but for debugging. return newNode end

--- --- Initializes the table, populates the caption, and writes and header row, --- all appropriate for a table focusing on a product at one building. --- --- The default is a wikitable output. With the displayOverride flag, this --- method will instead make a list. --- ---@param productName string the name of the product this table is based on ---@param buildingName string the name of the building this table is based on ---@param displayOverride string a flag for the output type if not the default ---@param numRecipes number of recipes that will be in this table, if it's known ---@param numIngredients number of columns that will be written to this table, if known ---@param finalColumnName string the header label of the last column function RecipeView.startViewForProductAndBuilding(productName, buildingName, displayOverride, numRecipes, numIngredients, finalColumnName)

-- These should never be nil at runtime. if not productName then error("Parameter is invalid for product name.") end if not buildingName then error("Parameter is invalid for building name.") end -- Use generic defaults if they are not provided. if not numRecipes then numRecipes = "All" end

local newNode if displayOverride == PARAMETER_DISPLAY_OVERRIDE_LIST then newNode = mw.html.create("ul") else newNode = startNewWikiTable newNode:tag("caption"):wikitext(numRecipes .. " recipe in the " .. buildingName .. " that produces " .. productName .. "."):done:newline

makeStandardRecipeTableHeaderRow(newNode, numIngredients, finalColumnName) end

beginning = newNode -- Return value is not used by the Controller, but for debugging. return newNode end

--- --- Initializes the table, populates the caption, and writes and header row, --- all appropriate for a table focusing on a building. --- --- The default is a wikitable output. With the displayOverride flag, this --- method will instead make a list. --- ---@param buildingName string the name of the building this table is based on ---@param displayOverride string a flag for the output type if not the default ---@param numRecipes number of recipes that will be in this table, if it's known ---@param numIngredients number of columns that will be written to this table, if known ---@param finalColumnName string the header label of the last column function RecipeView.startViewForBuilding(buildingName, displayOverride, numRecipes, numIngredients, finalColumnName)

-- These should never be nil at runtime. if not buildingName then error("Parameter is invalid for building name.") end -- Use generic defaults if they are not provided. if not numRecipes then numRecipes = "All" end

local newNode if displayOverride == PARAMETER_DISPLAY_OVERRIDE_LIST then newNode = mw.html.create("ul") else newNode = startNewWikiTable newNode:tag("caption"):wikitext(numRecipes .. " recipes in the " .. buildingName .. "."):done:newline

makeStandardRecipeTableHeaderRow(newNode, numIngredients, finalColumnName) end

beginning = newNode -- Return value is not used by the Controller, but for debugging. return newNode end

--- --- Adds a new row to the content being built. This is typically called from a --- Controller that knows how many rows to add. RecipeView maintains the output --- in-progress while rows are added, so that layout and formatting can be --- owned by this module instead of the Controller. --- --- Expects a table-of-tables for ingredients information, like this: --- ingredientsList = { --- 	[1] = { --- 		[1] = { --- 			[INDEX_OPTION_STACK_SIZE] = 9, --- 			[INDEX_OPTION_GOOD_NAME] = "Display Name", --- 			[INDEX_OPTION_GOOD_ICON] = "Icon_filename.png" --- 		}, --- 		[2] = { ... }, --- 		[3] = { ... }, --- 		... -- or fewer or up to six options --- 	}, --- 	[2] = { --- 		[1] = { ... }, --- 		[2] = { ... }, --- 		... -- or fewer or up to six options --- 	}, --- 	[3] = { ... } -- or fewer ingredient option groups --- } --- ---@param displayOverride string a flag for the output type if not the default ---@param buildingName string the name of the building of this recipe ---@param buildingIcon string the icon of the building ---@param gradeStars number of stars of efficiency of this recipe ---@param productionTime number of seconds to produce (if any--nil okay for none) ---@param ingredientsList table of ingredient subtables of options ---@param productStackSize number how many of the products are produced by this recipe (if any--nil okay for none) ---@param productName string the display name of the product ---@param productIcon string the icon of the product function RecipeView.addRowForRecipe(displayOverride, numIngredients,									buildingName, buildingIcon,									gradeStars, productionTime, ingredientsList,									productStackSize, productName, productIcon,									requiredBuilding)

local newNode if displayOverride == PARAMETER_DISPLAY_OVERRIDE_LIST then -- List version. If the building is required, then show the product -- name with stars instead of showing the building name N times. if not requiredBuilding then newNode = mw.html.create("li"):wikitext(buildingLink(buildingName, buildingIcon, imgS) .. NBSP .. parenStars(gradeStars)) else newNode = mw.html.create("li"):wikitext(resourceLink(productName, productIcon, imgS) .. NBSP .. parenStars(gradeStars)) end else -- Table version. newNode = mw.html.create("tr"):newline makeBuildingColumn(newNode, buildingName, buildingIcon) makeEfficiencyColumn(newNode, gradeStars, formatTime(productionTime))

-- Fill in with any needed blank cells. makeFillerBlankCells(newNode, #ingredientsList, numIngredients)

for _, iList in ipairs(ingredientsList) do

local optionsGrid = startNewInvisibleTable for _, option in ipairs(iList) do				makeOptionRow(optionsGrid, option) end

optionsGrid:done newNode:tag("td"):node(optionsGrid):done:newline end

makeResultColumn(newNode, productStackSize, productName, productIcon) end

newNode:done middle = middle .. tostring(newNode)

return newNode end

--- --- Wraps up anything outstanding for the view, then returns the entire --- MediaWiki entity originally started in the respective method. --- ---@return string the HTML markup of the completed view function RecipeView.endView

beginning:node(middle) beginning:done

middle = ""

return beginning end

--endregion

return RecipeView