XMLParser – Painless XML Translation
- Version: 4.82, Updated 8/26/2008
- Compatibility: Flash Player 6 and later (AS2)
- File size added to compressed SWF: about 3k
 |
 |
NOTE: If you need an AS3 version of this class, you can get it HERE (although the way AS3 handles XML makes this class largely unnecessary)
Description
This class provides an easy way to load and/or send an XML file and parse the data into a format that's simple to work with. Every node becomes an array with the same name. All attributes are also easily accessible because they become properties with the same name. So for example, if this is your XML:
<Resources>
<Book name="Mary Poppins" ISDN="1122563" />
<Book name="The Bible" ISDN="333777" />
<Novel name="The Screwtape Letters" ISDN="257896">
<Description>This is an interesting perspective</Description>
</Novel>
</Resources>
Then you could access the first book's ISDN with:
-
Book[0].ISDN
The value of a node (like the text between the <Description> and </Description> tags above) can
be accessed using the "value" property, like so:
-
Novel[0].Description[0].value
Just remember that all nodes become arrays even if there's only one node, and attributes become properties. You can obviously loop through the arrays too which is very useful. The root node is ignored for efficiency (less code for you to write) unless you set the keepRootNode_bol parameter to true. Also, numeric values are properly translated into numbers, not strings (as of version 4.6)
OBJECTIVES
- Eliminate the hassle and complexity of searching through XML using methods like my_xml.firstChild.firstChild.childNodes[2].attributes.name.
- Create an intuitive way to organize XML data while maintaining its heirarchy and naming conventions.
- Provide a mechanism to both parse XML data into an ActionScript-friendly format and also take an ActionScript object and translate it into an XML object (maybe for sending to a server).
Important properties
- percentLoaded_num: Poll this value to find out the loading progress
- bytesLoaded
- bytesTotal
- xml
- loaded_bol
- keepRootNode_bol
Usage
- Description: A static function that loads an XML document from a url (relative or absolute), parses it into the parsedObject, and then calls the onComplete (if you define one)
- Arguments:
- url: The URL (relative or absolute) where the XML file resides that you'd like to parse
- onComplete: [optional] A reference to a function that you'd like to call as soon as the XML file has been loaded and parsed. Three parameters will get passed to that function in the following order:
- success: If the XML file was loaded successfully, this will be true. Otherwise, it's false.
- parsedObject: The object containing all of the parsed XML data
- original_xml: The original XML that was loaded (unparsed)
- parsedObject: [optional] A reference to an object that should be populated with the parsed XML data.
- keepRootNode: [optional] By default, the class essentially ignores the root node to make it easier for you to access data (shorter code), but if you want to keep that root node, set this value to true. Obviously it's false by default.
- parseLineBreaks: [optional] If you set this value to true, all instances of "\n" in your XML will be parsed and replaced with line breaks in Flash.
- Description: A static method that translates an ActionScript object into XML format and sends it to a url and then returns any resulting XML (from the server) to the onComplete function.
- Arguments:
- toSend: The ActionScript object that you'd like to send to the server. It does NOT need to be a simple object with only a few properties. Its properties can contain arrays (with other arrays, etc.)
- url: The url to which the XML should be sent.
- onComplete: [optional] A reference to a function that you'd like to call as soon as the XML file has been and the server has responded and the resulting XML has been parsed. Three parameters will get passed to that function in the following order:
- success: If the XML file was loaded successfully, this will be true. Otherwise, it's false.
- parsedObject: The object containing all of the parsed XML data
- original_xml: The original XML that was loaded (unparsed)
- parsedObject: [optional] A reference to an object that should be populated with the resulting parsed XML data.
- keepRootNode: [optional] By default, the class essentially ignores the root node to make it easier for you to access data (shorter code), but if you want to keep that root node, set this value to true. Obviously it's false by default.
- parseLineBreaks: [optional] If you set this value to true, all instances of "\n" in your XML will be parsed and replaced with line breaks in Flash.
- Description: A static function that translates any ActionScript object into an XML object. It will retain the name of each property (which ends up being a node attribute) and array (which ends up being a collection of nodes).
- Arguments:
- toTranslate: The ActionScript object that should be translated into XML.
- rootNodeName: [optional] An XML document must have a single root node. You can define that name here. "XML" is the default name.
- Description: A static function that translates any XML into an object. It will retain the name of each attribute (which ends up being a property) and node value (which ends up being the "value" property of the resulting object). Similarly named node siblings are automatically dumped into an array.
- Arguments:
- xml: The XML that should be translated into an object.
- parsedObject: [optional] If you want to add the properties/arrays to a particular object that you've already created, pass it in here, otherwise a new object will get returned with all of the properties/arrays from the parsed XML.
- keepRootNode: [optional] By default, the class essentially ignores the root node to make it easier for you to access data (shorter code), but if you want to keep that root node, set this value to true. Obviously it's false by default.
- parseLineBreaks: [optional] If true, all instances of "\n" in your XML will be parsed and replaced with line breaks in Flash
- Description: Stops loading the XML document
- Description: Destroys the instance (and cancels loading the XML)
Examples
-
import gs.dataTransfer.XMLParser;
-
XMLParser.load("myDocument.xml", onFinish);
-
function onFinish($success:Boolean, $results:Object, $xml:XML):Void { //This function gets called when the XML gets parsed.
-
if ($success) {
-
trace("The first book is: "+$results.Book[0].name);
-
}
-
}
object properties become node attributes) and load the results back into an ActionScript-friendly format, do:
-
import gs.dataTransfer.XMLParser;
-
//Create an object to send an populate it with values...
-
var toSend_obj = new Object();
-
toSend_obj.name = "Test Name";
-
toSend_obj.Book = new Array();
-
toSend_obj.Book.push({title:"Mary Poppins", ISDN:"125486523"});
-
toSend_obj.Book.push({title:"The Bible", ISDN:"25478866998"});
-
//Now send the data and load the results from the server into the response_obj...
-
XMLParser.sendAndLoad(toSend_obj, "http://www.myDomain.com/myScript.php", onFinish);
-
function onFinish($success:Boolean, $results:Object, $xml:XML):Void {
-
if ($success) {
-
trace("The server responded with this XML: " + $xml);
-
trace("The server's response was translated into this ActionScript object: " + $results);
-
}
-
}
In the above example, the server would receive the following XML:
<XML name="Test Name">
<Book ISDN="125486523" title="Mary Poppins" />
<Book ISDN="25478866998" title="The Bible" />
</XML>
Need help?
Feel free to post your question on the forums. You'll increase your chances of getting a prompt answer if you provide a brief explanation and include a simplified FLA file (and any class files) that clearly demonstrates the problem.
Comments (34)
This looks great. How’s the performance?
Brian, I’ve been using this for quite some time and have never had any performance problems whatsoever, but I haven’t tried pushing it to its limits either by loading a 10MB XML file or anything. Nobody has reported performance problems either, so I think it’s pretty safe to say that it’ll perform quite well for you unless you get crazy with the amount XML data you load which would be more of a Flash limitation than this class.
Great class, just the thing i’ve been searching for.
Hope i’ll be able to put it in good use.
Cheers!
This is a great class, but very annoying at the same time. For example, if I already have an XML file loaded into my movie, I cannot convert it to an object using this class. It only works if I want to load XML from an external file.
Is there a way to convert an already-loaded XML file into an object using this class?
Brendan, you’ve got a valid point. I’ve never run into a situation where I’d want or need to load in XML without using XMLParser, but maybe you’re working with XML that’s being created from within an SWF in which case it’d be handy to have an XMLToObject() method. Wish granted. I just updated the class (v4.0) to allow for this. It should be as simple as passing your XML into the static XMLParser.XMLToObject() method and you’ll get an object returned. Enjoy.
Great class. It is very useful, and painless to use. I have a question…
Using the XMLParser.load() method, how would you reference the attributes of the first node?
How would I reference the “id” attribute in the following example?
Thanks!
David, as of version 4.4, you can now define a keepRootNode_bol parameter as true to force the class to include the root node. Keep in mind it’s false by default. So an example would be:
XMLParser.load(“myDocument.xml”, onCompleteLoad, results_obj, true);
The new version also adds the ability to get the bytesLoaded, bytesTotal, and percentLoaded_num for preloader visualization.
Enjoy!
You totally rock! This is a wonderful timesaver and it works flawlessly. Thank you!
yo dude Thanks a million for these classes! and most of all THANKS for sharing them for free! this is really a good attitude.
have a nice one!
Thank you very, very much for these classes ! They are incredibly useful to me !
this is just great, exactly what I was looking for…
thank you very much
thanks for your classes Jack!
you are a time saver.
question: is there a possibility to make XMLParser for actionscript 3??
that would be ideal!
Michako, yes, I do plan on eventually porting XMLParser to AS3 but not until I have a project that requires it. I’ve got too much on my plate right now to attack it, but stay tuned…
How do I use cancel()? XMLParser.cancel() does not work, because it is not a static method. But XMLParser.load() is static, so this is how it should be used, right?
I would like to kill the loading of the first XML, when the user clicks fast enough to fetch a second XML before the first is loaded.
Can you give a hand?
Tilman, the static load() method returns an instance of the XMLParser class, and that’s what you can call cancel() on. So you could do:
var myXMLParser = XMLParser.load(“myXML.xml”, onFinish);
//Then, to cancel, you’d do:
myXMLParser.cancel();
thanx,
very usefull class.
what about special characters : “é”, “è” or “à ” ?
does it work ?
bmg///
brice_m_g, from my testing, in order to get those special characters to show up inside Flash, you must:
1) Put this code on the first frame of your SWF: System.useCodepage = true;
2) Make sure those characters are embedded in the TextFields where you’ll use them.
Hey Jack! Your class is great! I was using Zeh Fernando’s XML2Object before but I think I’ll stick to yours from now on.
I thought about one little helpful feature though: while parsing XML document, you could change the type of the value/attribute to Number (instead of being String) when it seems to be numeric.
I found it useful while parsing XML data describing Tweens, using String type values didn’t work and it took me a while to figure it out why.
Great suggestion, Og2t. As of version 4.6, XMLParser will parse numbers as numbers, not strings.
You sir, are a God amongst Men!
Thanks Jack!
The best parser I’ve seen on the net and I’ve been around since the ice age. Very good work Jack I hope you can find the time to maintain the project.
jack,
This is the best xml related class i’ve seen!!
Congratulations and thanks for sharing!
Fantastic!
thanks jack… now i’m beginning to love XML ^^
any chance someone out there knows if this parses html text ? I’m trying to use cdata but have not been successful so far, any thoughts?
Thanks Jack, I love this parser, makes my life so much easier!
best,
~laura
Awsome, I got it to work. there’s two ways to put in html links
without CDATA, using utf-8 characters,
<a href="http://www.google.com/"> Link to Google</a>”
and the other with CDATA would be
<![CDATA[ Link to Google]]>
Thanks again Jack!
Hi Jack,
parser works great for me. Got a 1.5 Mb XML to load. Is there a way to monitor the loading progress?
thanks!
Sure, Mark – there are “bytesLoaded” and “bytesTotal” properties you can tap into as well as a “percentLoaded” property (“percentLoaded_num” in AS2). Keep in mind that the load() method returns an instance that you can use to check those values.
Been using the TweenLite engine for a while, just found out about this.
Terrific work. You are a real asset.
I migrated from Flash to Javascript (now doing full time JS development) a while back. This week, however, I need to create an API for an XML web service for use in Flash.
I just got headaches from trying to use Flash’s built in web service tools, as our web service wasn’t using any kind of premade toolkit or standards (it’s pretty janky but it works, lol). I then decided to use my old friend XMLParser and just build the API on top of that.
Best decision ever. This thing is so damn versatile! I think I’ll have to donate again tonight.
I am new to AS3 and learning. I just wanted to say thank you for all these wonderful classes you are allowing us to download. I came here to try out TweenMax (having had some success with Tweener) and I stumbled upon these other projects of yours. They look great and I only wish I had more time to try them out.
Anyway, thanks for making them accessible! Once I understand things better I’m sure I’ll want to join your club and contribute to your work financially. (In faith, I’ll start saving my pennies)
Thanks again!
Jack, you are Timer saver for us. Thank you for all wonderful classes.
I’ve said it before, and I’ll say it again.
YOU ARE THE MAN!
Thanks a lot for that class !
It seems that you changed the “value” proprety to “nodeValue” where we get the value of a node.
It tooks me a while to understand why I was getting all those undefined values !
Thanks again for the class !