LoaderMax – Smart AS3 Loading

• Version: 1.4, Updated 2010-09-01
• Compatibility: AS3 (Flash Player 9 or later)

LoaderMax is a new AS3 loading system that does much more than just get swf, mp3, css, video, image, text, binary, and xml files into your Flash application. It eats files for dinner, burps, and then asks for 2nds. And 3rds. Yet it's surprisingly thin. In fact, it can be half the size of most other loading systems even though it delivers a bunch of unique capabilities, some of which you probably never knew you needed but won't want to live without. Here are a few of the noteworthy features:

• Integration of loaders inside subloaded swfs - with most other systems, if you subload a swf, the loader will only concern itself with the swf file's bytes but what if that swf must subload other content like XML, images, and/or other swf files before it should be considered fully loaded? LoaderMax can elegantly handle the sub-subloads as deep as they go. You can link any loader and/or LoaderMax with a swf's root (using the requireWithRoot vars property) so that when you subload it into another Flash application, the parent SWFLoader automatically factors the nested loaders into its overall loading progress! It won't dispatch its COMPLETE event until they have finished as well.
• Automatic parsing of LoaderMax-related nodes inside XML - The XMLLoader class automatically looks for LoaderMax-related nodes like <LoaderMax>, <ImageLoader>, <SWFLoader>, <XMLLoader>, <VideoLoader>, <DataLoader>, <CSSLoader>, <MP3Loader>, etc. in XML files that it loads, and if any are found it will create the necessary instances and then begin loading the ones that had a load="true" attribute, automatically integrating their progress into the XMLLoader's overall progress and it won't dispatch a COMPLETE event until the XML-driven loaders have finished as well. See XMLLoader's ASDocs for details.
• Tight file size - Many other systems are 16-24k+ even if you're just loading text, but LoaderMax can be as little as 7k (depending on which loader types you use).
• Define an alternateURL for any loader - If the original url fails to load, it will automatically switch to the alternateURL and try again.
• A common set of properties and methods among all loaders - All loader types (XMLLoader, SWFLoader, ImageLoader, MP3Loader, CSSLoader, VideoLoader, LoaderMax, etc.) share common properties like: content, name, status, loadTime, paused, bytesLoaded, bytesTotal, and progress as well as methods like: load(), pause(), resume(), prioritize(), unload(), cancel(), auditSize() and dispose() delivering a touch of polymorphism sweetness.
• Nest LoaderMax instances inside other LoaderMax instances as deeply as you want. - A LoaderMax instance is basically a queue of loaders which makes it simple to control them as a whole and get the overall progress, bytesLoaded, and/or bytesTotal. You can put a queue into another - group and nest them however you want. This makes complex queues simple. Need to know when the first 3 loaders have finished loading inside a 10-loader queue? Just put those 3 into their own LoaderMax that has an onComplete and nest that LoaderMax inside your main LoaderMax queue.
• Set a width/height for an ImageLoader, SWFLoader, or VideoLoader and when it loads, the image/swf/video will automatically scale to fit using any of the following scaleModes: "stretch", "proportionalInside", "proportionalOutside", "widthOnly", or "heightOnly". Even crop the image inside that area with crop:true
• Conveniences like auto smoothing of images, centering their registration point, noCache, setting initial x, y, scaleX, scaleY, rotation, alpha, and blendMode properties, optional autoPlay for mp3s, swfs, and videos, and more.
• Works around common Flash hassles/bugs - LoaderMax implements workarounds for things like garbage collection headaches with subloaded swfs, images, and NetStreams as well as other problems like the recently discovered issues with subloading swfs that use TLF.
• Find loaders and content by name or url - Every loader has a name property which you can use to uniquely identify it. Feed a name or URL to the static LoaderMax.getLoader() or LoaderMax.getContent() methods to quickly get the associated loader or content.
• A single loader can belong to multiple LoaderMax instances
• Accurate progress reporting - For maximum performance, set an estimatedBytes for each loader or allow LoaderMax's auditSize feature to automatically preload just enough of each child loader's content to determine its bytesTotal, making progress reporting on large queues very accurate.
• prioritize() a loader anytime - Kick an object to the top of all LoaderMax queues to which it belongs, immediately supplanting the top spot in each one.
• A robust event system - events bubble up through LoaderMax hierarchies and carry a consistent target for easy identification
• Media playback controls in VideoLoader and MP3Loader - convenient methods like playVideo(), pauseVideo(), and gotoVideoTime() as well as properties like playProgress, videoTime, videoPaused, volume, and duration plus useful event dispatching like VIDEO_COMPLETE, PLAY_PROGRESS, and lots more make it simple to wire your own interface to VideoLoader and use it for full playback control, not just loading. Similar controls are available for MP3Loader too.
• Set up multiple event listeners in one line - Add listeners like onComplete, onProgress, onError, etc. via the constructor like new LoaderMax({name:"mainQueue", onComplete:completeHandler, onProgress:progressHandler, onError:errorHandler});
• maxConnections - Set the maximum number of simultaneous connections for each LoaderMax instance (default is 2). This can speed up overall loading times.
• pause()/resume() - no queue loading solution would be complete without the ability to pause()/resume() anytime.
• Helper classes for code hinting and strict data typing - Check out the com.greensock.loading.data package for classes like LoaderMaxVars, ImageLoaderVars, XMLLoaderVars, etc.
• Flex friendly - Simply change the LoaderMax.contentDisplayClass to FlexContentDisplay and then ImageLoaders, SWFLoaders, and VideoLoaders will return content wrapped in a UIComponent.

