Online Help
The XML plugin is an action plugin for use with Indigo Rose software products. It allows you to efficiently and effectively work with any valid XML (Extensible Markup Language) file.
We've made the XML plugin extremely powerful, yet remarkably easy to use. Using an innovative XML referencing scheme which we've named "XML Paths," this plugin makes reading, writing and manipulating XML files simple and straightforward.
If you need to work with XML data, this plugin is for you.
Many of the XML actions contain a parameter called XMLPath. This path is used to locate a specific element in the XML file. For example, in the sample XML document, the "address" element inside the first "customer" element can be accessed using:
database/customer/address_info/address
Since an XML document can contain multiple elements with the same name, you often cannot access every element in a document by name alone. For example, what if you need to access the information in the second customer element?
The secret is to add an optional index to each element name in order to specify which occurence of that name the path refers to. In XML paths, an index consists of a single colon (:) followed by a number. (If no index is specified, the index is assumed to be 1.)
For example, to access the second "customer" element in the first "database" element of the sample XML document, you could use:
database/customer:2
As another example, to access the second "phone" element in the second "customer" element, you would use:
database/customer:2/phone:2
An asterisk (*) can be used in an XML path to find the first matching element at a given level.
For example, you can use paths like this:
*/customer
...which refers to the first customer element in the first root element, no matter what the root element is named. In other words, the above path wouldn't care whether the root element was "database" or "moonbase_alpha."
You can use an asterisk with an index to refer to an element by position instead of by name. For example, you could use the following path to access the second element inside the customer element, no matter what that element is named:
database/customer/*:2
Using the above path, it wouldn't matter what the first two elements inside customer were named; they could be "first_name" and "last_name" or they could be "nose_length" and "hair_color"...either way, it would be the second element that would be referenced.
You can even form a path with nothing but asterisks. For example, the following path would refer to the third child element within the second root element:
*:2/*:3
Note: An asterisk always matches a single element. It doesn't match "all" elements at that level.
If you need to, you can change the index delimiter from ':' to something else by assigning a different value to the special Lua variable XML.Delimiter. For example, if your XML document has element names with ':' characters in them, you could change the delimiter to '|' instead by using this script:
XML.Delimiter = "|";
...after which you would specify paths like this:
database/customer|2/phone|2
Note: Most of the examples assume the following XML to be already loaded into memory. To test the examples you can save the text below as an .xml file and then use an XML.Load action to load it into memory.
<database> <customer id="1010" product="AutoPlay"> <first_name>John</first_name> <last_name>Smith</last_name> <company>Indigo Rose</company> <address_info> <address>100 Mystreet</address> <city>Winnipeg</city> <province>Manitoba</province> <country>Canada</country> <postal_code>R3B 0R3</postal_code> </address_info> <phone location="daytime">(204)946-0263</phone> <phone location="evening">(204)946-0242</phone> <fax>(204)942-3421</fax> <email>[email protected]</email> </customer> <customer id="1040" product="Setup Factory"> <first_name>Sara</first_name> <last_name>Winters</last_name> <company>Indigo Rose</company> <address_info> <address>200 Secondstreet</address> <city>Winnipeg</city> <province>Manitoba</province> <country>Canada</country> <postal_code>R3B 0R4</postal_code> </address_info> <phone location="daytime">(204)946-0244</phone> <phone location="evening">(204)946-0289</phone> <fax>(204)942-3422</fax> <email>[email protected]</email> </customer> </database>
XML.Count
XML.GetAttribute
XML.GetAttributeNames
XML.GetElementNames
XML.GetElementXML
XML.GetValue
XML.GetXML
XML.InsertXML
XML.Load
XML.RemoveAttribute
XML.RemoveElement
XML.Save
XML.SetAttribute
XML.SetValue
XML.SetXML
Counts the number of elements below a given XML path that match a given element name.
(string) The path to the element whose children you want to count.
(string) The element name (tag name) that you want to search for. Only elements that match will be counted. Use * to match any name.
(number) The number of matching child elements found. If an error occurs, -1 is returned.
-- This example assumes the sample XML is already loaded into memory. -- Count the total number of elements in "database". count = XML.Count("database", "*"); -- Display the count in a dialog message if no errors occurred. if (count ~= -1) then Dialog.Message("Count", "There are "..count.." elements in the database."); end
-- This example assumes the sample XML is already loaded into memory. -- Count the number of "phone" elements in the first customer element. count = XML.Count("database/customer", "phone"); -- Display the count in a dialog message if no errors occurred. if (count ~= -1) then Dialog.Message("Count", "There are "..count.." phone elements in the first customer element."); end
Returns the value of an element's attribute.
(string) The path to the element whose attribute you want to retrieve.
(string) The name of the attribute.
(string) The value of the specified element's attribute. If an element has no attribute or an error occurs, an empty string ("") is returned.
-- This example assumes the sample XML is already loaded into memory. -- Get the value of the first customer id attribute. attribute_result = XML.GetAttribute("database/customer", "id"); -- Perform some error checking. error = Application.GetLastError(); if (error == 0) then Dialog.Message("Attribute Value", "The first customer id is: "..attribute_result); else Dialog.Message("Error", _tblErrorMessages[error]); end
-- This example assumes the sample XML is already loaded into memory. -- Get the value of the second customer product attribute. attribute_result = XML.GetAttribute("database/customer:2", "product"); -- Perform some error checking. error = Application.GetLastError(); if (error == 0) then Dialog.Message("Attribute Value", "The second customer's product is: "..attribute_result); else Dialog.Message("Error", _tblErrorMessages[error]); end
Returns the names of an element's attributes in a numerically indexed table.
(string) The path to the element whose attribute names you want to retrieve.
(table) A numerically indexed table containing the names of the specified element's attributes. If the element doesn't contain any attributes or an error occurs, nil is returned.
-- This example assumes the sample XML is already loaded into memory. -- Return the names of the customer element's attributes. customer_attributes = XML.GetAttributeNames("database/customer"); -- Perform some error checking. error = Application.GetLastError(); if (error == 0) then Dialog.Message("Element Attributes", "The two attribute names are: \r\n\r\n"..customer_attributes[1].."\r\n"..customer_attributes[2]); else Dialog.Message("Error", _tblErrorMessages[error]); end
Returns a numerically indexed table containing the names of all child elements contained within a specific element.
(string) The path to the element whose child elements you want to find.
(boolean) Whether to return the full paths of the child elements, or just the element names:
true - Return the full paths of the child elements.
false - Return just the element names. (Default)
(table) A numerically indexed table containing the names of all child elements contained within the specified element. If there are no child elements or an error occurs, nil is returned.
-- This example assumes the sample XML is already loaded into memory. -- Return the names of all of the child elements of address_info. tbChild_elements = XML.GetElementNames("database/customer/address_info", false); -- Perform some error checking. error = Application.GetLastError(); -- If no errors occurred... if (error == 0) then if (tbChild_elements ~= nil) then -- Convert the table to a return/newline delimited string to display in a dialog. strChild_elements = Table.Concat(tbChild_elements, "\r\n", 1, TABLE_ALL); -- Display a dialog message containing all child names. Dialog.Message("Child Element Names", strChild_elements); end else Dialog.Message("Error", _tblErrorMessages[error]); end
Returns the raw XML of an element, i.e. the plain-text XML code for the element and all of its children.
(string) The path to the element whose XML you want to retrieve.
(string) The XML code for the entire element and all of its children. If the element doesn't exist, or an error occurs, an empty string ("") is returned.
-- This example assumes the sample XML is already loaded into memory. -- get the raw XML text of the 2nd customer element strCustomerXML = XML.GetElementXML("database/customer:2"); error = Application.GetLastError(); if (error ~= XML.OK) then Dialog.Message("Error", _tblErrorMessages[error]); end -- get the customer's name from the XML strCustomerName = XML.GetValue("database/customer:2/first_name") .. XML.GetValue("database/customer:2/last_name"); -- save the customer record as a separate XML document in C:\customer_records TextFile.WriteFromString( "C:\\customer_records\\"..strCustomerName..".xml" , strCustomerXML , false );
Returns the value of an element.
(string) The path to the element whose value you want to retrieve.
(string) The value of the specified element. If the element contains no value, or an error occurs, an empty string ("") is returned.
-- This example assumes the sample XML is already loaded into memory. -- Gets the value in database/customer/first_name. customer_name = XML.GetValue("database/customer/first_name"); -- If a value was returned, display it in a dialog message. if (customer_name ~= "") then Dialog.Message("Value","The customer's first name is "..customer_name); else Dialog.Message("Problem", "The customer name could not be located."); end
-- This example assumes the sample XML is already loaded into memory. -- Gets the second customer's second phone number. customer_phone = XML.GetValue("database/customer:2/phone:2"); -- If a value was returned, display it in a dialog message. if (customer_phone ~= "") then Dialog.Message("Value","The customer's second phone number is "..customer_phone); else Dialog.Message("Problem", "The telephone number could not be located."); end
Returns the currently loaded XML document as a string.
(string) A string containing the currently loaded XML document. If no document is loaded or an error occurs, an empty string ("") is returned.
-- Load an XML file into memory. XML.Load("AutoPlay\\Docs\\Sample2.xml"); -- Check if an error was returned. error = Application.GetLastError(); -- If no errors occurred... if (error == 0) then -- Return the currently loaded XML in a string. strXML = XML.GetXML(); -- See if any errors occurred. If no errors occurred, display the string. error = Application.GetLastError(); if (error == 0) then Dialog.Message("XML contents",strXML); else Dialog.Message("Error", _tblErrorMessages[error]); end else Dialog.Message("Error", _tblErrorMessages[error]); end
Inserts raw XML code into a specific location in the currently loaded document.
(string) The path to the element where you want to insert the XML text. You can insert the XML before this element, insert it after this element, or replace the element (and all its children) with the new XML text.
(string) The XML text that you want to insert.
(number) The insertion mode to use:
XML.INSERT_BEFORE (0) - Insert the new XML text before the specified element.
XML.INSERT_AFTER (1) - Insert the new XML text after the specified element.
XML.REPLACE (2) - Replace the specified element's XML text with the new XML text.
Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.
-- This example assumes the sample XML is already loaded into memory. -- we'll use the debug window to show what's happening Debug.ShowWindow(true); -- get the raw XML for the first customer's address_info and display it in the debug window strAddress = XML.GetElementXML("database/customer/address_info"); Debug.Print(strAddress.."\r\n\r\n"); -- insert a planet element right after the country element Debug.Print("Inserting planet...\r\n"); XML.InsertXML("database/customer/address_info/country", "<planet>Earth</planet>", XML.INSERT_AFTER); -- check for errors error = Application.GetLastError(); -- If an error occurred, display the error message. if (error == 0) then Debug.Print("Planet inserted.\r\n\r\n"); else Debug.Print("Error: ".. _tblErrorMessages[error] .. "\r\n"); end -- get the raw XML again and display it in the debug window to show what has changed strAddress = XML.GetElementXML("database/customer/address_info"); Debug.Print(strAddress.."\r\n\r\n");
Loads an XML file into memory so it can be processed.
(string) The path to the XML file.
Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.
-- Load an XML file into memory. XML.Load("AutoPlay\\Docs\\Sample2.xml"); -- Check whether an error occurred error = Application.GetLastError(); -- If no errors occurred... if (error == XML.OK) then -- get the current XML document as a string strXML = XML.GetXML(); -- if no errors occurred, display the XML in a popup dialog error = Application.GetLastError(); if (error == XML.OK) then Dialog.Message("XML contents",strXML); else Dialog.Message("Error", _tblErrorMessages[error]); end else Dialog.Message("Error", _tblErrorMessages[error]); end
Removes a specific attribute from an element.
(string) The path to the element whose attribute you want to remove.
(string) The name of the attribute you want to remove.
Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.
-- This example assumes the sample XML is already loaded into memory. -- Return the currently loaded XML in a string. strXML = XML.GetXML(); if (strXML ~= "") then Dialog.Message("Original XML contents",strXML); end -- Removes the "product" attribute from the first customer. XML.RemoveAttribute("database/customer", "product"); -- See if any errors occurred. If no errors occurred, display the string. error = Application.GetLastError(); if (error == 0) then -- Return the currently loaded(modified) XML in a string. strXML = XML.GetXML(); if (strXML ~= "") then Dialog.Message("Modified XML contents",strXML); end else Dialog.Message("Error", _tblErrorMessages[error]); end
Removes a specific element (and its children) from the currently loaded XML document.
(string) The path to the element you want to remove.
Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.
-- This example assumes the sample XML is already loaded into memory. -- Return the currently loaded XML in a string. strXML = XML.GetXML(); if (strXML ~= "") then Dialog.Message("Original XML contents",strXML); end -- Removes the address info element from the first customer entry. XML.RemoveElement("database/customer/address_info"); -- See if any errors occurred. If no errors occurred, display the string. error = Application.GetLastError(); if (error == 0) then -- Return the currently loaded (modified) XML in a string. strXML = XML.GetXML(); if (strXML ~= "") then Dialog.Message("Modified XML contents",strXML); end else Dialog.Message("Error", _tblErrorMessages[error]); end
Saves the currently loaded XML document to a file.
(string) The full path for the XML file.
Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.
-- This example assumes the sample XML is already loaded into memory. -- Saves the currently loaded XML to a file in the user's temp folder. XML.Save(_TempFolder.."\\Sample_XML_Save.xml"); -- Check to see if any errors occurred. error = Application.GetLastError(); if (error ~= 0) then Dialog.Message("Error", _tblErrorMessages[error]); end
Sets the value of an element's attribute.
(string) The path to the element whose attribute you want to set.
(string) The name of the attribute you want to set.
(string) The value you want the attribute to have.
Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.
-- This example assumes the sample XML is already loaded into memory. -- Return the currently loaded XML in a string. strXML = XML.GetXML(); if (strXML ~= "") then Dialog.Message("Original XML contents",strXML); end -- Changes the second customer element's attribute id to "9999". XML.SetAttribute("database/customer:2", "id", "new id"); -- See if any errors occurred. If no errors occurred, display the string. error = Application.GetLastError(); if (error == 0) then -- Return the currently loaded (modified) XML in a string. strXML = XML.GetXML(); if (strXML ~= "") then Dialog.Message("Modified XML contents",strXML); end else Dialog.Message("Error", _tblErrorMessages[error]); end
Sets the value of an element.
(string) The path to the element whose value you want to set.
(string) The value you want the element to have.
Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.
-- This example assumes the sample XML is already loaded into memory. -- Return the currently loaded XML in a string. strXML = XML.GetXML(); if (strXML ~= "") then Dialog.Message("Original XML contents",strXML); end -- Sets the first customer element's company name to "New Company Name". XML.SetValue("database/customer/company", "New Company Name"); -- See if any errors occurred. If no errors occurred, display the string. error = Application.GetLastError(); if (error == 0) then -- Return the currently loaded (modified) XML in a string. strXML = XML.GetXML(); if (strXML ~= "") then Dialog.Message("Modified XML contents",strXML); end else Dialog.Message("Error", _tblErrorMessages[error]); end
Loads an XML document into memory from a string.
(string) The XML document. This will replace the contents of the currently loaded XML document.
Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.
-- Loads an XML document from a string XML.SetXML(""); -- Check if any errors occurred setting the XML. error = Application.GetLastError(); if (error == 0) then -- Return the currently loaded XML in a string. strXML = XML.GetXML(); -- Display the XML contents in a dialog. if (strXML ~= "") then Dialog.Message("XML contents",strXML); end else Dialog.Message("Error", _tblErrorMessages[error]); end MyValue1 MyValue2
0 | (XML.OK) | - | (no error) |
---|---|---|---|
37000 | (XML.ERR_LOAD_FAILED) | - | Error loading XML file. |
37001 | (XML.ERR_SAVE_FAILED) | - | Error saving XML file. |
37002 | (XML.ERR_NOT_WELL_FORMED) | - | No valid XML document loaded. (The document is empty or not well formed.) |
37003 | (XML.ERR_INVALID_PATH) | - | The specified XML path is not valid or was not found. |
37004 | (XML.ERR_SET_VALUE_FAILED) | - | An error occurred while trying to set the value. |
37005 | (XML.ERR_SET_ATTRIBUTE_FAILED) | - | An error occurred while trying to set the attribute. |
37006 | (XML.ERR_INVALID_ATTRIBUTE_NAME) | - | Invalid attribute name. (Attribute names cannot contain spaces.) |
37007 | (XML.ERR_REMOVE_ELEMENT_FAILED) | - | The specified element could not be removed. |
37008 | (XML.ERR_REMOVE_ATTRIBUTE_FAILED) | - | The specified attribute could not be removed. |
37009 | (XML.ERR_NO_ELEMENTS) | - | There are no elements below the specified XML path. |
37010 | (XML.ERR_NO_ATTRIBUTES) | - | The element at the specified XML path does not have any attributes. |
37011 | (XML.ERR_INSERT_FAILED) | - | An error occurred while trying to insert XML. |
37012 | (XML.ERR_INVALID_INSERTION_MODE) | - | Invalid insertion mode. |
Indigo Rose Corporation
support.indigorose.com
The XML Actions Plugin is copyright © 2003-2004 Indigo Rose Software Design Corporation.
Copyright © 2003-2004 Indigo Rose Software Design Corporation.
All Rights Reserved.