Who would have thought that a government institution would be an early adopter of Flex and AIR?

Certainly not many people, and I am one of those pleasantly surprised by the news that the South African Revenue Service (SARS) had done just that!

It’s not everyday that you find the public sector out-pacing the private sector in new technology adoption (well, Flex has been around for a good number of years, so it’s not really that new).

I first learned of SARS’s foray into the Adobe Rich Internet Application (RIA) space when I registered for e-filing on www.sarsefiling.co.za . The e-filing website could use some improvement and I’m confident that it will come in time. Just like private sector banks, SARS has truly grasped the internet’s value proposition and I find that I highly commendable.

In an effort to foster more efficient tax controls, SARS developed two distributed desktop applications for tax practitioners and employers. A third package for individual taxpayers is in the works. The brand name for the suite of applications is equally catchy – e@syFile.

Their efforts went so far as having the e@syFile suite as finalist in both the North American and European Adobe Max awards at the end of 2008! Now that’s what I call palpable success.

To SARS I say:

Thank you and well done!

You have paved the way for adoption of the most exciting technology to come around in ages and I hope the private sector and other government organisations learn from your successes.

I wonder how many other SA organisations are seriously using Flex and AIR in their enterprise application environments. Does anyone know?

I know that there is a heavy-hitter of a stock analysis flex/php/mysql solution doing its thing in Nigeria. It was built for Customs Street Advisors, Lagos by the wizards at Saven Technologies.

While on the subject of tax, here's an interesting fact:

  According to legend, the term "Peeping Tom" was coined from a tax-related matter.

  It is said that Lady Godiva rode naked through Coventry in order to persuade her
  husband not to tax the townspeople so heavily; the only person to look at her as
  she rode by was a man named Tom and Peeping Tom has become a synonym for voyeur.

  (circa 1040-1080)

Here you will find out how to build and test an AMF service inside a Joomla! 1.5 (and above) installation using J-AMFPHP.

UPDATE: This post is still helpful even if
you were not aware of the advantages of
Adobe's Action Message Format (AMF) over XML, REST, etc.

Let’s say you are quite comfortable with building extensions for your Joomla! projects and you now want to take them to the next level by integrating them with Adobe Flex / AIR / Flash.

I assume that you have some basic knowledge of Flex and AIR and you know about all the advantages they can bring to your web applications, and that you know about the advantages of communicating with your remote applications via Adobe’s AMF protocol instead of XML or Web Services (i.e. better data exchange performance, especially for large datasets).

You probably also know about the wonderful AMFPHP script that enables you to leverage Adobe’s powerful AMF protocol for your PHP applications.

If this is you, then you probably know that an AMFPHP extension has been made available by Anthony Mclin under the guise of J-AMFPHP. The great thing about it is that it exposes your whole Joomla! environment to speak AMF with your Flex / AIR applications.

Fantastic!

You think to yourself.

Now I can build Flex and AIR applications for Joomla!
But wait a minute! I have downloaded and installed J-AMFPHP but I have no clue of how it works with Joomla!

Don’t worry, I went through the exact same thing and I want to save you the trouble of jumping through hoops in getting Joomla! to talk to your Flex / AIR environment.

Getting Ready

First, let’s have a look at the J-AMFPHP folder locations that we will be focusing on within your Joomla! folder structure:

[web-root]
    |__________[administrator]
            .........
               [amfphp]
            .........
               [plugins]
                   |______[j-amfphp]

The first folder, [amfphp] contains your gateway script just like you will find in the AMFPHP code. The AMF service browser is missing from the J-AMFPHP installation. I suppose this is for security reasons, however, for testing purposes the service browser is indispensable in testing your Joomla! AMF service code.

If you have not done so, please download the latest version of AMFPHP from SourceForge and extract the [browser] folder from the downloaded zip archive into your [amfphp] folder in Joomla! We will use the service browser to test our sample AMF service that we will build shortly.

UPDATE: Important - if you launch your service browser at this
stage you will get a faultCode = “AMFPHP_CLASSPATH_NOT_FOUND” error.

That's because the service browser needs an additional step to work properly.
Here's what you should do.

Find the [services] / [amfphp] folder inside your downloaded AMFPHP zip archive and extract this folder to [plugins] / [j-amfphp] in your Joomla! installation.

The service browser files should only be used in development environment. Leaving them in place in your production environment will allow anyone to view your AMF service composition, please remember to remove them before you go live.

Time For Action

Let’s get cracking and build our first AMF service class in Joomla!

Let’s name our service class “HelloJoomla” , which is a spin on the classic “Hello world!” application.

Under the [plugins] / [j-amfphp] folder in Joomla!, create a new folder named [hello_joomla] and underneath that create a file named “HelloJoomla.php”. This file will contain your AMF service class code.

Let’s run a little test to make sure that we are still on track before we dive into coding the service class.

Launch your web browser and point to:

http://url/to/your-joomla-installation/amfphp/browser/index.html (e.g. http://localhost/amfphp/browser/index.html)

The typical bluish Flex background should come up. After loading you should see two items on your leftmost panel i.e.

[+] amfphp
[+] hello_joomla

Clicking on the [+] sign next to the “hello_joomla” item will show something like (c) HelloJoomla.

So far so good. We’re ready to rumble.

*If you do not get these results, then you should step back and see whether you went through everything correctly.

Coding The AMF Class

Fire up your favourite code editor and open [plugins] / [j-amfphp] / HelloJoomla.php for editing.

Insert the following code:

<?php

//make sure this request comes from within the joomla framework
defined( '_JEXEC' ) or die( 'Restricted access' );

/**
 * An example "Hello World" class for AMFPHP.
 * Whatever you type here will show up in your AMFPHP browser
 * It is good practice to document your class and functions
 * (methods) this way to make it easier on anyone that
 * might want to use your code later, yourself included.
 */

class HelloJoomla
{
    /**
    * A basic function to demo AMFPHP Services
    * Takes in your name as a parameter and
    * returns a greeting message with your name on it
    * @param Name
    * @returns A text string with a greeting message
    */
    public function greetMe($name) {
        $text = "Hello ". $name .", you have just created your ";
        $text .= "first Joomla AMF service for Flash/Flex Remoting.";
        return $text;
    }
}
?>

As you can see, this is exactly the same way in which you code your PHP classes elsewhere!
All your wonderful “J” methods are now accessible from here e.g.

$db =& JFactory::getDBO();

Lastly, go to your web browser again and open / refresh
http://url/to/your-joomla-installation/amfphp/browser/index.html

Drill down to click on (c) HelloJoomla. You will see your “greetMe()” method on the right hand pane. Note how the comments that you included in your PHP code show up .

Type in your name in the space provided and click on “call”. Watch for the output underneath.

You’re unstoppable now! Your AMF gateway is up-and running. Your gateway access url from within your Flex / Flash / AIR environment will be

http://url/to/your-joomla-installation/amfphp/

Have fun integrating your Joomla! environment with Flex, Flash, And AIR!

Update: Create a "HelloJoomla" Adobe AIR Application in HTML and JavaScript  link