SWXml – XML API for SWX


Overview | Examples | Documentation

1. About SWXml

At first, what is SWX?

SWX is a native data format for Flash. It is a subset of the SWF format. SWX SWFs are regular SWF files that are used to store just data. You can find more information here: SWX documentation

What is SWXml?

SWXml is an API for SWX. It provides flash developers with a very easy way to create applications using the popular XML format (e.g. RSS Feeds, Atom, Media RSS, ...). In short, SWXml is a generic XML parser for SWX.

What does SWXxml exactly do?

SWXml parses an XML file and returns an array containing all the information. So you don't need to write ActionScript Code for parsing, you can just use the data of the XML file in a native way!

SWXml uses the SWX PHP, which is a SWX RPC (=remote procedure call protocol) implementation in PHP.

Does SWXml support XML attributes and namespaces?

Yes, it does. Attributes and namespaces are supported. The parser returns automatically all XML tags including elements with namespaces.


2. Requirements

Do I need SWX?

You have different possibilities:

Which PHP version do I need?

The SWXml API is compatible with PHP 4 and PHP 5.

Which Flash version do I need?

SWX and SWXml can be used with Flash 6 oder higher. Aral Balkan writes:

"SWX PHP, the current SWX RPC implementation that I'm working on, creates SWX files that are compatible with Flash 6+, Flash Lite 2.0 and Flash Lite 2.1. Currently, SWX PHP does not support Flash 9/AVM2 but it will eventually do so."


3. Installation of SWXml

SWXml class file

In combination with the public gateway on swxformat.org , there is no need of an installation.

If you want to use SWXml on your own server, you need a working SWX installation. Just copy the class file (_installation/SWXml.php) to the following folder:

That's it. SWXml is now available as service class.


4. How to use SWXml

Note: If you haven't worked with SWX yet, please start with the tutorials on swxformat.org.

SWX Request

Calling SWXml

Let's take a look at particular code lines of some of the examples, to show you how SWXml works. It is really easy.

For calling SWXml with the ActionScript API, there are basically three things you have to configure:

Let's look at the following example:

		var callDetails:Object = 
			{
				serviceClass: "SWXml",
				method: "parseXML",
				args: ["http://rss.cnn.com/rss/cnn_topstories.rss"],
				result: [this, resultHandler],
				timeout: [this, timeoutHandler],
				debug: true
			}	
	

In order to use SWXml, you choose SWXml as serviceClass.

At the moment, SWXml has only one method: parseXML.

There are two arguments: xmlSource (required) and xmlType (optional). The xmlSource can be an URL or a local string containing XML (e.g. <xml><demo>Hello World</demo></xml>). If it is a local string, you have to set the optional parameter xmlType to "string" (default of xmlType is 'url').

For local strings: If you have a large amount of data to send, use POST as encoding for your SWX object (swx.encoding = "POST";). Another thing: Use single quotation marks instead of double quotation marks in your local string. (<xml attribute='demo' > instead of <xml attribute="demo" >)

Handling the result

After calling the server, you can save the information you receive from SWX in an array. In this example, the array is called myFeed:

