XML Actions Plugin

 Online Help

Description

The XML Plugin allows you to efficiently and effectively work with any valid XML (Extensible Markup Language) file, directly from AutoPlay Media Studio 5.0. Reading, writing, and manipulating XML files has never been easier!

Whether you need to import a simple XML file containing project data, or continuously save your project settings into an XML file, this plugin is for you! We've made the XML Plugin extremely powerful, yet remarkably easy to use.

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:

database/customer/address_info/address

Since an XML document can contain multiple elements with the same name, you cannot access every element in a document by name alone. For example, what if you need to access the second customer's information?

The secret is to add an optional index to each element name that specifies which occurence of that element 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

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.

<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>sales@indigorose.com</email>
     </customer>
     <customer id="1040" product="AutoPlay">
          <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>sales@indigorose.com</email>
     </customer>
</database>

Actions

XML.Count
XML.GetAttribute
XML.GetAttributeNames
XML.GetElementNames
XML.GetValue
XML.GetXML
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 id attribute.
attribute_result = XML.GetAttribute("database/customer:2", "id");

-- Perform some error checking.
error = Application.GetLastError();
if (error == 0) then
    Dialog.Message("Attribute Value", "The second customer id 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.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 first name of the first customer 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 second customer's second phone number is "..customer_phone);
else
    Dialog.Message("Problem", "The telephone number could not be located for the second customer.");
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.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 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.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

Error Codes

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.

Additional Information

Author:

Indigo Rose Corporation
support@indigorose.com

Copyright:

The XML Actions Plugin is copyright © 2003 Indigo Rose Software Design Corporation.

Website:

http://www.indigorose.com

Copyright © 2003 Indigo Rose Software Design Corporation.
All Rights Reserved.