Module:RecipeView

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

---
--- View side of model–view–controller framework for displaying recipes. Owns
--- and handles all choices of display, layout, rendering, and styling.
---
--- Should _only_ be invoked from RecipeController.
---
--- @module RecipeView
local RecipeView = {}



StyleUtils = require("Module:StyleUtils")



--region Private member variables

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

--endregion



--region Private constants

local PARAMETER_DISPLAY_OVERRIDE_LIST = "list"

local ATTR_SORT_VALUE = "data-sort-value"

local ICON_SIZE_LARGE = "large"
local ICON_SIZE_SMALL = "small"
local ICON_NONE = "none"

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

local MAX_INGREDIENTS = 3

local DEFAULT_RESULT_HEADER = "Result"

-- 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 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 resourceLinkWithAnchor(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 = "[[File:" .. resourceIcon .. "|" .. iconSize ..
			"|alt=" .. resourceName .."|link=" .. resourceName .. linkAnchor .. "]]"
	local linkPart = "[[" .. resourceName .. linkAnchor .. "|" .. resourceName .. "]]"

	return iconPart .. StyleUtils.NBSP .. linkPart
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 = StyleUtils.NBSP .. "#" .. i
		end
		row:tag("th"):wikitext("Ingredient" .. numbering):done()
	end

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

	row:done():newline()
end



---
--- Returns a new recipe HTML table entity created with standard
--- display and interactivity classes.
---
---@return table standard MediaWiki HTML table entity
local function startNewRecipeTable()

	local recipeTable = mw.html.create("table")
	StyleUtils.styleRecipeTable(recipeTable)
	recipeTable:newline()

	return recipeTable
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 startNewIngredientsTable()

	local ingTable = mw.html.create("table")
	StyleUtils.styleIngredientsSubtable(ingTable)
	ingTable:newline()

	return ingTable
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
local function makeBuildingColumn(htmlTableRow, buildingName)

	htmlTableRow:tag("td")
			:attr(ATTR_SORT_VALUE, buildingName)
			:tag("div"):addClass(StyleUtils.CLASS_BUILDING_ICON)
				:wikitext(StyleUtils.BUILDING_LINK(buildingName, ICON_SIZE_LARGE))
			:done():newline()
		: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(ATTR_SORT_VALUE, gradeStars)
				:wikitext(StyleUtils.STARS[gradeStars]() .. StyleUtils.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, numIngredientsTotal)
	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
---@param numOptions number how many options total, for labeling the data
local function makeOptionRow(htmlTable, optionTable, numOptions)

	local row = htmlTable:tag("tr")
	row:tag("td")
			:wikitext(optionTable[INDEX_OPTION_STACK_SIZE])
			:done()

	local optionDiv = row:tag("td"):tag("div")
	if numOptions > 1 then
		optionDiv:addClass(StyleUtils.CLASS_OPTIONAL_INGREDIENT_ICON)
	else
		optionDiv:addClass(StyleUtils.CLASS_SINGLE_INGREDIENT_ICON)
	end

	optionDiv:wikitext(resourceLinkWithAnchor(optionTable[INDEX_OPTION_GOOD_NAME],
				optionTable[INDEX_OPTION_GOOD_ICON], StyleUtils.IMG_M(),
				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)

	if not resultStackSize or resultStackSize == 0 then
		resultStackSize = 1
	end

	local iconAndLinkPart = resourceLinkWithAnchor(resultName, resultIcon,
			StyleUtils.IMG_L(), LINK_ANCHOR_INGREDIENT )

	htmlTableRow:tag("td"):attr(ATTR_SORT_VALUE, resultName)
			:wikitext(resultStackSize)
			:tag("div"):addClass(StyleUtils.CLASS_PRODUCT_ICON):newline()
				:wikitext(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 = startNewRecipeTable()
		newNode:tag("caption"):wikitext(numRecipes .. " recipes using " .. 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 = startNewRecipeTable()
		newNode:tag("caption"):wikitext(numRecipes .. " recipes using " .. 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 = startNewRecipeTable()
		newNode:tag("caption"):wikitext(numRecipes .. " recipes for " .. 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 = startNewRecipeTable()
		newNode:tag("caption"):wikitext(numRecipes .. " recipe in the " .. buildingName .. " for " .. 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 = startNewRecipeTable()
		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(StyleUtils.BUILDING_LINK(buildingName, ICON_NONE)
					.. StyleUtils.NBSP .. StyleUtils.PAREN_STARS[gradeStars]())
		else

			local isResource, linkText = pcall(StyleUtils.RESOURCE_LINK, productName, ICON_SIZE_SMALL)
			if not isResource then
				if string.find(linkText, "^No goods found") then
					linkText = StyleUtils.SERVICE_LINK(productName, ICON_SIZE_SMALL)
				end
				-- If no service found, then return something more graceful
				if string.find(linkText, "^No service found") then
					linkText = "N/A"
				end
			end

			newNode = mw.html.create("li")
					:wikitext(linkText .. StyleUtils.NBSP
							.. StyleUtils.PAREN_STARS[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 numForSort = 0
			local optionsGrid = startNewIngredientsTable()
			for _, option in ipairs(iList) do
				makeOptionRow(optionsGrid, option, #iList)
				numForSort = math.max(numForSort, option[INDEX_OPTION_STACK_SIZE])
			end

			optionsGrid:done()
			newNode:tag("td"):attr(ATTR_SORT_VALUE, numForSort)
					: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(displayOverride)

	beginning:node(middle)
	beginning:done()

	middle = ""

	if displayOverride == PARAMETER_DISPLAY_OVERRIDE_LIST then

		return beginning
	else

		local divContainer = StyleUtils.styleRecipeContainer(mw.html.create("div"))
		divContainer:newline()
		divContainer:node(beginning)

		return divContainer
	end
end

--endregion

return RecipeView