MassLoad is a library that enables you to manage the loading of extern files in Flash (currently, only flash 9 is supported). MassLoad is usefull in big websites that need to often load files when navigate on them. The library supports text files, images and SWF files, sound files and can group them to load them simultaneously.

Install

In order to install MassLoad, you need to run the following command :

haxelib install massload

Then you can use the library by adding -lib massload to haxe commandline parameters.

Tutorial

How to get the massloader instance

The massloader is developped following the singleton pattern. So to get its instance you must do :

var loader = fas.massload.MassLoader.getInstance();

How to defined a file to download

File downloads are divised into 4 means of downloading called LoadFiles:
- Loader (for images, SWFs,...) : LLoadFile,
- UrlLoader (for text and XML files) : ULoadFile,
- SoundLoader (for sound files...) : SLoadFile,
- GroupLoader (for group of whatever kinds of file) : GLoadFile.

In fact the massloader manages a list of these LoadFiles, so you need to create an instance of a LoadFile before add it in the massloader.
To do that you can instanciate them manually but it's easier to use the LoadFileCreator tool. This tool is in the fas.massload.file package.

// You can let the massloader find the better way to download the specified file
var myFile = fas.massload.file.LoadFileCreator.create({file: "my_file.swf", name: "my flash file"});

// The massloader gets the way to download the file by checking the file extension
// So if the file extension isn't known you can register it like this :
fas.massload.file.LoadFileCreator.addExtension(UrlLoader, "ini");

// Now the extension is directly detected
var myIniFile = fas.massload.file.LoadFileCreator.create("my_file.ini", "my ini file");
        
// You can manually indicate the type of download you want the loader uses.
var mySoundFile = new fas.massload.file.SLoadFile(new flash.net.URLRequest("my_file.mp3"), "my sound file");

How to create a group of download

Group creation is a little different.

// To create a group you can do like this :
var myGroupFile = new fas.massload.file.GLoadFile([
        new fas.massload.file.ULoadFile(flash.net.URLRequest("my_file.php"),"my php file"),
        fas.massload.file.LoadFileCreator.create("sound.wav","my wav file"), //...
    ], "my group file");

// But it's easier to do like this
var myGroupFile = fas.massload.file.LoadFileCreator.create({files: [
        {file: "my_file.php", name: "my php file"},
        {file: "sound.wav", name: "my wav file"}, //...
    ], name: "my group file"});

How to listen events

It's good to download but we need to know when is downloaded... So the massloader and each LoadFile dispatch some events.

There is error events (fas.massload.events.MassLoaderErrorEvent):
- IO_ERROR

- SECURITY_ERROR

- ERROR (this error is dispatched for each kind of error)

And information events (fas.massload.events.MassLoaderEvent):
- INIT, COMPLETE, PROGRESS, OPEN events are the flash events redispatched,

- COMPLETE_ALL is dispatched by the massloader when it just finishes to download all the file list,

- COMPLETE_ELEM is dispatched by groups of files when an element is finished (when all are finished it dispatches the COMPLETE event)

- CLOSE is dispatched when a LoadFile is closed.

How to 'really' download

OK, we have instantied some LoadFiles. Now we must add them to the massloader and start it.

The method to use is addFile. This method takes a mandatory argument and 2 optionals.

The first is only the file to add...

The second is a priority. There is 3 kinds of priority:
- High: if the massloader is started, the currently downloading file is stopped and the added one is started. If it's not started the file is only placed at the head of the list,

- Medium: in this case
the added file is placed in second position,

- Low: in this case the file is added at the end of the list.

And the last one is a boolean indicate if you want to remove all the homonyms of the file to avoid useless multiple downloads.

// To add a file to the load list we just have to do this for each file to download
loader.addFile(myFile);
loader.addFile(myIniFile, Medium);
loader.addFile(mySoundFile, High, true);
//...

// Now we can launch the massloader
loader.start();

// To stop it, it'is : loader.stop(); (Incredible isn't it? ^^)

You must notice that you can start the massloader before adding LoadFiles. If the massloader is started before you add a LoadFile and the file list is empty, the file will automaticaly start.

How to use events

Error events have the following fields:
- file : which contains a reference to the ILoadFile which gets the error,
- text : the error message
- id : ...hem...not used.

