Packing Skin Assets

Note: Aspire UI Components Version 1.3.0+ is required.

You may compress skin assets from a theme folder, along with the “rules.xml” file, into one single binary file.

This is advantageous for the following reasons:

• the overall total payload (bytes to download over the network) is now reduced due to compression;

• only one network connection is required, instead of multiple simultaneous connections to the various PNG files;

• moving skin assets is now easier since you only need to move one file around;

• if embedding skin assets into the application SWF is preferred, this can now be done easily since you only need to embed one single file.

The benefits of using packaged themes will be especially visible when deploying to an environment where slow network connections are expected.

In order to package skin assets into a file that can be understood by the Aspire UI skinning manager, you need to use “Amber” - the packing tool provided in the Aspire UI library distribution. After you extract the files from the zip distribution, you will find “Amber” in the “tools” folder. Within this “tools/Amber/” folder, you will see a file “AssetsPackageBuilder.swf” - this is “Amber”, the assets packing tool.

For simplicity and cross-platform compatibility, “Amber” was created as a Flash Player 10 SWF. You can run the SWF either directly using Flash Player 10+, or via a web browser (if the web browser has Flash Player 10 plugin installed).

“Amber” automatically look for skin assets in the “assets/skins/default/” folder (relative to where the SWF is run).

When “Amber” is started, it will load the “rules.xml” file from the “assets/skins/default/” folder.

After parsing the “rules.xml” file, “Amber” will show you a list of skin assets.

You can either pack everything in the theme, or go through the list and exclude/include skin assets you wish to pack. This makes it easy to create a package that contains only the skin assets your application uses. For example, if your application does not display any uiWindow instances, you can exclude all the skins used by the uiWindow class.

Once you have selected the assets to pack, click the “Build!” button - you will be presented with a native dialog box, in which you should specify the target file name and location.

When saving the file, the default name is “assets.bin”. However, you can choose any name you like. It is recommended that you keep skin assets, whether packed or otherwise, in their respective folders. For example, if you have a theme named “olive” (saved in the folder named “olive”), you may want to save the packed version of that theme in a folder named “olivebin”.

In order to pack skin assets from your own theme, delete the “assets/skins/default” folder (relative to where “AssetsPackageBuilder.swf” is), and replace it with your own theme folder (renamed as “default”). Remember, “Amber” automatically look for skin assets in the “assets/skins/default/” folder (relative to where the “AssetsPackageBuilder.swf” is), so whatever you put there will be used for packing.

To use a packaged theme in your application, you must call the uiSkins.initialize() method, passing the name of the packaged theme file as the third parameter, in-lieu of the name of the “rules.xml” file which you would normally load. In other words, to be very clear, the packaged theme file replaces your usual “rules.xml” file, because the packaged theme file already contain a version of the “rules.xml” file.

Example:

    uiSkins.initialize(null, null, "assets.bin");
    // load "assets.bin" from "assets/skins/default/" folder

Example:

    uiSkins.initialize("olive", null, "assets.bin");
    // load "assets.bin" from "assets/skins/olive/" folder

If you wish, you can also save your packaged theme file as “rules.xml”. If you do that, the uiSkins manager will automatically load it. For example, if you save a packaged theme file as “rules.xml” in the “assets/skins/olivebin/” folder (relative to where you application SWF is), you can write the following code:

    uiSkins.initialize("olivebin");
    // load "rules.xml" from "assets/skins/olivebin/" folder

NOTE: if you choose to save the packaged theme file as “rules.xml”, when deploying over a network, please make sure you upload “rules.xml” as a binary file.