function resultHandler(event:Object)
	{

		var myFeed:Array =  event.result;
		...
	

How to access the data

Text information of a node

Now, you can use the data in a well-known Flash way, with dots between the names of the elements. You can also see the ending ".text" in the following example, which represents the actual value stored in this node.

function resultHandler(event:Object)
	{

		var myFeed:Array =  event.result;
		trace (myFeed.rss[0].channel[0].title[0].text);
	}

The corresponding XML file structure for this example is:

		<rss>
			<channel>
				<title>Hello World</title>
			</channel>
		</rss>
	

So myFeed.rss[0].channel[0].title[0].text would be "Hello World".

The syntax for accessing an node is:
Name of your array, followed by the names of your nodes with an index in brackets, plus ".text" at the end. (e.g. myFeed.rss[0].channel[0].title[0].text)

For each element, you have to put an index in brackets! That's because your data is stored in arrays. If there is only one element in the XML file, for example the very first node of an XML file, set the value 0 in the bracket.

The following rows show you how to access different items (e.g. different news entries):

	myTextArea.text += "Latest News: " + myFeed.rss[0].channel[0].item[0].title[0].text + "\n";
	myTextArea.text += "Latest News: " + myFeed.rss[0].channel[0].item[1].title[0].text + "\n";	
	myTextArea.text += "Latest News: " + myFeed.rss[0].channel[0].item[2].title[0].text + "\n";

The corresponding XML file structure would be:

		<rss>
			<channel>
				<item>
					<title>Hello World!</title>	
				</item>
				<item>
					<title>Hello World?</title>	
				</item>
				<item>
					<title>Hello World ...</title>	
				</item>								
			</channel>
		</rss>
	

Important:
All element names returned from SWXml are in lower case letters!

Create s subset

If you want to reduce the length of your code lines, you can also create a subset of the feed array (e.g. array with a single feed item, a channel, all items, ...). The following code shows you an example of saving the channel data in an array called myChannel.

// Display the result.
myFeed =  event.result;
	
// create a subset of myFeed
var myChannel:Array = myFeed.rss[0].channel[0];

myTextArea.text = "Title: " + myChannel.title[0].text + "\n";
	

Attributes

SWXml returns XML attributes. Image you have the following XML file:

		<rss version="2.0">
			<channel>
				<title>Hello World</title>
			</channel>
		</rss>
	

In Flash, you can read the attribute "version" in this way:

		myFeed.rss[0].attributes.version
	

The value for myFeed.rss[0].attributes.version would be "2.0".

You can access attributes with the following syntax:
[node where you attribute is located] + "attributes" + [name of attribute]

Namespaces

SWXml supports XML namespaces. It automatically returns every elementy in an XML file, you don't have to set up anything!

Let's have a look a the following element from the "Creative Commons" namespace:

     <creativeCommons:license>
		http://www.creativecommons.org/licenses/by-nc/1.0
    </creativeCommons:license>

Since you cannot use a colon in Flash, SWXml replaces every colon with the characters "NS" (= NameSpace). From this it follows that the name for creativeCommons:license is creativecommonsNSlicense.

myFeed.rss[0].channel[0].item[0].creativeCommonsNSlicense[0].text

In short, the syntax for namespaces is: [namespace prefix] + NS + [element name].


5. Error handling

After calling SWXml, there are three problems that could happen:

If problems occure, an error is triggered. You can handle these errors with a faultHandler function.

var callDetails:Object = 
		{
			serviceClass: "SWXml",
			method: "parseXML",
			args: ["http://does-not-exist.xml"],
			result: [this, resultHandler],
			timeout: [this, timeoutHandler],
			fault: [this, faultHandler],
			debug: true
		}
		...
		
		function faultHandler(event:Object) {
			trace (event.fault.message);
			trace (event.fault.code);			
		}
	
	}

If the XML file is not found, the error code (event.fault.code) is 2.

For XML parse errors, the code is 256. The content of fault.message differs depending on your PHP version (4 or 5), because it is the original feedback from the PHP XML parser. It contains a further error code from the XML parser and a description of the parse problem (depending on PHP version as mentioned before).

For a URL without 'http', the error code is 256, too. The error message is: "The URL doesn't start with 'http'".

Using a faultHandler function in your SWX call, you can check for missing feed files, missing 'http' at the beginning of the URL and XML parse errors.


6. Debugging

SWX Service Explorer and SWX Data Analyzer

Using the SWX Service Explorer or the SWX Data Analyzer, you can see the data that is returned from an SWX call.

The Explorer and the Analyzer are really useful tools. Have a look at the "tree view" where you see the array of your XML data clearly arranged. I recommend you to use these tools!

For SWX Data Analyzer, you have to turn debug mode on:

		var swx:SWX = new SWX();
		swx.debug = true;

You can find further information on swxformat.org.


7. Use SWXml for API developement

You can also use SWXml as part of your own API. Aral will integrate SWXml to the BaseService class. In the meantime, you can find an example and some further information here: New SWX Backpack Service


8. Status and open issues

Version: SWXml 0.8.2 (November, 2007)

Feature Status
compatible with PHP 4
(tested with 4.4.4.)
compatible with PHP 5
(tested with
5.1.6 and 5.2.3)
Return the content of a node (.text)
Return the content of a Node (.text) with namespace
Return attributes
Return attributes with namespace
Error handling: Parse error
Error handling: File not found
Error handling: URL does not start with 'http'
Possibility to parse a local string containing XML

Changelog:

SWXml 0.8.2 (November, 2007)

SWXml 0.8 (October, 2007):


9. Links


10. Feedback

Bugs, feedback, suggestion box, ... : Contact

www.video-flash.de, Florian Plag, 18.11.2007