splinkresource 0.1.0 framework released

splinkresource aims to ease the workflow with resources in actionscript3 multilanguage applications. It supervises the processing of resources by loading and registring display assets, fonts and class libraries. During resource loadtime it offers detailed information on the load progress of the currently loading resource but also on the overall resource load progress. Moreover it provides conventient access to the processed resources within your application.

In particular splinkresource simplifies the development of actionscript 3 multilanguage applications by offering the concept of localized resourcebundles. Each resourcebundle contains information on and references to resources availible within the context of a locale. So the framework loads and provides only the resources needed for the specified locale. If your need to switch to another locale during runtime, you just pass the new locale to the framework and let it process the corresponding resourcebundle. Upon completion you have access to resources within the context of the new locale.

Of course splinkresource integrates well into the splinklibrary queue system. For instance you can add splinkresource easily into your application bootstrapping.

Because I believe in examples
The rough workflow with splinkresource is to:

- create an xml file based on the resourcebundles.dtd shipped with splinkresource. The file might look like:

 
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE resourcebundles SYSTEM "resourcebundles.dtd">
<!-- Sample xml Note that id values MUST BE UNIQUE -->
<!-- defaultLocale is the locale which is loaded by default -->
<resourcebundles defaultLocale="de_DE">
 
<!-- For multilanguage applications define a resourcebundle
for each locale -->  
 
<!-- locale defines the locale for the resourcebundle
package -->
<resourcebundle locale="de_DE">
	<!-- path is the path to the asset files, relative from
	your applications root directory -->
	<assets path="assets/">
		<!--
		 id is the assets id
		 src is the assets source
		 register defines a subclass of
		 org.quui.resource.AssetRegister in which the assets are
		 specified
		 -->
		<asset id="sample assets" src="assets.swf"
		register="sample.SampleAssetRegister" filesize="16375" />
	</assets>
	<!-- path is the path to the font files, relative from
	your applications root directory -->
	<fonts path="fonts/">
		<!--
		id is the name of the font
		type is the identifier which you use within your
		application to access a FontData object
		src (optional) the fonts source
		isSystemFont (optional) default value is false
		xOffset,yOffset (optional) enables to define a x/y offset
		for a specific font type
		sizeOffset (optional) enables to define a size offset
		for a specific font type
		-->
		<font id="Futura LT Condensed Bold" type="headline"
		src="futura_western.swf" filesize="26908" />
		<font id="Arial" type="text" src="arial_western.swf"
		filesize="104710" />
		<font id="Verdana" type="system" isSystemFont="true"
		xOffset="5" yOffset="5" sizeOffset="-3" filesize="0" />
	</fonts>
 
		<!--
		path is the path to the library swf files, relative
		from your applications root directory a quick way to
		get a library swf is to generate an swc (which in fact
		is a zip archive) and extract the swf within. To gain
		autocompletion for dynamically loaded class swfs:
		as fdt user you can add the swc as "runtime shared
		code" in your "fdt sourcefolder" tab or as flex user
		add the swc to the "flex build path" and switch the
		"default link type" for your swc from "merged into
		code" to "runtime shared library". These steps cause
		the compiler not to compile the code into your swf
		(because the code will be loaded during application
		runtime), but enable the editor to use the swc for
		autocompletion
		-->
<libraries path="library/">
		<!--
		id is the librarys id
		src is the librarys source
		-->
<library id="de.polygonal.as3ds" src="as3ds.swf"
		filesize="43654" />
	</libraries>
 
</resourcebundle>
 
<resourcebundle locale="en_US">
	<assets path="assets/">
		<asset id="assetA" src="assetA.swf"
		register="DefaultAssetRegister" filesize="0" />
		<asset id="assetB" src="assetB.swf"
		register="DefaultAssetRegister" filesize="0" />
	</assets>
	<fonts path="fonts/">
		<font id="Futura LT Condensed Bold" type="headline"
		src="futura_western.swf" xOffset="3" yOffset="3"
		sizeOffset="2"
		filesize="26908" />
		<font id="Arial" type="text" src="arial_western.swf"
		sizeOffset="-2"
		filesize="104710" />
		<font id="Verdana" type="system" isSystemFont="true"
		filesize="0" />
	</fonts>
</resourcebundle>
 
</resourcebundles>
 

- use the org.splink.ant.filesizeinjectortask.jar ant task and integrate it into the build process. Have a look at the sample build file:

 
<?xml version="1.0" encoding="UTF-8"?>
 
<!-- @author Max Kugland -->
<project name="org.splink.resource.sample" default="build_sample"
basedir="../">
<property file="build/build_${user.name}.properties" />
 
	 <!-- project folders -->
