Resources

#Localization

The recommended approach for localizing Parsley based applications is very different dependending on whether you are using Flex or not. For Flex Applications Parsley integrates with the Flex ResourceManager. For Flash Applications Parsley offers its own Localization Module. In fact that module is the only part that survived from version 1 of the framework, albeit with some major refactorings.

##ResourceBindings

This is the only Parsley Localization feature that works the same way in Flex and Flash Applications, so we will explain it first.

You can place [ResourceBinding] metadata tags on properties of objects managed by the IOC Container:

[ResourceBinding(bundle="errorMessages",key="fileNotFound")]
public var message:String;

The tag has the following effects:

• When the object is instantiated the container will fetch the message with the specified bundle name and key from the ResourceManager and inject it into the property. This step happens while other injections are processed and before the methods marked with [Init] get invoked. In case the bundle is not yet available at the time the object is initialized the resource may get injected at a later time.

• When Flex ResourceManager is updated (Flex Applications) or the currentLocale property of the Parsley ResourceManager gets changed (Flash Applications) the value for that property will be updated automatically.

For Flex Applications it is recommended to use this feature primarily for objects defined in Parsley configuration classes or files (MXML or XML). For View Components, even when they connect to the Parsley IOC Container like described in Dynamic View Wiring, you could just stick to normal Flex Binding syntax like this:

<s:Label text="{resourceManager.getString('RegistrationForm','city')}"/>

This way your localized View Component does not depend on the Parsley Framework at all. The Parsley [ResourceBinding] tag still may come in handy for other localized objects.

For Flash Applications the [ResourceBinding] tag is usually the recommended approach for localizing components.

In most cases the Parsley Framework will automatically detect if it is used in a Flex or Flash Application depending on how Parsley is initialized. So the adapter that connects the class that processes the [ResourceBinding] tags to either the Flex or Parsley ResourceManager will be set automatically. There are a few exceptions described in the following sections.

Like for most other Parsley metadata tags there are corresponding MXML and XML tags that could be used alternatively:

#####MXML Example

<Object type="{SlideShowController}">
    <ResourceBinding property="message" bundle="errorMessages" key="fileNotFound"/> 
</Object>

#####XML Example

<object type="com.bookstore.catalog.SlideShowController">
    <resource-binding property="message" bundle="errorMessages" key="fileNotFound"/>  
</object>

##Localized Flex Applications

For Flex Applications the [ResourceBinding] tag described in the previous section is currently the only integration feature that is available (and probably the only feature you'll need in a Flex environment). Otherwise you should use the Flex Localization features the same way like you would without using the framework. There is extensive documentation available in the Flex Livedocs

We might think about expanding the Flex Module Support to include management of dynamically loaded Flex Resource Modules which are associated with a particular Flex Module. But we will wait for feedback on this and see how the Module Support gets used.

#####Initializing the ResourceBinding metadata tag support for Flex

Whenever you are using the FlexContextBuilder to initialize your MXML-based Parsley Configuration the framework will automatically set the required adapter for you. In rare cases where you would build a Parsley Flex Application but not use MXML configuration at all (for example confining yourself to use XML configuration files) you'd need to set the adapter manually:

ResourceBindingDecorator.adapterClass = FlexResourceBindingAdapter; 

##Localized Flash Applications

For Flash Applications Parsley offers its own Localization Module. This is the oldest part of the framework that already existed in early AS2 versions of the framework. But it's still a good solution if you are not using Flex. This section describes how you configure and use this module.

This functionality is not part of Parsley Core. The extension is available on the Parsley download page. Simply add the SWCs from the download to your classpath.

###Configuration

Parsley includes a separate XML configuration namespace that you can use to declare the bundles that the framework should load when initializing the IOC Container:

<objects xmlns="http://www.spicefactory.org/parsley" 
    xmlns:res="http://www.spicefactory.org/parsley/flash/resources"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.spicefactory.org/parsley 
      http://www.spicefactory.org/parsley/schema/3.0/parsley-core.xsd
    http://www.spicefactory.org/parsley/flash/resources 
      http://www.spicefactory.org/parsley/schema/3.0/parsley-resources-flash.xsd">
    
    <res:resource-manager id="resourceManager">
        <res:locale language="en" country="US"/>
        <res:locale language="de" country="DE"/>
        <res:locale language="fr" country="FR"/>
    </res:resource-manager>
	        
    <res:resource-bundle id="tooltips" basename="messages/tooltips" localized="true"/>

    <res:resource-bundle id="alerts" basename="messages/alerts" localized="true"/>

    <!-- other object definitions ... -->
    
</objects>

In the example above we declare a ResourceManager and the supported locales. In a modular application you should only declare a single ResourceManager instance (usually in the main application Context initialized on application start). You can then add any number of ResourceBundles in the main Context as well as child Context configurations. In the example above we add two bundles, one for tooltips and one for alerts.

With the basename attribute you specify how Parsley concatenates the actual names of the files it attempts to load. For the basename messages/tooltips and the active locale en_US it would look for the following files:

• messages/tooltips.xml
• messages/tooltips_en.xml
• messages/tooltips_en_US.xml

This way you could keep messages that differ for each country in tooltips_en_US while adding messages which are the same for each country with English messages to tooltips_en.xml. You can reduce the number of files Parsley attempts to load though: When you set the ignore-country attribute to true the third file from the list will be omitted, if you set the localized attribute to false the second one will be omitted, too.

Since this is an extension it has to be initialized explicitly before using the XmlContextBuilder:

FlashResourceXmlSupport.initialize();

###XML Resource Bundle Files

The structure for the bundle files themselves is quite trivial:

<resource-bundle 
    xmlns="http://www.spicefactory.org/parsley/flash/resource-bundle"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.spicefactory.org/parsley/flash/resource-bundle 
        http://www.spicefactory.org/parsley/schema/3.0/parsley-resources-flash-bundle.xsd"
    >
    <resource key="tooltip.save">Saves the file</resource>
    <resource key="tooltip.open">Opens a new file</resource>
    <resource key="tooltip.saveAs">Saves the file with a new name</resource>
    <resource key="tooltip.delete">Deletes the file</resource>
</resource-bundle>

###Switching the active Locale

If you want to switch the active locale at runtime (and thereby trigger updates for properties marked with [ResourceBinding]), you can inject the configured ResourceManager into any object and set its currentLocale property:

[Inject]
public var resourceManager:ResourceManager;

public function switchLocale (lang:String) : void {
    resourceManager.currentLocale = new Locale(lang);
} 

This will trigger the loading of the XML bundle files associated with that locale. The ResourceManager will dispatch a LocaleSwitchEvent.COMPLETE event when the loading process has completed. But in many cases you don't even have to listen for that event as the ResourceBindings will update automatically. You only need this event if switching the locale involves more than just updating property values.