Flex localization with Resource Bundles

Working with resource bundles in Flex is (surprise, surprise) relatively easy and pretty cool. They’re a great way to separate content from code and localize your flex apps. You have the choice to either compile the different locales statically into the app, or load them dynamically using the ResourceManager.


Adding support for different locales


First thing you need to know is that, Flex techinically doesn’t support most locales right “out of the box”. In order to support more, it needs to create a bunch of framework resource SWCs for each locale you want to use. This is really easy though. There is a command-line utillity called copylocale that will handle creating those for you…all you need to do is tell it which locale you want to create. Pop open a terminal and navigate to your flex SDK directory, and run this command, substituting “fr_FR” for the locale you wish to create:

./bin/copylocale en_US fr_FR

This will generate all the asset files the framework needs. You’re done with this part.


Adding resource bundles


To add resource bundles, there are a few steps you need to follow. Each step will be discussed further below:

  • Create a source directory in your project for each locale you wish to use. Normally, it would go something allong the lines of src/locale/en_US, src/locale/en_GB, etc.
  • Create a properties file that will contain the resources to be localized. This property file is a simple text file containing key/value pairs. Mostly it’s going to contain strings to be localized, but can also contain ClassReferences and Embedded assets, just like a style swf.
  • If you want to compile all the locales into the app, update the compiler settings to include the locales and source paths into the app.
  • If you would like to load the additional locales on demand, create a resource swf to be loaded in by calling ResourceMananger.loadResourceModule().


Creating the properties file


The properties file is what the compiler uses to make the resource bundle. In fact, the compiler parses that file and creates a subclass of ResourceBundle for use in the app. It is made up of simple key/value pairs:

mytitle=Title
myothervalue=This is some other text we want to localize

You don’t enclose the strings in quotes, and any whitespace before the value is trimmed (which is great for keeping your properties file nice and neat). Whatever you name the file will be the name of the resource bundle: a file named “strings.properties” becomes the “strings” resource bundle in the app. One important note, the text file must be encoded in UTF-8.

Telling the flex compiler which bundles to include in the app
In order for flex to know which resource bundles you plan on using in the app, you need to explicitly tell it using metadata tags. In mxml it looks like:

  1. <mx:Metadata>
  2.      [ResourceBundle("strings")]
  3. </mx:Metadata>

and in actionscript it looks like this:

ActionScript
< view plain text >
  1. [ResourceBundle("myResources")]


Specifying which locales to compile into the app


If you are going to statically compile all the locales you want to use in the app, you simple add a couple of compiler options:

-locale=en_US,fr_FR -source-path=locale/{locale}

if you get a warning about the source path overlapping after changing those options, you can also add the compiler option -allow-source-path-overlap=true.

Now when you compile your app, flex will create resource bundles for each of the locales.


Creating resource modules to dynamically load in


If you would like to load different locale bundles on the fly, you need to comile swfs for each locale. Unfortunately, you cannot do this within Flex Builder, you must use the command line. Luckily, this is also easy, though it is a two step process.

First, we need to find out exactly which bundles to include into the module swf. The way we do this is by compiling our app with no locale specified, and including the compiler option -resource-bundle-list:

mxmlc -locale= -resource-bundle-list=myresources.txt MyApp.mxml

Note that the above example using the command line, but you can do this part in Flex Builder by adding additional compiler options under the project preferences (Flex Compiler > additional compiler arguments). Now when you compile the app, a text file will be output that contains a list of bundles to include in the module:

bundles = strings collections containers controls core effects skins styles

Note the “strings” bundle. Flex knew to include this because we specified it in the metadata.

What do we do with that list? That’s the second step. We go back to the command line, and use that list as part of a the -include-resource-bundles compiler argument when we compile the module swf. Open a terminal window, navigate to your projects directory, and use the following command:

mxmlc -locale=en_US -source-path=locale/{locale} -include-resource-bundles=strings,collections,containers,controls,core,effects,skins,styles -output en_US_resources.swf

You can customize the -output file name to your liking, and be sure the -source-path arguments points to the directory which contains the properties file. Repeat this step for each locale you want to compile, changing the -locale and -output options accordingly.


Using the resource bundles


Using the resource bundles is pretty easy. Wherever you want a string localized, you can do two things:

If you plan on only localizing once when the app starts, you can use the @Resource() compiler directive wherever you want to use the text. You simply pass the name of the resource bundle, and the key which you wish to use:

  1. <mx:Label text="@Resource(bundle='strings', key='mytitle')" />