<property name="dependencies" value="${basedir}/dependencies" />
<property name="build" value="${basedir}/build" />
<property name="sample" value="${basedir}/sample" />
<property name="xml" value="${basedir}/xml" />
<property name="source" value="${basedir}/src" />
 
    <taskdef name="sizeinjector"
	classname="org.splink.ant.SizeInjectorTask"
	classpath="${basedir}/build/org.splink.ant.filesizeinjectortask.jar" />
 
	<target name="inject" description="Inject file sizes into the
	resources xml file">
        <sizeinjector file="${resourcefile}"
		resourcebasedir="sample" />
    </target>
 
	<target name="build_sample_assets">
		<exec executable="${flex.mxmlc}">
		<arg line="-default-size 1 1" />
		<arg line="-default-frame-rate=30" />
		<arg line="-library-path '${flex3libsdir}'" />
		<arg line="-default-background-color=0xffffff" />
		<arg line="-source-path ${source}" />
		<arg line="-output ${sample}/assets/assets.swf" />
		<arg line="${source}/sample/SampleAssetRegister.as" />
	    </exec>
	</target>
 
	<target name="build_sample"
	depends="build_sample_assets, inject">
		<exec executable="${flex.mxmlc}">
		<arg value="-debug=true" />
		<arg line="-library-path '${flex3libsdir}'" />
		<arg line="-library-path '${org_splink_library}'" />
		<arg line="-external-library-path+='${basedir}/${as3ds}'" />
		<arg line="-default-size 640 480" />
		<arg line="-default-frame-rate=30" />
		<arg line="-default-background-color=0xffffff" />
		<arg line="-sp ${source}" />
		<arg line="-o ${sample}/sample.swf" />
		<arg line="${source}/sample/SampleApplication.as" />
	    </exec>
	</target>
</project>
 

- invoke splinkresource from within your application code, register a few listeners and let it do the work. splinkresource processes your resourcebundles.xml file, loads the neccessary resources for the given locale into the given ApplicationDomain and registres the the loaded resources. Meanwhile it provides you with infomation about the loading progress and upon processing completion you can access the resources within the given ApplicationDomain through the singleton class ResourceProvider.

package sample
{
imports...
public class SampleApplication extends Sprite
{
public function SampleApplication()
{
	// pass the path to the resourcebundles.xml, also pass the locale
	// for which to load resources, also register for various events
	var processor:ResourcebundleProcessor =
	new ResourcebundleProcessor("../xml/resourcebundles.xml", "de_DE");
	processor.register(QueueEvent.ON_ERROR, onProcessError);
	processor.register(QueueEvent.ON_COMPLETE, onProcessComplete);
	processor.register(ResourcebundleProcessorProgressEvent.PROGRESS,
	onProgress);
	processor.start();
}
 
/**
 * Invoked when the resource loading progresses, as you can see you
 * get provided with a lot
 * of information on the load progress
 */
private function onProgress(
e:ResourcebundleProcessorProgressEvent):void
{
	var progress:ResourceProgress = e.getResourceProgress();
 
	var br:String = "\r\n";
 
	trace(progress.getId()+" "+progress.getCurrentItem() +
	" / " + progress.getTotalItems() + br);
 
	trace(
	Math.round(progress.getCurrentItemBytes() / 1024) + "kb / " +
	Math.round(progress.getCurrentItemTotalBytes() / 1024) + "kb " +
	progress.getCurrentItemPercent() + "%"+br);
 
	trace(
	Math.round(progress.getTotalLoadedBytes() / 1024) + "kb / " +
	Math.round(progress.getTotalBytes() / 1024) + " kb " +
	progress.getTotalPercent() + "%"+br);
} 
 
/**
 * Invoked when an error occurs
 */
private function onProcessError(e:QueueEvent):void
{
	trace(e.getErrorMessage());
}
 
/**
 * Invoked when the ResourcebundleProcessor completed its
 * processing
 */
private function onProcessComplete(e:QueueEvent):void
{
	e.getSource().finalize();
 
	testAssets();
	testFonts();
}
 
/**
 * Renders one of the assets defined in resourcebundles.xml to
 * the screen
 * Note that you can access assets trough the
 * ResourceProvider.getInstance().getAssetClassById method
 */
private function testAssets():void
{
	var SplinkAssetClazz:Class =
	ResourceProvider.getInstance().getAssetClassById(
	SampleAssetRegister.SPLINK_ASSET);
	addChild(new SplinkAssetClazz());
}
 
/**
 * Renders some fonts defined in resourcebundles.xml to
 * the screen
 */
private function testFonts():void
{
	var fontData:FontData =
	ResourceProvider.getInstance().getFontDataByType("headline");
 
	var textFormat:TextFormat = new TextFormat();
	textFormat.size = 20;
	textFormat.font = fontData.getId();
	var textField:TextField = new TextField();
	textField.defaultTextFormat = textFormat;
	textField.autoSize = TextFieldAutoSize.LEFT;
	textField.htmlText = fontData.getId();
	if(fontData.getIsSystemFont() != true)
		textField.embedFonts = true;
	textField.x = 0;
	textField.y = height + 20;
 
	addChild(textField);
}
}
}
 

Note that there is a quickstart sample included in the release so you can easily start trying splinkresource.
You can download splinkresource here