Module:Element

Documentation

This documentation is transcluded from Module:Element/doc. (Edit | history)
Note to editors: Please don't categorize this template by editing it directly. Instead, place the category in its documentation page, in its "includeonly" section.

Note: This template is used on a lot of pages. In order not to put too much load on the servers, edits should be kept to a bare minimum.
Please discuss proposed changes on the talk page first.
Editing a template causes all pages that use the template to be re-rendered. If the Template is used often, this can put a lot of load on the servers since it fills up the job queue. [statistics]

This page documents the features of the templates {{Area}}, {{Node}}, {{Relation}}, and {{Way}}. These templates can be used for inserting links to either nodes, ways, or relations (area links to a closed way) as well as tool links. All templates share a common codebase. Therefore, they work almost identical ({{Area}} and {{Relation}} have each a minor difference to the rest).
It was rewritten in Autumn 2018 using fewer options and Lua.

Usage

The usage is similar for all templates described here. You just have to adjust the name (e.g. {{Area|...}} instead of {{Node|...}}). Writing

{{node|12345}}

results in

12345 12345

Overview of all parameters:

Name/Number	Possible values	Description
1	Integer	refers to an OSM ID, required parameter
2	String	label for the main link, default: same as ID
tools	all, josm, mini, no, or short	tool links to be displayed, default: no(ne)
lang	language code from Mediawiki's list or special code in this wiki	used to assure the labelling of the links in a certain language (see section Translation below)

Feature list

Wiki code	Result	Note
{{Relation|2345}}	2345 2345	The icon links to the wiki article about relations.
{{Relation|2345|Promenade}}	Promenade Promenade
{{Relation|2345|tools= all }}	2345 2345 (iD JOSM history analyse)
{{Relation|2345|tools= all |Promenade}}	Promenade Promenade (iD JOSM history analyse)
{{Relation|2345|tools= all |lang= vi }}	2345 2345 (iD JOSM lịch sử phân tích)	translation to Vietnamese
{{Relation|2345|Promenade|tools= all |lang= ar }}	Promenade Promenade (iD JOSM التاريخ analyse)	translation falls back to English as Arabic translation is incomplete.
{{Way|12346|tools= all |lang= ar }}	12346 12346 (iD JOSM التاريخ)	links displayed depending on the element
{{Relation|2345|tools= josm }}	2345 2345 (JOSM)
{{Relation|2345|tools= josm |Promenade}}	Promenade Promenade (JOSM)
{{Relation|2345|tools= mini }}	23452345
{{Relation|2345|tools= mini |Promenade}}	PromenadePromenade
{{Relation|2345|tools= no }}	2345 2345
{{Relation|2345|tools= no |Promenade}}	Promenade Promenade
{{Relation|2345|tools= short }}	23452345
{{Relation|2345|tools= short |Promenade}}	PromenadePromenade
{{Relation||Promenade}}		Does not work, ID required.

Translation

If the parameter tools is set to all, the link labelled history will be shown. In case of {{Relation}} there is an additional link analyse. Their labels will align themselves to the page language. There is also a lang parameter for explicitly setting the language. Extracting the language of a page seems to be an expensive process (for the parser which takes longer to create the page). Unfortunately, this is also repeated for every occurrence of the template even on the same page. Therefore, translations are limited to a minimum (i.e. there is a translation with tools=all only).

lang parameter

The lang parameter is used to explicitly request a translated version of the template. It translates two English texts ("analyse" and "history"). These are used with the setting tools=all only. It also adds the prefix for the link to the article "relation" (below the icon) regardless of its existence. Whilst the language is automatically detected, the link will not change without request. This is due to the fact that the icon's wikicode is generated before the language version may be detected.

Languages for Translation

The module stores all translations in Module:Element/translation. There are the following priorities for examining the correct language:

1. user input in lang parameter
2. dedicated language namespace (DE, ES, FR, IT, JA, NL, RU)
3. language title prefix (all other prefixes)
4. English as default

This means that there is no specified fallback language used apart from English.
The templates {{Hu:Relation}}, {{Pl:Relation}} and {{Pt:Relation}} are versions of this template which fall back to Hungarian, Polish and Portuguese if no user input is provided.

Adding a Language

Please paste the following lines into the code of Module:Element/translation:

 translateAnalyse = {
 	-- other language codes alphabetically before 'code'
 	['code'] = "your translation",
 	-- other language codes alphabetically after 'code'
 },
 translateHistory = {
 	-- other language codes alphabetically before 'code'
 	['code'] = "your translation",
 	-- other language codes alphabetically after 'code'
 },

Missing language

If there is no complete translation, the page is also added to one of the subcategories of Category:Pages with missing translation. This is useful for finding missing translations in this wiki. The language name is read from Module:OSM Constants or mw.language.fetchLanguageName(pageLanguage, 'en').

Design Decisions

This section aims to explain why this template works this way. It should be read before proposing any changes. There may be different opinions (see Discussion page), but this documentation only focuses on the current implementation.

Why are the tools not shown by default?