If you plan on dynamically updating the content during the life of the app (for example, allowing the suer to set the locale), you can use bindings and the ResourceManager singleton to specify the strings:

  1. <mx:Label text="{resourceManager.getString('strings', 'mytitle')}" />

When using bindings, the value of the string will be updated once you set the ResourceManager.localeChain property, which is an array containing the locales to use, in cascading order. For example, if you specify [‘fr_FR’, ‘en_US’], the ResourceManager will first look for the key in the fr_FR bundle. If that key is not found, it will use the key from the en_US bundle instead. You can use just a single locale in the array if you wish.


Loading additional resource bundles


Again, pretty simple. you can use ResourceManager.loadResourceBundles() to load the resource module swf containing the new locale. One that locale is loaded, you can set the ResourceManager.localeChain property to use the new locale.

For some additional info, the Runtime Localization article on Labs is a great resource. Also see:

http://www.herrodius.com/blog/123
http://soenkerohde.com/2008/07/flex-localization/
http://hillelcoren.com/2008/09/12/resource-bundles-in-flex-wo-lots-of-extra-code/ ( for a nice ResourceManager utility class)

TransformManager fix for Mac Firefox

This post is specifically about Jack Doyle’s (aka greensock) awesome TransformManager tool, but the overall idea solves the issue of mouse up events when releasing the mouse button outside the stage in Mac Firefox.

In case you didn’t know already, in Firefox on the Mac there is a problem with releasing the mouse outside the browser window. If you click within the swf, then while holding the mouse button down, drag outside the browser window, then release the mouse button, Mac FF doesn’t hear the MOUSE_UP event. Obviously, this is a problem for the TM because if you do that, when you bring the mouse back over the swf, the MOUSE_MOVE handlers are still firing, and the selection is still following the mouse, event though you’ve released the mouse button.

The key to the whole fix is that in Mac FF, the MOUSE_LEAVE event will not fire until you release the mouse button, if it was being held down when you drag out of the swf.

So to solve this I tweaked the TM class as follows:

add a helper method to determine if it is mac ff, and one to dispatch fake mouse up events (you’ll see why in a bit)

ActionScript
< view plain text >
  1. // on Mac Firefox, if you click the mouse button,
  2. // then drag out of the browser window and release the mouse button,
  3. // the MOUSE_LEAVE event doesn't fire doesn't fire until the mouse button is released.
  4. // Knowing that we can properly handle MOUSE_UP events for moving, resizing, etc.
  5. private function get isFirefoxMac():Boolean{
  6.             // this is adapted from some flex code
  7.             var browserUserAgent:String = ExternalInterface.call("navigator.userAgent.toString");
  8.             var browserPlatform :String = ExternalInterface.call("navigator.platform.toString");
  9.  
  10.             var isFirefoxMac:Boolean = (browserUserAgent && browserPlatform &&
  11.                 browserUserAgent.indexOf("Firefox") > -1 && browserPlatform.indexOf("Mac") > -1);
  12.             return isFirefoxMac;
  13. }
  14.  
  15.  
  16. private function dispatchFakeMouseUpEvent():void{
  17.             var mevent:MouseEvent = new MouseEvent(MouseEvent.MOUSE_UP, true, false, _stage.mouseX, _stage.mouseY);
  18.             _stage.dispatchEvent(mevent);
  19. }

Then, I made a slight modification to the onPress* methods, to check if it isFirefoxMac, if so also listen for the MOUSE_LEAVE event.

ActionScript
< view plain text >
  1. private function onPressRotate($e:MouseEvent):void {
  2.                        
  3.                         //... whatever pre-existing code ...
  4.                        
  5.                         _stage.addEventListener(MouseEvent.MOUSE_MOVE, onMouseMoveRotate, false, 0, true);
  6.                         _stage.addEventListener(MouseEvent.MOUSE_UP, onReleaseRotate, false, 0, true);
  7.                        
  8.                         if ( isFirefoxMac ){
  9.                                     _stage.addEventListener(Event.MOUSE_LEAVE, onMouseLeaveRotate, false, 0, true);
  10.                         }
  11.  
  12.                         // other stuff...
  13.             }
  14. }

Each type of press gets an associated onMouseLeave* event (onMouseLeaveScale, onMouseLeaveRotate, etc).

ActionScript
< view plain text >
  1. private function onMouseLeaveRotate(event:Event):void{
  2.             _stage.removeEventListener(Event.MOUSE_LEAVE, onMouseLeaveRotate);
  3.             dispatchFakeMouseUpEvent();
  4. }

