Christophe Herreman

Here are some good things to know when using class mapping with AMFPHP. As an example, imagine working on an application that handles users through a UserVO value object. Here's what the PHP and the AS2 class look like.

The UserVO class in PHP

This class is in a "vo" subfolder of the "services" folder (in your AMFPHP installation dir).

The UserVO class in AS2

This class is in the namespace "com.domain.vo.UserVO".

Flash to PHP

Sending VO's from Flash to PHP is quite simple. Just add the parameters in the "arguments" key. Use the fully qualified classpath of the class on the server side and make sure you set "required" to true;

PHP to Flash

Watch out here! You can leave out the "returns" key from the method entry in the methodtable. When you do that, AMFPHP will return the name of the class for you. The thing to know here is that in PHP4 the classname will be returned in lowercase, while in PHP5 it will be returned in its original format of lower- and uppercases. Note that this does not return the fully qualified classpath, but just the classname. "uservo" vs. "UserVO".

Here's a quote from the "get_class" function docs.

In PHP 4 get_class() returns a user defined class name in lowercase, but in PHP 5 it will return the class name in it's original notation.
http://be.php.net/manual/en/function.get-class.php

This is not recommended because Object.registerClass() will fail because it is case-sensitive. The best way to get Object.registerClass() to work is to pass in the name of the class in the "returns" key and then use that same name in lowercase to register the class in Flash.

And then in Flash...

That's it, cheers!

[Update] I must have missed something here: the "returns" string is always passed to Flash in lowercase. So remember that when you use Object.registerClass().

Another update to my ARP lab. I have been thinking about localization for a while but didn't really have the time to work something out untill now. Continuing on the e-learning project we are working on, we came to the point where we needed to have multi-lingual user interfaces. So why not write a generic way in the ARP framework instead of having a custom implementation for our project.

Download the sample files here.

How it works (Nils, you won't like this!)

Each locale has its own XML file that holds the localized strings. In the application, there is a LocaleManager class that knows what the current locale is and, when a new locale is set, will load and parse the localized strings. This loading and parsing happens in a class called ResourceBundle, which "bundles" the "resources", the localized strings, into a collection.

The XML files look like this.

This is pretty much the same idea as the XML files to configure your ARP application with the AppSettings class. Each string has a key and a value. Notice that the keys should be the same for the different resource files. The XML files are saved with the following naming convention: they start with "resources_" and a string representation of the locale is appended to it. Example names are "resources_en.xml", "resources_du_BE.xml" or "resources_du_NL.xml". As you can see, we have a common resource file for English strings and 2 more specific ones for Dutch. One for Belgium and one for The Netherlands.

When the application starts, each view/form that is interested in localized content should:
- register as a listener with the LocaleManager
- implement the LocaleListener interface which makes it possible to be added as a listener to the LocaleManager and which forces the form to implement the localeChanged() event handler.

From the example, here is what the RegistrationForm class looks like.

Notice that a new locale is created when the user chooses a different language from the combobox. Here the locale is created through a static method called fromString() because we allready have all the locale details we need in a string. You can ofcourse also instantiate a new locale by calling the Locale's constructor and passing in the language and the region. After creating the locale, we assign it to the LocaleManager through the setLocale() method. This will create a new resourcebundle and load the localized content. As you can see, I implemented it in a way so that you don't have to take care of the resourcebundles yourself. The LocaleManager does it for you. Finally, when the content is loaded and parsed, the localeChanged() method gets called. This is the method you use to update your view. You can fetch the localized strings with the getString() method on the LocaleManager. When the string is not found in the resourcebundle, an error is thrown.

Download

You can download the example here. The following classes should be added in the package "org.osflash.arp.util":
- Locale
- LocaleListener
- LocaleManager
- ResourceBundle

Related content:

- Configuring your ARP application

25 candles on the birthday cake today, I'm getting old.

I was discussing the use of typesafe ENUM's with a co-worker today when we got to a point where we couldn't agree on how to implement some of the behavior. We have this AssessmentItemType class that holds different types of assessmentitems like MULTIPLE_CHOICE, FILL_IN_TEXT, DRAG_AND_DROP_WITH_TEXT, etc that looks like this (some of the content is stripped).

These types are assigned to an instance of the AssessmentItem class when we are parsing the assessmentitems from XML files. But during the parsing, we need a way to look up the correct assessmentitemtype in the ENUM. All we know about the type of the assessmentitem is its name, "multipleChoice" for instance, or its id, "1" for instance. The id is used for backward compatibility with the previous system.

The first solution was to create a separate helper class to look up the assessmentitemtype by looking into the available types, exposing the TYPES array. We figured we needed a getByName() and a getById() method in order to look up the type both ways. The second solution was to add these 2 methods to the AssessmentItemType class itself and not to create a separate class. I personally thought that the second solution was the best because creating a separate class to look up values would be overkill in my opinion. We were also showing some the class' internals by making the TYPES array public in order to access it from the helper class. We couldn't end the discussion because my co-worker had to catch a train, so I was wondering what you guys were thinking.

PS: This might not be a critical design question, but both solutions might have there pros and cons where we didn't think of.

There was a recent post on the ARP mailinglist about how an application could be configured. Since there is (still) not a uniform way of doing so in ARP I thought I'd share the solution I came up with. The whole idea is based on an XML file that contains key/value pairs, pretty much like the appsettings implementation in .NET. The XML file, called "appsettings.xml", gets loaded in the ArpApplication class. This is a new class I introduced to the framework that all Application forms extend. The Application form being the applications point of entry.

Before diving into any code examples, please note that these are my personal additions to the framework and that they are not in any official release. Other additions from the ARP Advisory Committee members are available as well: Peter Hall, Jesse Warden, Shannon Jackson and the ARP labs overview.

appsettings.xml

Here's an example of the appsettings.xml file. As you can see all entries consist of a key/value pair. In order for your application to find the appsettings file, you should either:
- name it "appsettings.xml" and put it in a folder where your swf can read it without changing folders.
- use flashvars in the html file that embeds the swf and create a var called "appSettingsPath". Point its value to the appsettings file in any directory. Note that the name "appsettings.xml" can be changed then and that it can even be a serverside page that generates a dynamic config.

To access one of the values, use the AppSettings class.

Note that these values can only be fetched when the appsettings file has been loaded and parsed. Therefore your Application class needs to extend the ArpApplication class. To know when the loading and parsing is done, you need to implement the onAppSettingsLoad() method. This is a (abstract) method in ArpApplication that gets called when the values have been parsed.

In the following code we set the backgroundcolor of the application to a value in the appsettings and then call the show() method on 2 subforms: menuForm and contentForm.

I overwrote the show() method in these subclasses because they also need values from the appsettings file. And now that I think about it, doing so isn't the best idea. I can see how pretty intense operations are called everytime we hide/show the forms. Either letting the application form dispatch events when the settings are loaded could be a better solution or if there was any way of intercepting the onLoad() handler of the subforms, that could be a good solution too. That way, we could trigger the onLoad() handler on the subforms only when the appsettings are loaded. (In fact, I have been trying to catch the onLoad() before it fires without success. So if anyone knows, please let me know.)

Here is a zip file with a small example and the ArpApplication and the AppSettings class.
Put the AppSettings class in the package org.osflash.arp.config.* and the ArpApplication class in org.osflash.arp.view.*