XiLib

XiLib is a package of 2 classes, that can help in building modular Flash applications.
It facilitates application maintenance : There is no need to re-build the whole project to fix a specific bug, to upgrade an existing part or add a new part to an existing application.
Xilib works with Haxe Flash9 and gives help in loading and using ressources from external SWF libraries (as run-time downloaded classes, media assets, components, plugins or listeners*).

Install


In order to use XiLib, you need to install the library using haxelib, like that :
haxelib install xilib

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

What can XiLib do ?


XiLib contains XlibMananger class, that can be used to do:
  • Hard-coded loads of external libraries (once at once or several at the same time)
  • Soft-coded loads of external libraries (from an XML file)
  • Easilly use shared classes, components...

XlibManager also provides:

  • A plug-in system management, that allows you to download at run-time some parts of your project, like own skinned components for example.
  • An easy event system allowing a kind of inversion of control (IOC) in the projects' building process

Maintainting modular applications can be sometimes quite difficult, especially when there is too many separated parts to manage, it gives headacke
So, a light framework was defined : XiLib uses Xlib & Xplug objects and you can use the workspace (folder structure joined to the library), to easilly work with XiLib.

What are Xlib & Xplug ?


They are SWFs files compiled with some specifications, and using a special extension (not requiered but prefered), in order to recongnize them.
A Xlib is an external downloadable library, as a shared library.
A Xplug can be used as a run-time downloaded plugin, or listener*.

Xlib specifications:

  • Media : .swfm : assets library : sounds, pictures, fonts...
  • Package : .swfp : packages, classes
  • Component : .swfc : [Package] + [Media]

XPlug specifications:

  • Plugin : .swfpl : swf + static function main() (compiled without "-main" option)
  • Listener : .swfl : swf + static function main() (compiled without "-main" option)

Objects requirements:


All the xlibs objects (Xlib or Xplug), must define a path that will be used to download the eXternal library and a name to locate ressources in the application.
If the eXternal library uses the stage of the root display object, so you have to add a stage param to the xlib. This param can be used 3 ways : hard-coded, it's a Sprite, soft coded in the .xlibs XML file* as child depths separated by comas or child names separated by comas too. To find the target, XlibManager uses the "root" given in arguments to its constructor.
A domain param comes next. If exist, it will define the domain where classes will be stored. If not, the defaut root domain will be used.
Then a Xplug (plugin or listener) must define a main function that is the class name containing the static function main (entry point of the plugin).
And at the end, only listener defines listen param that is a String that it will listen to through the XlibManager (pushEvent).

How does it work ?


In all cases, in order to use XiLib you need these 2 lines :
xlibm = new XlibManager( flash.Lib.current );
xlibm.addEventListener( XiLibEvent.COMPLETE, onComplete );

Manual managing (hard coded):


Here you have to build the Xlib or Xplug object(s) and give it (or them) to XlibManager to load.
It's an example of manual loading :
var xlib = new xilib.Xlib( "core", "../../../xlibs/release2006/packages/core.swfp" );
xlibm.loadXlib( xlib );

Automatic managing (soft coded):


Here you have to give to XlibManager the path to the .xlibs XML file, where it will find all the xlibs to download.
It's an example of automatic loading :
xlibm.loadXlibsFromXml( "example.xlibs" );

.xlibs XML file :


Here a sample of a xlibs list:
<xlibs>
    <package name="core" path="../../../xlibs/release2006/packages/core.swfp" />
</xlibs>

How to get my ressources ?


You can get your ressources easilly, here are some samples:
// To get the class definition:
Connection = xlibm.getClass( "core", "com.example.tools.Connection" );
// To get an instance of a class:
var proxy = xlibm.getInstance( "core", "com.example.tools.Proxy" );
trace( "Call to a static function : " + Connection.getData() );
trace( "Call to an object's instance function : " + proxy.getInstance() );
// To get the eXternal library's loader (if you want to add it to the DisplayList by yourself):
var sprite = xlibm.getLoaderInstance( "core" );

Compilation


