LanguageManager

Kind of class: public class
Package:
Inherits from:
  • EventDispatcher
Classpath: org.asaplibrary.management.lang.LanguageManager
File last modified: Sunday, 15 May 2011, 21:07:49
Class for managing language dependencies in an application. For text, the language dependent texts are expected to be in an xml per language, with the following structure: 
<?xml version="1.0" encoding="UTF-8"?>
<texts>
<text id="helloWorld">Hello World</text>
<text id="helloBoldWorld">with bold Hello]]></text>
<text id="helloHTMLWorld" html="false">with visible html tags]]></text>
<text id="helloWorldInBrackets" html="false"></text>
</texts>
The 'id' attribute is mandatory, and has to be a String. It cannot contain "_" (underscore). The 'html' attribute is optional. If left out, text is rendered as HTML text; any other value than "false" is seen as true. When false, the text is set directly into the text field, and any html tags are ignored. In case the text contains xml characters, the text has to be wrapped in a tag. The id is expected to be unique. When it isn't, the last item is taken. The xml file containing the language dependent texts has to be loaded with the method loadXML. When loaded and parsed, the LanguageManager sends an event of type LanguageManager.EVENT_LOADED. Subscribe to this event if you wish to be notified. No event is sent when the loading fails, only a Log message of level ERROR is output. Once an xml file has been loaded, data is available by id through getTextByID and getDataByID. Since the LanguageManager is a Singleton, the language dependent data is available throughout your application. However, the LanguageManager also contains a mechanism for automatic assignment of data. To use this functionality, use the provided class MultiLanguageTextContainer, or write your own implementation of IMultiLanguageTextContainer. When writing your own class, allow for a way to determine the id of the text that is to be used by a specific instance for your class. In case of the MultiLanguageTextContainer class, this id is retrieved from the name of the movieclip instance to which the class is linked, by taking everything after the last underscore and converting to a number. So "myText_1" gets the text with id=1. Once the id is known inside your class, add the instance to the LanguageManager with addContainer, providing the id and the instance itself as parameters. If data has been loaded, it is provided to the instance immediately. Whenever new data is loaded, the LanguageManager calls "setData" on each instance that was added, thereby updating language dependent text instantaneously. A good spot to add an instance to the LanguageManager is when Event.ADDED is received. Make sure to remove it again when Event.REMOVED is received, to allow for proper memory management. This also makes sure that the instance keeps its text when subject to animation key frames. Instances can share the same id, and thereby have the same text. By default, the LanguageManager returns an empty string (or provides an empty string in the data) when a requested id is not found. This has two drawbacks:
  • The textfield becomes effectively invisible since there is no text in it
  • Formatting of the textfield (such as weight or alignment) may be lost when the textfield is cleared
To allow for easier debugging, the flag generateDebugText can be set. If an unknown id is requested, the returned text will be ">> id = #id", where #id is replaced with the actually requested id. This makes it easier to find missing texts from the xml files.
Example
    • Loading an xml file into the LanguageManager, specifying a language code to be used in determining the name of the xml file to be loaded. 
      // @param inCode: 2-letter ISO language code;
// will be added to filename.
// Example: with parameter "en" the file "texts_en.xml" will be loaded.
private function loadLanguage (inCode:String) : void {
var lm:LanguageManager = LanguageManager.getInstance();
lm.addEventListener(LanguageManager.EVENT_LOADED, handleLanguageLoaded);
lm.loadXML("../xml/texts_" + inCode + ".xml");
}
private function handleLanguageLoaded () : void {
Log.debug("handleLanguageLoaded: Language file loaded.", toString());
}
    • Assigning a text to a textfield manually from anywhere in your code: myTextfield.text = LanguageManager.getInstance().getTextByID(23);
    • A class that gets a random text from the first 10 texts of the LanguageManager each time it is loaded: 
      class MyText extends MovieClip implements IMultiLanguageTextContainer {
private var mID:Number;
private var myTextField:TextField;
public function MyText () {
addEventListener(Event.ADDED, handleAdded);
addEventListener(Event.REMOVED, handleRemoved);
}
public function setData (inData : TextItemData) : Void {
setText(inData.text, inData.isHTML);
}
public function setText (inText:String, inIsHTML:Boolean = true) : Void {
if (inIsHTML) tf_txt.htmlText = inText;
else tf_txt.text = inText;
}
private function handleAdded (e:Event) : Void {
mID = Math.floor(10 * Math.random());
        
LanguageManager.getInstance().addContainer(mID, this);
}
    
private function handleRemoved (e:Event) : Void {
LanguageManager.getInstance().removeContainer(this);
}
}

Summary

Constructor
Constants
  • EVENT_LOADED : String
    • The event sent when the language xml has been loaded and parsed
Instance properties
  • generateDebugText : Boolean
    • Flag indicates whether items show their id as text when no text is found in the xml.
Class methods
Instance methods

Constructor

LanguageManager

function LanguageManager()

singleton constructor. Do not use externally.

Constants

EVENT_LOADED

static const EVENT_LOADED:String = "onLanguageLoaded"

The event sent when the language xml has been loaded and parsed

Instance properties

generateDebugText

generateDebugText:Boolean(write)

Flag indicates whether items show their id as text when no text is found in the xml. When false, an empty string is returned when no text is found.

Class methods

getInstance

static function getInstance() : LanguageManager
Returns
  • The singleton instance of the LanguageManager

Instance methods

addContainer

function addContainer(inID:String, inContainer:IMultiLanguageTextContainer) : void

Add a multi-language container to the LanguageManager. If data has been loaded, the container will receive its data immediately. If the container had been added already, it will not be added again.

Parameters
inID :the id to be associated with the container
inContainer:instance of a class implementing IMultiLanguageTextContainer

addText

function addText(inData:TextItemData) : void

Add text for a specific ID to the language manager. Set the text in any IMultiLanguageTextContainer instance associated with that id.

Parameters
inData:TextItemData instance containing necessary data.

getDataByID

function getDataByID(inID:String) : TextItemData

Retrieve text data

Parameters
inID:the id for the text to be found
Returns
  • the text data with the right text if found, with an empty string if generateDebugText is set to false, or with '>> id = ' + id if generateDebugText is set to true

getTextByID

function getTextByID(inID:String) : String

Retrieve a text

Parameters
inID:the id for the text to be found
Returns
  • the text if found, an empty string if generateDebugText is set to false, or '>> id = ' + id if generateDebugText is set to true

loadXML

function loadXML(inURL:String) : void

Load language XML

Parameters
inURL:full path of the xml file to be loaded

removeContainer

function removeContainer(inContainer:IMultiLanguageTextContainer) : void

Remove a multi-language container from the LanguageManager

Parameters
inContainer:previously added instance of a class implementing IMultiLanguageTextContainer

toString

override function toString() : String
Overrides
  • EventDispatcher.toString