XML Actions Plugin 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.

XML Paths

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:

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:

As another example, to access the second "phone" element in the second "customer" element, you would use:

Matching Any Element Name

An asterisk (*) can be used in an XML path to find the first matching element at a given level.

...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:

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:

Note: An asterisk always matches a single element. It doesn't match "all" elements at that level.

Using a Different Index Delimiter

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:

Sample XML

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.

Actions

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

number XML.Count (string XMLPath, string ElementName);

Description:

Counts the number of elements below a given XML path that match a given element name.

XMLPath:

(string) The path to the element whose children you want to count.

ElementName:

(string) The element name (tag name) that you want to search for. Only elements that match will be counted. Use * to match any name.

Returns:

(number) The number of matching child elements found. If an error occurs, -1 is returned.

Example 1:

-- 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

Example 2:

-- 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

string XML.GetAttribute (string XMLPath, string AttributeName);

Description:

Returns the value of an element's attribute.

XMLPath:

(string) The path to the element whose attribute you want to retrieve.

AttributeName:

(string) The name of the attribute.

Returns:

(string) The value of the specified element's attribute. If an element has no attribute or an error occurs, an empty string ("") is returned.

Example 1:

-- 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

Example 2:

-- 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

table XML.GetAttributeNames (string XMLPath);

Description:

Returns the names of an element's attributes in a numerically indexed table.

XMLPath:

(string) The path to the element whose attribute names you want to retrieve.

Returns:

(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.

Example:

-- 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

table XML.GetElementNames (string XMLPath, boolean FullPaths = false);

Description:

Returns a numerically indexed table containing the names of all child elements contained within a specific element.

XMLPath:

(string) The path to the element whose child elements you want to find.

FullPaths:

(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)

Returns:

(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.

Example:

-- 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

string XML.GetElementXML (string XMLPath);

Description:

Returns the raw XML of an element, i.e. the plain-text XML code for the element and all of its children.

XMLPath:

(string) The path to the element whose XML you want to retrieve.

Returns:

(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.

Example:

-- 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 );

string XML.GetValue (string XMLPath);

Description:

Returns the value of an element.

XMLPath:

(string) The path to the element whose value you want to retrieve.

Returns:

(string) The value of the specified element. If the element contains no value, or an error occurs, an empty string ("") is returned.

Example 1:

-- 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

Example 2:

-- 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

string XML.GetXML ();

Description:

Returns the currently loaded XML document as a string.

Returns:

(string) A string containing the currently loaded XML document. If no document is loaded or an error occurs, an empty string ("") is returned.

Example:

-- 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

XML.InsertXML (string XMLPath, string Text, number InsertionMode);

Description:

Inserts raw XML code into a specific location in the currently loaded document.

XMLPath:

(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.

Text:

(string) The XML text that you want to insert.

InsertionMode:

(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.

Returns:

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- 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");

XML.Load (string Filename);

Description:

Loads an XML file into memory so it can be processed.

Filename:

(string) The path to the XML file.

Returns:

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- 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

XML.RemoveAttribute (string XMLPath, string AttributeName);

Description:

Removes a specific attribute from an element.

XMLPath:

(string) The path to the element whose attribute you want to remove.

AttributeName:

(string) The name of the attribute you want to remove.

Returns:

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- 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

XML.RemoveElement (string XMLPath);

Description:

Removes a specific element (and its children) from the currently loaded XML document.

XMLPath:

(string) The path to the element you want to remove.

Returns:

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- 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

XML.Save (string Filename);

Description:

Saves the currently loaded XML document to a file.

Filename:

(string) The full path for the XML file.

Returns:

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- 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

XML.SetAttribute (string XMLPath, string AttributeName, string AttributeValue);

Description:

Sets the value of an element's attribute.

XMLPath:

(string) The path to the element whose attribute you want to set.

AttributeName:

(string) The name of the attribute you want to set.

AttributeValue:

(string) The value you want the attribute to have.

Returns:

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- 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

XML.SetValue (string XMLPath, string Value);

Description:

Sets the value of an element.

XMLPath:

(string) The path to the element whose value you want to set.

Value:

(string) The value you want the element to have.

Returns:

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- 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

XML.SetXML (string Text);

Description:

Loads an XML document into memory from a string.

Text:

(string) The XML document. This will replace the contents of the currently loaded XML document.

Returns:

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- Loads an XML document from a string
XML.SetXML("MyValue1MyValue2");

-- 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

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.

XML Actions Plugin

Description

XML Paths

Matching Any Element Name

Using a Different Index Delimiter

Actions

Description:

XMLPath:

ElementName:

Returns:

Example 1:

Example 2:

Description:

XMLPath:

AttributeName:

Returns:

Example 1:

Example 2:

Description:

XMLPath:

Returns:

Example:

Description:

XMLPath:

FullPaths:

Returns:

Example:

Description:

XMLPath:

Returns:

Example:

Description:

XMLPath:

Returns:

Example 1:

Example 2:

Description:

Returns:

Example:

Description:

XMLPath:

Text:

InsertionMode:

Returns:

Example:

Description:

Filename:

Returns:

Example:

Description:

XMLPath:

AttributeName:

Returns:

Example:

Description:

XMLPath:

Returns:

Example:

Description:

Filename:

Returns:

Example:

Description:

XMLPath:

AttributeName:

AttributeValue:

Returns:

Example:

Description:

XMLPath:

Value:

Returns:

Example:

Description:

Text:

Returns:

Example:

Error Codes

Change Log

1.0.0.2