From Blue Mars Developer Guidebook

This page is protected and certified by Avatar Reality Inc. Only Editable by Avatar Reality Staff Members.

Return to XMLtoLua

Contents 1 Function 2 Usage 2.1 Notes 2.2 Example 2.3 Definition Files 2.4 Troubleshooting

Function

ARLoadXML(definitionFile, dataFile)

return value - a table representing the contents of an XML file, null if the file is not loaded

definitionFile - string XML file that specifies how the conversion is performed

dataFile - string XML file that is loaded and converted to Lua. The file is located under the Blue Mars user folder.

Usage

Notes

Use ARDownloadFile to download and save the dataFile to the user directory (if parsing XML is not required, see the alternate ARWebUtils.DownloadFile function, which returns data in a callback function).

Use ARSaveXML to convert a Lua table to an XML file.

Example

• See the High Score Server example
• See ARGolfStatsDisplay which uses ARLoadXML to display recent golf games in the clubhouse, via Flash Material.

self.xmltable = ARLoadXML(self.Properties.recentgamesdef,self.Properties.xmlresults)

Definition Files

A definition file is also an XML file. It instructs ARLoadXML what nodes and attributes to expect in the XML file it's reading and how to convert values to Lua.

The definition file always starts with the definition of the root node tag in the XML data file, with a list of the properties (XML tag attributes) expected for that tag. After that, the subnodes of the root node can each be a Table or Array, each with an optional set of Property specifications that correspond to tag attributes. Array is like Table but with an expected number of subnodes each using the tag specified in the Array elementName attribute.

Each property specifies the property name and Lua type it should be converted to: int, float, string or an enum. A leaf-node (i.e. containing no child nodes) with content (the data between the tag begin and end) can also be interpreted as a Property.

Here is a sample definition file used in the High Score Server example.

<?xml version="1.0"?>

<Definition root="golf_player">

    <Property name="id" type="int" />
    <Property name="name" type="string" />
    <Property name="handicap" type="int" />
  
  <Array name="sections" elementName="section">
	<Property name="id" type="string"/>
	<Property name="course" type="string"/>
	<Property name="limit" type="int"/>
	<Property name="total" type="int"/>
	<Property name="name" type="string"/>
	<Property name="average" type="string"/>
	<Array name="scores" elementName="score">
	<Property name="score" type="int"/>
	<Property name="date" type="string"/>
	</Array>
	<Array name="holes" elementName="hole">
	<Property name="number" type="int"/>
	<Property name="limit" type="int"/>
	<Property name="total" type="int"/>
	<Property name="average" type="string"/>
	<Array name="scores" elementName="score">
	<Property name="score" type="int"/>
	<Property name="date" type="string"/>
	</Array>
	</Array>
  </Array>
</Definition>

And a sample XML file that the definition file can process.

<golf_player id="1" name="ted" handicap="0">
<sections>
<section id="1" name="section1" course="course1" limit="3" average="" total="0">
<scores>
</scores>
<holes>
<hole number="1" limit="3" average="" total="0">
<scores>
</scores>
</hole>
</holes>
</section>
<section id="2" name="section2" course="course2" limit="3" average="4.0000" total="2">
<scores>
<score score="4" date="2009-09-17 20:33:03"/>
<score score="4" date="2009-09-17 20:33:17"/>
</scores>

<holes>
<hole number="1" limit="3" average="25.0000" total="8">
<scores>
<score score="25" date="2009-09-17 19:13:25"/>
<score score="25" date="2009-09-17 19:32:11"/>
<score score="25" date="2009-09-17 19:36:33"/>
</scores>
</hole>
<hole number="2" limit="3" average="" total="0">
<scores>
</scores>
</hole>
<hole number="3" limit="3" average="" total="0">
<scores>
</scores>
</hole>
</holes>

</section>
<section id="3" name="section3" course="course3" limit="3" average="" total="0">
<scores>
</scores>
<holes>
<hole number="1" limit="3" average="" total="0">
<scores>
</scores>
</hole>
<hole number="2" limit="3" average="" total="0">
<scores>
</scores>
</hole>
<hole number="3" limit="3" average="" total="0">
<scores>
</scores>
</hole>

<hole number="4" limit="3" average="" total="0">
<scores>
</scores>
</hole>
<hole number="5" limit="3" average="" total="0">
<scores>
</scores>
</hole>
<hole number="6" limit="3" average="" total="0">
<scores>
</scores>
</hole>
<hole number="7" limit="3" average="" total="0">
<scores>
</scores>
</hole>
<hole number="8" limit="3" average="" total="0">

<scores>
</scores>
</hole>
<hole number="9" limit="3" average="" total="0">
<scores>
</scores>
</hole>
</holes>
</section>
</sections>
</golf_player>

Troubleshooting

• Check the return value - if it's null instead of a table, then XML file was not successfully read and converted
• Check the - any mismatch between the definition file and the XML file will be reported