Xbasic

*property_from_xml Function

Syntax

C *PROPERTY_FROM_XML(xml as c,prop as p[, reversible as l])

Arguments

xmlCharacter

The XML to parse into a dot variable.

propPointer

A dot variable that will be populated with the parsed XML.

reversibleLogical

Default = .f. If .t., mapping information for the XML format will be included in the prop variable.

Description

Read property from XML, if reversible flag is set, the XML we generate will match (adds levels to handle scaling tags - i.e. adding runs of tags and mapping names).

Discussion

*property_from_xml() populates an Xbasic Dot Variable with XML Attribute/Element Values. Xbasic has always had very strong XML parsing features (see Parsing XML Documents with Xbasic), however the new *property_from_xml() function provides a new way in working with XML. This function populates an Xbasic dot variable with the data from the XML document. Once you have he Xbasic variable, it is very easy to extract a specific element or attribute value from the XML document.

Example 

dim xml as c = http_get_page2("http://feeds.gawker.com/lifehacker/full")
dim content as p
*property_from_xml(xml,content)
dim xmlvalue as c 
xmlvalue = content.rss.channel.item[17].title

'to get all of the titles, use the .dump_properties() method
dim allTitles as c 
allTitles = content.rss.channel.item.dump_properties("title")

Understanding __A5_elementContent and __A5_Xml_Manifest 

Some meta information is included when XML content is converted to a dot variable. This information is required in order to provide round-trip support (convert XML to a property array and then back to original XML format.) Consider the following very simple snippet of XML.

xml = <<%txt%
<name city-name="boston">
    Fred Smith
</name>
%txt%

If you view this XML using the XML viewer function (showXML()), you will see this:

showXML(xml)
images/parseXML1.jpg

You will notice that the XML has an attribute called 'city-name'. This is not a valid Xbasic variable name, so the attribute has to be renamed (to 'city_name'). In order that the *property_to_xml() function can get back to the same XML that was originally parsed, a list of all of the attribute names that were changed is kept in the special __A5_Xml_Manifest property.

images/parseXML2.jpg

Also, you will notice that in the XML snippet, the 'name' element has a value and also it has attributes. The attribute values are shown as properties and the element value is shown using the special property name '__A5_elementContent'.

Here is how you can parse the above XML into an Xbasic dot variable:

delete p
dim p as p

'set the optional 3rd flag to .t. to use the special properties
*property_from_xml(xml,p,.t.)

'convert the dot variable into a script so we can 'see' what's in the variable
?*variable_to_script(p)
= DIM name as P
DIM name.city_name as C = "boston"
DIM name.__A5_elementContent as C = <<%str%

Fred Smith
%str%
DIM __A5_Xml_Manifest as C = <<%str%
@Mapping:
city_name=city-name%str%

'now, go back to XML
?*property_to_xml(p,"")
= <name city-name = "boston" >
    Fred Smith
</name>

Notice how this is a perfect 'round-trip'! The generated XML is the same as the initial XML that was parsed. Now, try the above exercise without using the new optional flag on the *property_to_xml() function

delete p
dim p as p

*property_from_xml(xml,p,.f.)

'convert the dot variable into a script so we can 'see' what's in the variable

?*variable_to_script(p)
= DIM name as P
DIM name.city_name as C = "boston"

Notice how the Xbasic dot variable only has the value of the attribute. It does NOT have the value of the element!

Videos 

Working with XML Documents

The *property_from_xml() function and XML document viewer make it easy to work with XML documents. Watch the video below to learn how to use these features when working with XML documents using Xbasic.

See Also