GetElementData: Difference between revisions

Latest revision as of 18:35, 31 January 2022

This function retrieves element data attached to an element under a certain key.

Syntax

var getElementData ( element theElement, string key [, bool inherit = true] )

OOP Syntax Help! I don't understand this!

Method: element:getData(...)

Counterpart: setElementData

Required Arguments

theElement: This is the element with data you want to retrieve.
key: The name of the element data entry you want to retrieve. (Maximum 31 characters.)

Optional Arguments

inherit: - toggles whether or not the function should go up the hierarchy to find the requested key in case the specified element doesn't have it.

Returns

This function returns a variable containing the requested element data, or false if the element or the element data does not exist. When getting data corresponding to a XML attribute, this is always a string.

Example

This example stores the tick count when a player joins and then allows players to see how long they are connected using a console function 'joinTime'.

Click to collapse [-]

Server

function joinTime ( )
    setElementData ( source, "joinTime", getTickCount() ) -- Store the current tick count in the player's data with the key 'joinTime'
end
-- Make our 'joinTime' function be called when a player joins
addEventHandler ( "onPlayerJoin", root, joinTime )

function showJoinTime ( source, commandName, playerName )
	if ( playerName ) then -- see if a player was specified
		thePlayer = getPlayerFromName ( playerName ) -- get the player element for the specified player
		if ( thePlayer ) then -- if one was found...
			local timeOnline = (getTickCount() - getElementData ( thePlayer, "joinTime" )) / 1000 -- calculates the time since join
			outputChatBox ( getPlayerName ( thePlayer ).." joined "..timeOnline.." seconds ago", source ) -- output the player's join time
		else
			outputChatBox ( "Couldn't find '" .. playerName .. "'", source ) -- display an error
		end
	else
		-- display when the player who used the function joined and inform how to see other people's join time
		local timeOnline = (getTickCount() - getElementData ( source, "joinTime" )) / 1000 -- calculate the time since join
		outputChatBox ( "You joined " ..timeOnline.." seconds ago", source )
		outputChatBox ( "Use 'join_time <player name>' to see other people's join time", source )
	end
end
-- Add a console command joinTime, that takes an optional parameter of a player's name
addCommandHandler ( "joinTime", showJoinTime )

@@ Line 1: / Line 1: @@
 __NOTOC__
-Elements can contain data values. These are accessable via names, and their value can be retrieved using [[getElementData]] and set using [[setElementData]]. These values are also loaded from the attributes in the XML map files, and as such can provide a powerful way to store and retrieve data in XML for each element.
+{{Server client function}}
+This function retrieves [[element data]] attached to an element under a certain key.
 ==Syntax==
-<syntaxhighlight lang="lua">var getElementData ( element theElement, string key )</syntaxhighlight>
+<syntaxhighlight lang="lua">var getElementData ( element theElement, string key [, bool inherit = true] )</syntaxhighlight>
+{{OOP||[[element]]:getData||setElementData}}
 ===Required Arguments===
-*'''theElement:''' This is the element with data you want to retreive.
+*'''theElement:''' This is the element with data you want to retrieve.
-*'''key:''' The name of the element data entry you want to retrieve.
+*'''key:''' The name of the element data entry you want to retrieve. (Maximum 31 characters.)
+===Optional Arguments===
+*'''inherit:''' - toggles whether or not the function should go up the hierarchy to find the requested key in case the specified element doesn't have it.
 ===Returns===
-This function returns a ''variable'' containing the requested element data, or ''false'' if the element data does not exist, or the element itself does not exist. Usually this is a ''string'' but it doesn't have to be.
+This function returns a ''variable'' containing the requested element data, or ''false'' if the element or the element data does not exist. When getting data corresponding to a XML attribute, this is always a ''string''.
 ==Example==
-'''Example 1:''' This example stores the time a player joins and then allows players to see this using a console function 'join_time'.
+This example stores the tick count when a player joins and then allows players to see how long they are connected using a console function 'joinTime'.
+<section show="true" name="Server" class="server">
 <syntaxhighlight lang="lua">
--- Make our 'joinTime' function be called when a player joins
-addEventHandler ( "onPlayerJoin", getRootElement(), "joinTime" )
 function joinTime ( )
-     setElementData ( source, "joinTime", os.date() ) -- Store the current time in the player's data with the key 'joinTime'
+     setElementData ( source, "joinTime", getTickCount() ) -- Store the current tick count in the player's data with the key 'joinTime'
 end
+-- Make our 'joinTime' function be called when a player joins
+addEventHandler ( "onPlayerJoin", root, joinTime )
--- Add a console command join_time, that takes an optional parameter of a player's name
-addCommandHandler ( "join_time", "showJoinTime" )
 function showJoinTime ( source, commandName, playerName )
-    if ( playerName ) then -- see if a player was specified
+	if ( playerName ) then -- see if a player was specified
-        thePlayer = getPlayerFromNick ( playerName ) -- get the player element for the specified player
+		thePlayer = getPlayerFromName ( playerName ) -- get the player element for the specified player
-        if ( thePlayer ) then -- if one was found...
+		if ( thePlayer ) then -- if one was found...
-            outputChatBox ( getClientName ( thePlayer ) .. " joined " .. getElementData ( thePlayer, "joinTime" ), source ) -- output the player's join time
+			local timeOnline = (getTickCount() - getElementData ( thePlayer, "joinTime" )) / 1000 -- calculates the time since join
-        else
+			outputChatBox ( getPlayerName ( thePlayer ).." joined "..timeOnline.." seconds ago", source ) -- output the player's join time
-            outputChatBox ( "Couldn't find '" .. playerName .. "'", source ) -- display an error
+		else
-        end
+			outputChatBox ( "Couldn't find '" .. playerName .. "'", source ) -- display an error
-    else
+		end
-        -- display when the player who used the function joined and inform how to see other people's join time
+	else
-        outputChatBox ( "You joined " .. getElementData ( source, "joinTime" ), source )
+		-- display when the player who used the function joined and inform how to see other people's join time
-        outputChatBox ( "Use 'join_time <player name>' to see other people's join time" )
+		local timeOnline = (getTickCount() - getElementData ( source, "joinTime" )) / 1000 -- calculate the time since join
-    end
+		outputChatBox ( "You joined " ..timeOnline.." seconds ago", source )
+		outputChatBox ( "Use 'join_time <player name>' to see other people's join time", source )
+	end
 end
+-- Add a console command joinTime, that takes an optional parameter of a player's name
+addCommandHandler ( "joinTime", showJoinTime )
 </syntaxhighlight>
-'''Example 2:''' This example will store the version of the map in the variable ''mapVersion''. Generally this will be ''2.0'' in the final release.
+</section>
-<syntaxhighlight lang="lua">
-map = getRootElement ( )
-mapVersion = getElementData ( map, "version" )
-</syntaxhighlight>
 ==See Also==
 {{Element functions}}
+[[pt-br:getElementData]]