Information events have the followinf fields:
- the same file field than error events,
- in the case of a ProgressEvent the fields bytesLoaded and bytesTotal contains informations about the progression, otherwise they are set at zero.
- in the case of an information event dispatch by an element of a GroupFile, the element is referenced into the element field.

To access to the content of a loaded file you must use its content field. In fact the content field contains the instance of the flash loader used. For instance in ULoadFile, the content field contains an instance of an UrlLoader...

This is an example to show how to get the content of a loaded file

//...
function onMyFileComplete(ev:fas.massload.events.MassLoaderEvent) : Void {
    // We have load a swf file so we can do some actions like
    flash.Lib.current.addChild(ev.file.content);
}

function onMyGroupFileComplete(ev:fas.massload.events.MassLoaderEvent) : Void {
    // In a group of files the 'content' field is different. It contains a Hash of LoadFiles
    // So with our example we can access to content like this:
    trace(ev.file.content.get("my php file").content.data);
    
    // or this
    ev.file.content.get("my wav file").content.play();
}
//...

Example

The code below is an example of a little website.

Main.hx

import fas.massload.MassLoader;
import fas.massload.file.LoadFileCreator;
import fas.massload.events.MassLoaderEvent;
import fas.massload.events.MassLoaderErrorEvent;


class Main {
    static function main() { new Main(); }

    function new() {
        var loader = MassLoader.getInstance();
        
        // Before showing the page we need to get the text content
        // and the website logo...
        var page = LoadFileCreator.create({name: "page", files: [
            {file: "news.php", name: "news"},
            {file: "img/logo.png", name: "logo"}
        ]});
        page.addEventListener(MassLoaderEvent.PROGRESS, onPageProgress);
        page.addEventListener(MassLoaderEvent.COMPLETE, onPageComplete);
        page.addEventListener(MassLoaderErrorEvent.ERROR, onError);
        loader.addFile(page, High);

        // The ambiance sound isn't the most important thing so 
        // we set it in low priority

        var sound = LoadFileCreator.create({file: "music.mp3", name: "ambiance"});
        sound.addEventListener(MassLoaderEvent.COMPLETE, onSoundComplete);
        sound.addEventListener(MassLoaderErrorEvent.ERROR, onError);
        loader.addFile(sound, Low);

        loader.addEventListener(MassLoaderEvent.COMPLETE_ALL,onCompleteAll);
    
        loader.start();
    }

    function onCompleteAll(ev:MassLoaderEvent) : Void {
        trace("The download list is empty!");
    }

    function onError(ev:MassLoaderErrorEvent) : Void {
        trace("Error #" + ev.text);
    }

    function onPageProgress(ev:MassLoaderEvent) : Void {
        trace("Page progression: " + Math.round( ev.bytesLoaded / ev.bytesTotal * 100 ));
    }

    function onPageComplete(ev:MassLoaderEvent) : Void {
        trace("Page complete");

        // Show the logo
        flash.Lib.current.addChild(ev.file.content.get("logo").content);

        // Trace the text
        trace(ev.file.content.get("news").content.data);
    }

    function onSoundComplete(ev:MassLoaderEvent) : Void {
        trace("Sound complete");

        // Start the music
        ev.file.content.play();
    }
}

Additional features

The massloader contains other features to help you to manage your files list.

Methods

Remove the LoadFile called sName from the list.

function removeFile( sName:String ):Void

If bAll is false: Replace the first LoadFile called sName from the list by the specified file.
If bAll is true: Replace all LoadFile called sName from the list by the specified file.

function replaceFile( file:ILoadFile, sName:String, bAll:Bool )

Return true if a LoadFile called sName is in the list.

function exists( sName:String ):Bool

Return the index of the first LoadFile called sName in the list and -1 if it's not present.

function indexOf( sName:String ):Int

Return the index of the last LoadFile called sName in the list and -1 if it's not present.

function lastIndexOf( sName:String ):Int

Properties

Indicate if the massloader is started.

var loading( default, null ):Bool;

Contains the list of non loaded files.

var files( default, null ):Array<ILoadFile>;

Contains the number of elements in the files list.

var filesCount( default, null ):Int;

Indicate the number of simultaneaous download available.

var parallelFiles( default, setParallelFiles ):Int;

Number of files downloading currently simulatenously.

var loadingFiles( default, null ):Int;