UPDATE: Enhanced code styling 30 June 2009

This post will show you how to write a basic AIR application in HTML/JavaScript and get it to speak AMF with your Joomla! 1.5 (and above) installation.

If you’re just starting out, see how to setup and run J-AMFPHP in Joomla first. We’ll be creating our AIR application based on that example.

Why HTML and JavaScript?

I’ve seen some tutorials on the web that dive straight into FlexBuilder’s MXML layouts and AS3 classes as a start. Although the thinking behind MXML is to mimic (X)HTML, I feel that starting out with (X)HTML is the easiest way for a web developer to get acquainted with the world of Adobe AIR (and Flex). With this combination you also have the ability to access AS3 libraries from JavaScript, which I think is great.

For other reasons that would fill a whole post, I prefer building AIR applications in XHTML and JavaScript.

The method we are going to use is just one of the many ways to build AIR applications from the free Adobe AIR SDK. You can build an HTML/JavaScript AIR application from only a text editor and the command prompt / terminal window, or from DreamWeaver, or the Flash IDE, or FlexBuilder, or from Eclipse with the proper plugins.

The mashup possibilities are endless!

For this example I use Aptana Studio to build our “HelloJoomla” AIR application. (You can also do this from the command-line/text editor combo or from DreamWeaver).

In a hurry? Download Source [zip - googlecode]

Screenshots

Our application will look like this when it’s run.

Executing HelloJoomla

The AMF Response

Creating The Application

In Aptana Studio, create a new application and select “Adobe AIR Project” as the application type. Name it “HelloJoomla” and accept all the default settings. (I’m not going to go into this as it’s fairly straightforward to do and there are plenty of examples around).

After this step, Aptana Studio will open a file called “HelloJoomla.html” for editing. This is your main application file which resides in the root folder of your application.

By default, “HelloJoomla.html” will include the AIRAliases.js JavaScript file. This file simply maps and shortens some core AIR and ActionScript 3 functions.

Because the AIRAliases.js file may not be present when you’re building you app with a text editor/command line we’re going to remove the JavaScript file from “HelloJoomla.html” and create the aliases we need manually.

remove the line containing

<script src="lib/air/AIRAliases.js" type="text/javascript"></script> 

from your "HelloJoomla.html" code

Defining The JavaScript Functions

JavaScript will be driving the functionality of our AIR application. This includes handling the AMF communication with our Joomla! server and manipulating the DOM.

Just like in normal web applications, we can place our JavaScript code in a separate js file and link to it externally. For our example I’m going to write our JavaScript inline between the “head” tags. (We could easily use jQuery, MooTools or any other js library we choose but for this example I will be using raw JavaScript to keep our first application light).

create a new JavaScript block inside "HelloJoomla.html"

<script type="text/javascript">
    our JavaScript code will go here...
</script> 

We then place our js code in between our script tags.

 //Define AIR aliases [Maps variables JavaScript objects to ActionScript methods objects]
 //(remove/comment-out the next 4 lines if you loaded AIRAliases.js)
 var air;
 if (!air) air = {};
 air.NetConnection = window.runtime.flash.net.NetConnection;
 air.Responder = window.runtime.flash.net.Responder;

 //Set the url to your J-AMFPHP gateway e.g.	
 var GATEWAY = 'http://localhost/joomla/amfphp/';

 //initialse Net connection variables
 var conn = null;
 var response = null;

 //invoke if there is a problem with an AMF request
 function doFault( e )
 {
    alert( e.description );
 }

 //Connect to the AMF gateway
 function initConnection(){
    conn = new air.NetConnection();
    conn.connect( GATEWAY );
 }

 function doHello()
 {
    //Get the value of the text input (Name box)
    var uName = document.getElementById('myName').value;

    if (uName) { //Name Box has a value (i.e not null)
	//Set Loading message
	document.getElementById('amfresults').innerHTML = "Loading AMF Request...";

	//Call helloResult function with the response object
	//as the parameter. If action failed, call doFault function
	response = new air.Responder(helloResult, doFault);

	//send request to AMF service path with uName as the parameter
	//and act upon the response
	conn.call('hello_joomla.HelloJoomla.greetMe', response, uName);

    } else {
	//if name input field is null 
	document.getElementById('amfresults').innerHTML =
	"This would work much better if you provded your name  ";
    }
}

 function helloResult(result){ // the 'result' parameter is the AMF response

    //Populate the element of id 'amfresults' with the AMF result object [i.e. a string]
    document.getElementById('amfresults').innerHTML = result;
}

The core functionality of our AIR application is complete. Now we just need to and some basic css and HTML to the rest of our “HelloJoomla.html” file.

The Basic CSS

We could place this in an external stylesheet and reference it from “HelloJoomla.html”, but I’ve chosen to add this CSS code inline between our “head” tags. It’s not an issue for a small application.

 <style type=text/css>

 body{
     padding: 30px;
     background-color: #f9f8f2;
     color:#70695D;
     font-family: Helvetica,Arial,sans-serif;
     font-size:14px
 }
 ul {
     list-style: none;
 }
 li {
     margin-bottom:14px
 }

 h3 {
     color:#25211B;
     font-family:Georgia,"Times New Roman",Times,serif;
     font-weight:normal;
     font-size: 22px;
 }

 input {
     font-size:12px; margin-top:10px; font-weight:bold
 }
 #myName {
     width:180px;
     height:34px;
     background-color:#eae9db;
     margin-right:10px;
     border: 1px solid #c9c5b0;
     font-size:15px;
     color:#444;
 } 

 #myName:hover {
     background-color: #fff;
  }

 .buttn {
     width:120px;
      height:34px;
     font-size:12px;
     font-weight:bold;
     background-color:#191610;
     color:#fff;
     border: 1px solid #191610;
 }

 #amfresults {
     width: 50%;
     padding: 10px;
     margin: 10px 0 0 25px;
     color: #4D7553;
     line-height:20px
 }
 </style>

Where It All Happens

We’re almost done. Let’s add the HTML body code and complete building our application.

 <body onLoad="initConnection();"><!-- Call initConnection() when the application loads -->
    <ul>
        <h3>Send AMF Request To HelloJoomla Service</h3>
        <li>Enter your name below and send the AMF request<br/>
	    <input type="text" id="myName" />
            <input type="button" class="buttn" onclick='doHello();'
                 value="Send AMF Request" />
        </li>

    </ul>
        <div id="amfresults"></div>
 </body>

Happy coding )

Download Source [zip - googlecode]