This is simply too "expensive" (see translation). This setting would result in many pages being displayed in maintenance categories like Category:Pages where template include size is exceeded. It would also assume that everyone using this template (think of a mapper fixing a wiki error without wiki background) wants to have all tools available.

Why are there so few tools only?

This is a general purpose template, if you need special links, you can add them directly to your page. Please remember that the parser is not able to cache this template, so if you link to five relations, it has to create 35 (= 5 * 7) links in the worst case (i.e. displaying all tools).

Why was the "undefined relation" option dropped?

Simply because it fails its purpose: This template is for linking to a relation, if there is no relation (yet) you can simply leave out this template (this is commonly done now anyway). This would be like a link to a web page with an "under construction" banner only. In addition, as it displayed text, it had to compute the page language and translate the text for every call, a functionality that can be archived at lower cost by inserting the text itself.

Why is there no "status"?

Template:State provides a more detailed way of documenting mapping statuses.

Why are shortened URLs used instead of the long forms?

There are pages that include this template over 1000 times. Replacing short URLs like osm.org with openstreetmap.org would increase the size of the expanded text by 11 characters. The change would scale up to 11,000 characters in such an article. There are also options which use multiple links, this would result in an even bigger increase.

This template renders link to specified relation with possible extra tools.

Template parameters

Parameter		Description	Type	Status
Relation id	1	Relation id (number).	Number	required
Label for rendering	2	Label to render instead of relation id	Line	optional
Linked tools	tools	Tools linked next to relation link. Suggested values all mini short no	Line	optional
Language	lang	Language of rendered template. Example de	String	optional

--[[ Please remember to use the talk page before changing this template! 
	 When the first Lua version was written this was used on more than 5000 pages,
	 now it is probably some 3000 more. 
	 A change will cause a re-rendering of all pages. Keep that in mind! ]]--

local p = {}
local translations = mw.loadData('Module:Element/translation')

-- start for Template:Area
function p.area(frame)
	-- extracting arguments
	local areaId = frame.args[1]
	local areaName = frame.args[2]
	local toolbarSetting = frame.args["tools"]
	local langcodeInput = frame.args["lang"]
	
	-- checking for correct parameters
	assert(tonumber(areaId), "Given way id parameter is not a number")
	if areaName == "" then
		areaName = nil
	elseif areaName ~= nil then
		areaName = mw.text.trim(areaName)
	end
	areaId = mw.text.trim(areaId)
	if langcodeInput ~= nil then langcodeInput = string.lower(langcodeInput) end
	
	return elementText("area", areaId, areaName, toolbarSetting, langcodeInput)
end

-- start for Template:Node
function p.node(frame)
	-- extracting arguments
	local nodeId = frame.args[1]
	local nodeName = frame.args[2]
	local toolbarSetting = frame.args["tools"]
	local langcodeInput = frame.args["lang"]
	
	-- checking for correct parameters
	assert(tonumber(nodeId), "Given node id parameter is not a number")
	if nodeName == "" then
		nodeName = nil 
	elseif nodeName ~= nil then
		nodeName = mw.text.trim(nodeName)
	end
	nodeId = mw.text.trim(nodeId)
	if langcodeInput ~= nil then langcodeInput = string.lower(langcodeInput) end
	
	return elementText("node", nodeId, nodeName, toolbarSetting, langcodeInput)
end

-- start for Template:Relation
function p.relation(frame)
	-- extracting arguments
	local relationId = frame.args[1]
	local relationName = frame.args[2]
	local toolbarSetting = frame.args["tools"]
	local langcodeInput = frame.args["lang"]
	
	-- checking for correct parameters
	assert(tonumber(relationId), "Given relation id parameter is not a number")
	if relationName == "" then
		relationName = nil 
	elseif relationName ~= nil then
		relationName = mw.text.trim(relationName)
	end
	relationId = mw.text.trim(relationId)
	if langcodeInput ~= nil then langcodeInput = string.lower(langcodeInput) end
	
	return elementText("relation", relationId, relationName, toolbarSetting, langcodeInput)
end

-- start for Template:Way
function p.way(frame)
	-- extracting arguments
	local wayId = frame.args[1]
	local wayName = frame.args[2]
	local toolbarSetting = frame.args["tools"]
	local langcodeInput = frame.args["lang"]
	
	-- checking for correct parameters
	assert(tonumber(wayId), "Given way id parameter is not a number")
	if wayName == "" then
		wayName = nil 
	elseif wayName ~= nil then
		wayName = mw.text.trim(wayName)
	end
	wayId = mw.text.trim(wayId)
	if langcodeInput ~= nil then langcodeInput = string.lower(langcodeInput) end
	
	return elementText("way", wayId, wayName, toolbarSetting, langcodeInput)
end