Actually, the onMouseLeaveMove handler is slightly different since onReleaseMove() doesnt need a mouse event:

ActionScript
< view plain text >
  1. private function onMouseLeaveMove(event:Event):void{
  2.             _stage.removeEventListener(Event.MOUSE_LEAVE, onMouseLeaveMove);
  3.             onReleaseMove(event);
  4. }

I also added a line to the removeParentListeners() method to remove the onMouseLeaveMove handler:

ActionScript
< view plain text >
  1. _stage.removeEventListener(Event.MOUSE_LEAVE, onMouseLeaveMove);

That’s just about it, just one more small tweak to the TransformItem class. You need to do the same routine for the TransformItem.onMouseDown() method: Check for Mac FF, if so add a MOUSE_LEAVE handler, and in the onMouseLeave() method just call the onMouseUp() method.

Error installing AIR app

I was trying to install an AIR app I’m working on, and during the install process kept getting hit with this error:

The application could not be installed because the AIR file is damaged. Try obtaining a new AIR file from the application author.

I tried a few solutions I came across (one involving deleting the /var/folders/zzz directory and rebooting, and another about building an .airi file and including that), but they didin’t work. What did work for me was to simply un-check the “timestamp option” when exporting a digital certificate during the export release build process.

The solution, along with a few others people were having was found here.

Have you checked out Adobe Labs recently?

I heard about Adobe Story this morning, so I headed over to Adobe Labs to check it out. While I was there I found a few more interesting projects I haven;t yet heard of:

  • Genesis : Genesis is the code-name for a new product initiative at Adobe with the objective of joining business applications, documents and the web on every knowledge workers desktop with integrated collaboration capabilities. Using the very intuitive interface of the Genesis desktop client (built on Adobe AIR) knowledge workers are able to create custom workspaces combining views into business applications, analytics, web sites and documents.
  • Wave : Adobe® Waveâ„¢ is an Adobe AIR application and Adobe hosted service that work together to enable desktop notifications. It helps publishers stay connected to your customers and lets users avoid the email clutter of dozens of newsletters and social network update messages. Adobe Wave is a single web service call that lets publishers reach users directly on their desktop: there’s no need to make them download a custom application or build it yourself.
  • Patch Panel: Adobe is pleased to offer our third-party developers and the larger Adobe Flex® development community this preview of PatchPanel, a first glimpse at combining the dynamic control of ActionScriptâ„¢ with the power of Adobe’s Creative Suite®. Similar to Adobe’s ExtendScript environment for the Creative Suite, PatchPanel provides developers deep access into controlling the Creative Suite through independently-created scripts. PatchPanel provides the necessary link between the Flex development environment and the Creative Suite’s internal controls, allowing existing ActionScript developers the ability to apply their skills toward enhancing the creative process, as well as inviting a new generation of creative minds to explore the flexibility and automation possible with ActionScript.

    PatchPanel is a Flex library and set of services that make it possible for Shockwave® Flash® (SWF) files to work as Adobe Creative Suite CS3 and CS4 plug-ins. Flex developers can include this Flex library in their projects in order to create Flash plug-ins that access the ExtendScript Document Object Model (DOM) of Creative Suite applications through ActionScript objects.

There’s a bunch more too….looks like we’ve got some pretty decently cool stuff on the way from Adobe. That’s not even counting Flex 4, which looks like it’s shaping up to be quite awesome!

Flash Builder

Everybody knows by now that Flex Builder is now Flash Builder, which i think is a great move. With all the chatter about it, one thought just keeps popping up for me: how much of a non-impact this is on my daily work and career. Yeah, I’ve gone through the whole thing about explaining flex to clients, but for the most part, I haven’t really run into issues where clients/employers are confused over the IDEs.

The “New RegFly.com”…seriously???

Got an email today about the “new RegFly.com”….ugh. That’s kind of like hearing about “the new Enron”. If you don’t remember RegisterFly read about them here, but long story short they were one of the worst domain name registrar scandals, ultimately losing their ICANN accreditation and causing me and plenty of others A LOT of grief. The fact that they are using a different domain name to avoid having to display the court-ordered notice about losing their accreditation speaks volumes to the fact that things haven’t changed at all. Please spare yourself some agony and avoid them like the plague.

DockableFlex – Nice!

Wow, just came across DockableFlex:

DockableFlex is an open source component library based on Adobe Flex 3.
It provides basic dock support for the Panel Component.

Looks pretty slick, if you’ve ever tried dragging tabbed panels around in photoshop or in the Eclipse IDE, you get the idea.