Page 1 of 1

basic XML

Posted: Mon Sep 02, 2019 3:32 am
by relanat
Let's run through some XML jargon. Elements, tags, attributes, subelements and text.
What is an XML element? For modders it is anything inside '<' and '>'.
There are two different ways to enclose an XML element.
As in the "Image" XML below which starts with '<Image...' and ends with '.../>'.
Or as in "StaticData", starting with '<StaticData>' and ending with '</StaticData>'.
Note that both use '/' to close the XML just in a different way.
Without this a 'close tag does not match open' error will occur.
Elements can also be inside other elements. They are then called subelements of the outer element.

Here's the code for the small armor patch from UsefulItems.xml in Transcendence_Source 1.8.3.

Code: Select all

<ItemType UNID="&itSmallArmorPatch;"
		inherit=		"&baStdArmorRepair;"
		name=		"small armor patch(es)"
		level=			"1"
		value=		"28"
		mass=		"1000"
		frequency=		"common"
		attributes=		"ArmorRepair; Consumable"

		description=		"This is a small armor plate that can be welded to your ship's armor to repair damage."

		useScreen=		"&dsRPGUseItemOnArmor;"

		sortName=		"armor patch, small"

	<Image imageID="&rsItems1;" imageX="288" imageY="576" imageWidth="96" imageHeight="96"/>
		<Data id="RepairHP">35</Data>
There are 4 XML elements here.
The main UNID is an element with the tag of "ItemType", 12 attributes and 2 subelements, "Image" and "StaticData".

The "Image" element has a tag of "Image", 5 attributes and no subelements.

The "StaticData" element has a tag of "StaticData", no attributes and one subelement, "Data".

The "Data" element has a tag of "Data", one attribute called 'id' and text. The text is "35".

The use of an XML editing program like NotePad++, Sublime Text or jEdit makes this much clearer because they will highlight an element.

First type this code into the debug console:

Code: Select all

(setq theTypeXML (typGetXML (unvEntity "itSmallArmorPatch")))
Press 'Enter' and all the armor patch code as seen above will show (but not in quite the same format or order). This is the "ItemType" element and we have saved it as 'theTypeXML'.

By using 'xmlGetAttribList' we can get a list of all 12 attributes of this "ItemType" element. Attributes are all of the code with '=' at the end. In this example they include 'name=', 'value=' etc. Note the '>' after the 'sortName' line of code. This ends the attributes for this element. Anything after this will be a subelelement.
In all these code examples type in the top line of code and press 'Enter' and the second line will appear.

Code: Select all

(xmlGetAttribList theTypeXML)
(name value unid attributes inherit level sortName mass frequency numberAppearing description useScreen)
To get the value of the attribute we use the attribute name.

Code: Select all

(xmlGetAttrib theTypeXML "frequency")
We can also get a list of the 2 subelements of the "ItemType" element.

Code: Select all

(xmlGetSubElementList theTypeXML)
("<Image imageID=\"0x0000F11D\" imageX=\"288\" imageY=\"576\" imageWidth=\"96\" imageHeight=\"96\"/>" "<StaticData>\x0d\n\x09\x09\x09<Data id=\"RepairHP\">35</Data>\x0d\n\x09\x09</StaticData>")
It can be difficult to see but there are two subelements shown here, "Image" and "StaticData".
Note that the "Data" element isn't listed here (although it is shown in the "StaticData" element). That is because it isn't a subelement of the "ItemType" element. It is actually a subelement of the "StaticData" element.
So to get to the "Data" element we use this code:

Code: Select all

(xmlGetSubElement (xmlGetSubElement theTypeXML "StaticData") "Data")
"<Data id=\"RepairHP\">35</Data>"
To go even deeper into the code and get the 'text' of the "Data" element, which in this example is "35", we use this code:

Code: Select all

(xmlGetText (xmlGetSubElement (xmlGetSubElement theTypeXML "StaticData") "Data") 0)
It is just a matter of following the matching '<' and '>'. Anything directly inside of another element is a subelement. Just keep getting subelements until you get to the code that you want.
If you aren't sure use 'xmlGetSubElementList' to check which element is next in line and then use 'xmlGetSubElement' with that 'tag'.
In this example we used the whole UNID XML, theTypeXML, and got the subelement "StaticData". Then we got the subelement "Data" from that. From there we could get the 'text' of the "Data" element, 35.