-- Main function compiling the wiki text
function elementText(elementType, elementId, elementName, toolbarSetting, langcodeInput)
	local output = {}
	local elementDescription = elementType
	if elementType == "area" then elementType = "way" end -- non-existing area type
	
	output[1] = '<span class="plainlinks"><bdi class="sortkey" style="display:none;speak:none">'
    if elementName == nil then
        output[2] = elementId
    else
        output[2] = elementName
    end
	output[3] = '</bdi>'
	
	if(toolbarSetting == "mini") then 
		output[4] = '[//osm.org/' .. elementType ..'/' .. elementId
		if elementName == nil then
			output[5] = '<span title="browse ' .. elementDescription .. '">' .. elementId
		else
			output[5] = '<span title="browse ' .. elementDescription .. ' ' .. elementId
			 .. '">' .. elementName
		end
		output[6] = '</span>]'
	
	elseif (toolbarSetting == "short") then
		output[4] = '<small>[//osm.org/' .. elementType .. '/' .. elementId
		if elementName == nil then
			output[5] = '<span title="browse ' .. elementDescription .. '">' .. elementId
		else
			output[5] = '<span title="browse ' .. elementDescription .. ' ' .. elementId
			 .. '">' .. elementName
		end
		output[6] = '</span>]&nbsp;<tt class="noprint" style="background:#EEF">(' ..
			'[//osm.org/edit?editor=id&' .. elementType .. '=' .. elementId .. 
			'<span title="iD">i</span>]&nbsp;'
		output[7] = '[http://localhost:8111/import?url=https://api.osm.org/api/0.6/'
			 .. elementType .. '/' .. elementId .. '/full <span title="JOSM">J</span>]'
		output[8] = ')</tt></small>'
	
	else
		output[4] = '[[File:Osm element ' .. elementDescription .. '.svg|20px|link='
		if langcodeInput ~= nil and langcodeInput ~= 'en' then
			output[5] = langcodeInput .. ':' .. string.upper(string.sub(elementDescription, 1, 1))
				 .. string.sub(elementDescription, 2, -1)
			--[[ no case distinction in page namespaces, 
				no check for page existance for the sake of faster processing ]]--
		else
			output[5] = elementDescription
		end
		output[6] = '|' .. elementDescription .. ']]&nbsp;'
		output[7] = '[//osm.org/' .. elementType .. '/' .. elementId
			.. ' <span title="browse '.. elementDescription
		if elementName == nil then
			output[8] = '">' .. elementId
		else
			output[8] = ' ' .. elementId .. '">' .. elementName
		end
		output[9] = '</span>]'
		
		if toolbarSetting == "all" then
			local pageLanguage = langcode(langcodeInput)
			local translationComplete = true
			local transHistory = translations.translateHistory[pageLanguage]
			if not transHistory then
				translationComplete = false
				transHistory = translations.translateHistory['en']
			end
			
			output[10] = ' <small>([//osm.org/edit?editor=id&' 
				 .. elementType .. '=' .. elementId .. ' iD] '
			output[11] = '[http://localhost:8111/import?url=https://api.osm.org/api/0.6/'
				 .. elementType .. '/' .. elementId .. '/full JOSM] '
			output[12] = '[http://osm.virtuelle-loipe.de/history/?type='
				 .. elementType .. '&ref=' .. elementId .. ' ' .. transHistory .. ']'
			if elementType == 'relation' then -- relation analysis
				local transAnalyse = translations.translateAnalyse[pageLanguage]
				if not transAnalyse then
					translationComplete = false
					transAnalyse = translations.translateAnalyse['en']
				end
				output[13] = ' [http://ra.osmsurround.org/analyze.jsp?relationId='
					.. elementId .. ' ' .. transAnalyse ..']'
			end
			table.insert(output, ')</small>')
			if not translationComplete then
				local fullEnglishName = languageName(pageLanguage)
				if string.len(fullEnglishName) ~= 0 then
					table.insert(output, '[[Category:Pages unavailable in '
						.. fullEnglishName .. ']] [[File:Translate.svg|x10px|link='
						.. 'Module:Element#Adding_a_Language|Help translate this to '
						.. fullEnglishName .. ']]')
				end
			end

		elseif toolbarSetting == "josm" then
			output[10] = ' <small>([http://localhost:8111/import?url='
				 .. 'https://api.openstreetmap.org/api/0.6/' .. elementType
			output[11] = '/' .. elementId .. '/full JOSM])</small>'
		end
	end
	
	table.insert(output, "</span>") -- ends class plainlinks
	return tostring(table.concat(output))
end

-- this uses the external module 'OsmPageTitleParser': 
function langcode(langcodeInput)
	--[[ Priorities:
		1 user input
		2 dedicated language namespace
		3 language title prefix
		4 'en' as default
	]]--

	if langcodeInput then
		return string.lower(langcodeInput)
	end

	local langModule = require('Module:OsmPageTitleParser')
	return tostring((langModule.parseTitle(mw.title.getCurrentTitle()).language):getCode())
end

function languageName(code)
	local constantsModule = mw.loadData('Module:OSM Constants')
	-- should be already loaded (needed by OsmPageTitleParser as well)
	local customLangName = constantsModule.customLangCodes[code]
	
	if customLangName ~= nil then
		return customLangName
	else
		return mw.language.fetchLanguageName(code, 'en')
	end
end
	
return p