Now you can build 2 kind of SWF : a local version which contains all the classes built-in, or a prod version that will use external libraries loaded at runtime. In all cases you have to add the library:
-lib xilib
Then, -D xilib_on builds a prod version

Example


In this example, we'll try to externalize the communication process with a server, used by an application.
We want switch from an old socket protocol (release2006) to an AMF one (release2008).

Writing the libraries:


So let's build the Connection class for a socket protocol:
workspace/libs/release2006/com/example/tools/Connection.hx:
package com.example.tools;

class Connection
{
    public static function getData() : String
    {
        return "Data from Socket";
    }
}

class Proxy
{
    var instance    : Int;
    
    public function new ()
    {
        instance = Math.round( Math.random() * 100000 );
    }
    
    public function getInstance() : Int
    {
        return instance;
    }
}

Here comes the AMF Connection class.
workspace/libs/release2008/com/example/tools/Connection.hx:
package com.example.tools;

class Connection
{
    public static function getData() : String
    {
        return "Data from AMF";
    }
}

class Proxy
{
    var instance    : Int;
    
    public function new ()
    {
        instance = Math.round( Math.random() * 100000 );
    }
    
    public function getInstance() : Int
    {
        return instance;
    }
}

These classes are here just to simulate. The only difference here is the message displayed (Data from Socket / AMF).
The Connection.hx file contains a Proxy class. The Connection class is here to show a static call when the Proxy class will allow the work with an instance object.

Building the external libraries:


The builds files below, build the SWF files that will be the packages.
This one is to build the Socket version:
workspace/xlibs/release2006/packages/buildCore.hxml:
# Compile XLib Package
-swf core.swfp
-swf-version 9
-cp ../../../libs/release2006/
com.example.tools.Connection

This another is to build the AMF version:
workspace/xlibs/release2008/packages/buildCore.hxml:
# Compile XLib Package
-swf core.swfp
-swf-version 9
-cp ../../../libs/release2008/
com.example.tools.Connection

It gives us 2 files named core.swfp for each version.

Writing a sample project


This sample code can be used to build a local version or a prod one.
workspace/projects/examples/packages/Main.hx:
import flash.display.MovieClip;
import xilib.XLibManager;

#if !xilib_on
import com.example.tools.Connection;
#end

class Main
{
    var root        : MovieClip;
    var Connection    : Dynamic;
    var xlibm        : XlibManager;
    
    public function new()
    {
        root = flash.Lib.current;
        
        xlibm = new XlibManager( root );
        xlibm.addEventListener( XiLibEvent.COMPLETE, onComplete );
        #if xilib_on
        xlibm.loadXlibsFromXml( "example.xlibs" );
        #else
        onComplete( { totalXlibsComplete : 1, totalXlibs : 1 } );
        #end
    }
    
    function onComplete( ?eo : XiLibCompleteEventObject )
    {
        if ( eo.totalXlibsComplete == eo.totalXlibs )
        {
            Connection = xlibm.getClass( "core", "com.example.tools.Connection" );
            var proxy = xlibm.getInstance( "core", "com.example.tools.Proxy" );
            
            trace( "Call to a static function : " + Connection.getData() );
            trace( "Call to an object's instance function : " + proxy.getInstance() );
        }
    }
    
    static function main()
    {
        var v = new Main();
    }
}

As we can see, we are using the xilib_on compilation directive in order to switch between a SWF that contains all the classes built-in or another one that loads them at runtime.
The XiLib Manager is looking for a .xlibs file that is a XML based file and which contains the external libraries' paths.
In this case, the XML file looks like:
workspace/projects/examples/packages/example.xlibs:
<xlibs>
    <package name="core" path="../../../xlibs/release2006/packages/core.swfp"  domain="own"/>
</xlibs>

Now, in order to switch from the old socket protocol, to the AMF one, you just have to change the package path from release2006 to release2008.

More examples:


You can find a set of samples of what actually, XiLib can do, by downloading the library.
There is a workspace folder, using an appropriate structure and containing examples, xlibs and libs (sources) separated.
version #10941, modified 2011-09-07 05:25:22 by flowtron