XmlNodeGetChildren: Difference between revisions

Revision as of 11:41, 6 April 2008

This function returns all children of a particular XML node, or a particular child node.

Syntax

table/xmlnode xmlNodeGetChildren ( xmlnode parent, [ int index ] )

Required Arguments

parent: This is the xmlnode you want to retrieve one or all child nodes of.

Optional Arguments

index: If you only want to retrieve one particular child node, specify its (0-based) index here. For example if you only want the first node, specify 0; the fifth node has index 4, etc.

Returns

If index isn't specified, returns a table containing all child nodes. If index is specified, returns the corresponding child node if it exists. Returns false in case of failure.

Example

Click to collapse [-]

Server

Suppose you have an .xml file with random welcome messages:

<messages>
    <message>Welcome to the deathmatch server, enjoy your stay.</message>
    <message>Welcome. Be sure to get your free pizza at Matt's!</message>
    <message>Party going on at the LS beach, be there</message>
</messages>

To retrieve a random message and display it whenever a player joins, you could use the following code:

addEventHandler("onResourceStart", getResourceRootElement(getThisResource()),
    function()
        local xml = xmlLoadFile("welcome.xml")             -- open the XML file
        g_WelcomeMessages = xmlNodeGetChildren(xml)        -- get all child nodes of the root node (<messages>) and put them in a global variable
        xmlUnloadFile(xml)                                 -- close the XML file
    end
)

addEventHandler("onPlayerJoin", getRootElement(),
    function()
        local numMessages = #g_WelcomeMessages                        -- get the number of messages
        local message = g_WelcomeMessages[math.random(numMessages)]   -- pick a random message
        outputChatBox(message, source, 0, 255, 0)                     -- display it to the joining player
    end
)

@@ Line 1: / Line 1: @@
 __NOTOC__
 {{Server client function}}
-This function returns a single child or all the children of a particular XML node.
+This function returns all children of a particular XML node, or a particular child node.
 ==Syntax==
-<syntaxhighlight lang="lua">xmlnode/table xmlNodeGetChildren( xmlnode parent, [ int index ])</syntaxhighlight>
+<syntaxhighlight lang="lua">table/xmlnode xmlNodeGetChildren ( xmlnode parent, [ int index ] )</syntaxhighlight>
 ===Required Arguments===
-* '''parent''': This is an [[xmlnode]] that you want to find the children under.
+* '''parent:''' This is the [[xmlnode]] you want to retrieve one or all child nodes of.
 ===Optional Arguments===
-{{OptionalArg}}
+* '''index:''' If you only want to retrieve one particular child node, specify its (0-based) index here. For example if you only want the first node, specify 0; the fifth node has index 4, etc.
-* '''index''': This is the index of the node you wish to find. For example, to find the 5th subnode, you would use 4 as the index value. To find the first occurence, use 0. If this is not set, it will return a list of all children.
 ===Returns===
-If index isn't specified, it returns a list of all children. Returns an [[xmlnode]] object if index was set and a node was found, otherwise it returns false.
+If '''index''' isn't specified, returns a table containing all child nodes. If '''index''' is specified, returns the corresponding child node if it exists. Returns ''false'' in case of failure.
 ==Example==
 <section name="Server" class="server" show="true">
-If you wanted to find the 'instructions' node in a map file like this:
+Suppose you have an .xml file with random welcome messages:
 <syntaxhighlight lang="xml">
-<map version="2.0">
+<messages>
-      <options>
+    <message>Welcome to the deathmatch server, enjoy your stay.</message>
-            <instructions>Start at the begining and keep going until the end!</instructions>
+    <message>Welcome. Be sure to get your free pizza at Matt's!</message>
-      </options>
+    <message>Party going on at the LS beach, be there</message>
-</map>
+</messages>
 </syntaxhighlight>
-You could use the following code:
+To retrieve a random message and display it whenever a player joins, you could use the following code:
 <syntaxhighlight lang="lua">
-maproot = getLoadedMapXMLRoot ();
+addEventHandler("onResourceStart", getResourceRootElement(getThisResource()),
-optionsnode = xmlNodeGetChildren( maproot, 0 ); -- In this case it would find the options sub node as the first under the 'map' node
+    function()
+        local xml = xmlLoadFile("welcome.xml")             -- open the XML file
+        g_WelcomeMessages = xmlNodeGetChildren(xml)        -- get all child nodes of the root node (<messages>) and put them in a global variable
+        xmlUnloadFile(xml)                                 -- close the XML file
+    end
+)
+addEventHandler("onPlayerJoin", getRootElement(),
+    function()
+        local numMessages = #g_WelcomeMessages                        -- get the number of messages
+        local message = g_WelcomeMessages[math.random(numMessages)]   -- pick a random message
+        outputChatBox(message, source, 0, 255, 0)                     -- display it to the joining player
+    end
+)
 </syntaxhighlight>
 </section>
 ==See Also==
 {{XML functions}}