Rich Shupe debuted LoaderMax in his presentation at Flashbelt (thanks Rich!). You can view his slides here.

Interactive demo 1

Documentation

Please view full ASDoc documentation here.

Sample AS3 code

Interactive demo 2

FAQ

1. Where do I get the code?
   LoaderMax is included in the main AS3 GreenSock download zip - just click the "Download AS3" button at the top right corner of this page.
2. What if I need to send variables to the server along with my request in a loader?
   The first parameter of the various loaders (ImageLoader, XMLLoader, SWFLoader, MP3Loader, etc.) accepts either a simple String URL or a URLRequest. So if you want to pass data to the server, simply construct a URLRequest accordingly, like:
   PLAIN TEXT
   Actionscript:

   1. var request:URLRequest = new URLRequest("http://www.yourDomain.com/whatever.php");
   2. var variables:URLVariables = new URLVariables();
   3. variables.exampleSessionId = new Date().getTime();
   4. variables.exampleUserLabel = "label1";
   5. request.data = variables;
   6. request.method = URLRequestMethod.POST;
   7. var loader:ImageLoader = new ImageLoader(request, {name:"image1"});

3. Do I need to define estimatedBytes for all my loaders?
   Nope. If you don't define one, the default value of 20000 will be used. The only benefit of defining an estimatedBytes is to make the loader's progress more accurate before it has downloaded enough information to determine the bytesTotal. Once it can accurately determine the bytesTotal, it will do so and stop using the estimatedBytes. By default, when a LoaderMax loads, it will loop through its children first and find any that don't explicitly define an "estimatedBytes" and quickly open a URLStream to determine the bytesTotal if possible. There's a slight speed penalty when the LoaderMax first starts loading, but it makes it very accurate. You can turn that feature off with auditSize:false in your LoaderMax's vars parameter.
4. If a child loader inside a LoaderMax has already completed and I call load() again on the LoaderMax, will it waste time reloading that already-completed loader?
   No. If a loader has completed, LoaderMax will skip it in the queue for maximum efficiency and performance. If you want to force a full reload, though, set the "flush" parameter to true in your load() call, like myLoader.load(true)
5. Why do I have to use different loader types (ImageLoader, XMLLoader, SWFLoader) instead of LoaderMax automatically figuring out the type of loader needed based on the file name extension?
   Actually, LoaderMax has a parse() method that can do exactly that (automatically figure out the type of loader necessary based on the file extension) - you just need to make sure you use LoaderMax.activate() first to activate the loader types that you want LoaderMax to be able to recognize (like ImageLoader, SWFLoader, etc.). This extra step may seem annoying, but there are a few reasons I opted to avoid building the system in a way that activates all of the loader types by default:
   • It forces ALL types of loaders to be compiled in your swf so that they're available just in case you need them. So your project may never need an SWF loader or MP3 loader, etc. but they still must be compiled in your SWF for the logic in the "lazy" loader. In my opinion, this bloats the whole system which isn't good because a loading system should be relatively lightweight in order to get things moving quickly.
   • It's virtually impossible to accurately determine the file type if the extension is something like ".php" because you could have a server-side script that spits back any type - an image, an XML file, etc. In those cases, the "lazy" system would break down. You'd have to explicitly define the type anyway.

   Ultimately I believe it is much cleaner to have the developer choose the appropriate loader for the asset whenever possible (ImageLoader, SWFLoader, XMLLoader, etc.) and it definitely allows the system to be more lightweight and efficient. It could literally reduce the file size requirement by more than 60% in many cases.

6. Is the LoaderMax API finalized? Might it change?
   This is a 1.0 release and while there are no plans to make any changes to the API, my experience has been that feedback from the community is invaluable and can help shape the API. I try to keep improving things to serve end users better, so don't be surprised if there are some changes in upcoming months. I would recommend checking back frequently for updates or sign up for Club GreenSock so that you can be notified.
7. Can I make suggestions for improving LoaderMax?
   Please do! Either in the comments section below or in the forums.
8. Why did you use the loosely typed vars parameter to define all the special properties (like {name:"myLoader", width:100, height:200}) instead of regular strong-typed parameters or properties? Your way doesn't give me code hinting either.
   True. However, one of the objectives was to keep file size to a minimum and encourage readable code, neither of which could be accomplished very well otherwise. There are quite a few optional special properties for various loaders (SWFLoader recognizes 41!) and regular parameters just wouldn't be feasible. Which one is more readable?:
   PLAIN TEXT
   Actionscript:

   1. new SWFLoader("main.swf", "myFile", 100, 100, 200, 200, this, completeHandler, null, null, progressHandler);
   2. -OR-
   3. new SWFLoader("main.swf", {name:"myFile", x:100, y:100, width:200, height:200, container:this, onComplete:completeHandler, onProgress:progressHandler});

   But don't worry - if you want strong typing and code hinting, there are some helper classes for exactly that - Check out the com.greensock.loading.data package for classes like LoaderMaxVars, ImageLoaderVars, XMLLoaderVars, etc. that allow you to define all your vars stuff with a special object.

9. Can I get the source code for the demos above?
   Sure, download it here.
10. Is LoaderMax available in AS2? Will it be?
    The tweening platform and TransformManager, my 2 most popular products, ARE available in AS2 as well as AS3 but LoaderMax is only AS3 because...well...AS2 has been on the decline for a long time and LoaderMax relies heavily on the event system in AS3 so it would be a much bigger challenge to port it to AS2. Then there's maintenance. Right now, every time I make an update to the AS3 version of TweenLite/Max/TimelineLite/Max/TransformManager, I must also make the update to the AS2 versions, copy all the files, create zips, post to the SVN, update the bonus zips for members, etc., Then there are language-specific differences I'd need to accommodate. So it just doesn't seem worthwhile to do for a product like LoaderMax especially since AS2 is heading towards extinction.
11. Will you be posting more examples?
    Yes.
12. Do I have to purchase a license to use this code? Can I use it in commercial projects?
    You may use the code at no charge in commercial or non-commercial web sites, games, components, applications, and other software as long as end users are not charged a fee of any kind to use your product or gain access to it. If your client pays you a one-time fee to create the site/product, that's perfectly fine and qualifies under the "no charge" license. If multiple end users are charged a usage/access/license fee of any kind, please simply sign up for a corporate Club GreenSock membership which comes with a special commercial license granting you permission to do so. Click here for details. Club GreenSock members get several useful bonus plugins, classes, update notifications, SVN access, and more. Please see the licensing page for details on licensing.

Need help?

Please post your question in 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.