Editor’s Note: This is part three of a four-part series on building mobile dashboards with Flash and PHP. You can still read Part One and Part Two on php|architect’s Website.

In case you did not know this, I love PHP. It is the Swiss Army Knife of development languages, and I can do dang near anything using it. These days, as “web” increasingly means “the backside of my application”, PHP domination of the web is growing. These days though, PHP means a lot more than just a way to dynamically generate HTML. Many PHP applications these days don’t involve a browser at all, or at the very least, don’t talk to it directly like in days past. Today, many of our client applications are desktop applications or mobile applications that use the payload from the PHP application to do more than just put words on the screen. As PHP developers, we’ve moved into a new phase. One where we have to concentrate less on what things look like and more on how things work. For developers like myself, who couldn’t draw a stick-figure if his life depended on it, this is very good news.

So we find ourselves today, working on the backside of an application that will run on an iPad. For the pretty stuff, see Marco’s article titled “Mobile Dashboards Made Easy”. It gives you the details on what the application does with the data it gets. Our job is to pull the data, and then package it in the way the application expects it.

A Journey of a Thousand Lines of Code, Starts at the Yak Barbers.

We will build the backside of the application using Zend Framework. For those of you that use other frameworks, the concepts shouldn’t be too difficult to follow. Here’s a thought, though – since you are learning here, why not grab Zend Server and Zend Framework to go with your Flash Builder and set them all up? Break out of your existing development paradigm for the time it takes you to run this tutorial and experiment with new tools. The worst case scenario is that it validates your tool choice in your mind. In the best case, you pick up a new tool or two for your toolbox. In my case, though, I used a plain vanilla Apache install on Windows, PHP 5.3.x and Flex Builder 4. I did not get to experience the round-trip debugging feature of Flex Builder 4, but we’ll worry about that at a later date.

Once you have a working environment – *AMP stack and at the very least, Zend Framework – downloaded and put somewhere and the Zend Tool operational, then we can proceed. If you do not have Zend Tool set up, you need to stop, go read the section of the Zend Framework manual that talks about Zend Tool and get it set up. It’s not difficult, but it will make life ever so much easier, especially since we use it for getting things set up.

OK, now that this is set up, there’s a little more yak shaving to do. Since this is an API running over HTTP, you will need a working web server. In most cases, this means an Apache conf file to define a virtual name based server. I call the application dashboard, and on my laptop, it is set up as laptop.local. However you want to set it up is fine, just remember that the client needs to be able to get to it. In my case, the client is running straight out of Flash Builder 4 so adding dashboard.local to my hosts file was all that was necessary for everything to work. If you are working in a more complex setup, you will want to figure out a better way. Personally, I am all about making this as easy as possible so I can get on with the coding.

By now you have Apache set up and running and are ready to get your app on. From the directory that contains your projects directory (as specified in your web server config file), go ahead and execute this:

zf create project dashboard

Do the Database Dance

Since this application needs a database, I’ve provided you with one. It’s a very small sample of the php|architect core database. I’ve only provided the tables and fields necessary to demonstrate the features of the client.

If you download the source code, you will find a sample.sql with everything you need to create a database named sample in a MySQL RDBMS. All you need to do is create the database in your MySQL server, and then import it.

Once you have created it, you need to tell your application how to access it. In application/configs/apalication.ini you will find the resource.db section.

resources.db.adapter = “PDO_Mysql”

resources.db.params.dbname = “sample”

resources.db.params.username = “root”

resources.db.params.password = “”

resources.db.params.host = “localhost”

Adjust the parameters to suite your configuration, and save the file. (Yes, I run MySQL on my local laptop with root and no password. No, you should never do that, ever, not even as a joke.)

There, we have now completed the yak shaving portion of the program…almost. One final thing you have to do. I really don’t understand why Zend Tool doesn’t do this one last step for you. Navigate to the public directory created by the zf create project above. In there, you will find an .htaccess file. At the top of that file, put the line:

SetEnv APPLICATION_ENV development

Now save and exit the file.

There, now you are completely done with the yak shaving portion of the program. Now that you’ve gone through all the steps, I should probably point out that you can download the complete source code for dashboard, unzip it somewhere, point Apache to it and be on your way. Yes it’s faster, but you don’t learn as much.

The Front End

Hopefully, by this point, you’ve already read Marco’s article on how to build the front end. If you’ve not, stop and do it now. Without that, you have no idea if you did it right. For my testing, I pulled up Flash Builder 4, imported his project into its own directory, set it to display like an iPhone, and then simply ran the application locally to test. With both the front end and back end running on the same machine, debugging anything is very simple.

It should be noted that if you are using Zend Studio/Zend Server and Flash Builder 4, your life will be a lot easier as you can use their round-trip debugging. You can set breakpoints within the server side of the application, run the client and have things pause while you work out the details on the server side. This application is simple enough so that there doesn’t need to be a lot of debugging, but when things go wrong, not being able to see exactly what is going wrong can be a real pain.

The only downside to using the integrated system is that you have to create the projects using Flash Builder 4. Since I used Zend Tool to create them, I couldn’t use the whole round-trip debugging tool.

Once you have the client up and running, either within Flash Builder 4 or on a mobile device, it’s time to dive in.

API!=RESTful

Before we get started, I feel it necessary to talk a little about the API that we are building. Not all APIs are RESTful; this one certainly isn’t. This API is more along the lines of RPC over HTTP. One of the biggest things that keep this API from being RESTful is that we use POST to talk to the web server when we are requesting the data. In REST, the HTTP verbs are important. I am using POST here merely as a convenience as it allows us to submit larger payloads than can be submitted on the URL itself.

Second, the application itself does not return HTTP Result Codes other than 200. We are not talking to a web browser, therefore we can return our errors any way we want to.

If this application was going to be multi-client and a web browser would be a possible option, I would have designed it slightly differently in this respect. I would have returned proper HTTP result codes for all conditions. However, the client of this API is only going to be our Flex-based application, therefore we only need 1 result code, 200. We always return 200 on a successful call, regardless of whether the procedure worked correctly or not. Internally, we have ways of dealing with errors, and the payload tells us what went wrong.

If there is something else wrong, i.e. the server had issues, the web server will return the appropriate code, and the client will deal with it as it will.

In the first installment of this article, I showed how a Flex-based front end can easily connect to a PHP backend; this is particularly true if the backend was designed for this kind of operation in the first place, but Cal Evans is going to show you how you can build an API around any existing system in Part 3.

For now, let’s focus on the user experience that our dashboard will provide. The first thing to keep in mind that is that we’re targeting platforms that are quite different: Flash can support iOS (which is itself broken down into iPads and iPhones), Android and QNX, which powers RIM’s Playbook.

As it so happens, we use all three categories of devices at Blue Parabola—which means that instead of endlessly fighting over which one to support, we wrote a simple app that works on every platform.

There are a couple of considerations to make here. The first is that these devices have very diverse sizes and aspect ratios. Therefore, our app needs to adapt to each configuration—possibly with as little intervention on our part as possible. The second is that mobile users often expect the layout of their apps to adapt dynamically to the orientation of their device.

In our case, the needs of our mobile dashboard are quite simple; there are, after all, only so many ways in which one can display sales information. One thing that is worth noticing, however, is the fact that this information also lends itself to being displayed visually—for example, through a nice pie chart.

Thus, our application will display a list of sales figures when in landscape mode and a pie chart that illustrates the various categories of sales.

Getting Started

The first thing that we need to do is, obviously, create the project. This is actually fairly simple, as the latest version of Flash Builder (4.5.1 as of this writing) features a mobile project template that can simultaneously be compiled against all three supported platforms.

Given that we have the ability to display results according to their time period (day, week and month), our best choice here is a “Tabbed Application,” which allows us to navigate through multiple tabs.

The new project wizard generates a new TabbedViewNavigatorApplication container, complete with the three tabs:

<s:ViewNavigator label="Today"
                 width="100%" height="100%"
                 firstView="views.TodayView"
                 firstViewData="{todayData}" />
<s:ViewNavigator label="Week"
                 width="100%" height="100%"
                 firstView="views.TodayView"
                 firstViewData="{weekData}"/>
<s:ViewNavigator label="Month"
                 width="100%" height="100%"
                 firstView="views.TodayView"
                 firstViewData="{monthData}"/>

There are a couple of things to note here. The first is that Flash Builder will normally create individual views for each of the tabs on the expectation that each tab contains different information. In our case, the information displayed is always the same (the only thing that changes is the time period), so we simply recycle the same view three times.

Additionally, the ViewNavigator will create its own instance of our initial view, which means that whatever data this uses must either be generated internally or passed by using the firstViewData parameter. In our case, it makes more sense to do the latter, which means that we need to generate the proper date periods that signify “today,” “this week,” and “this month.”

There are a number of ways to do so; our backend automatically sets the time portion of the start date to midnight and that of the end date to 23:59:59. Therefore, we can generate these date periods with a little bit of ActionScript code:

protected function handleCreationComplete(event:FlexEvent):void {
   var startDate:Date;
   var endDate:Date;

   startDate = new Date(todayData.startDate);
   startDate.date -= startDate.day;

   endDate = new Date(startDate);
   endDate.time += 86400000 * 7 - 1;

   weekData = {
      startDate: startDate,
      endDate: endDate
   };

   startDate = new Date(todayData.startDate);
   startDate.date -= startDate.date - 1;

   endDate = new Date(startDate);
   endDate.month += 1;
   endDate.time -= 1;

   monthData = {
      startDate: startDate,
      endDate: endDate
   };
}

Nothing special here. Note, however, that ActionScript’s date functionality is quite different from that of PHP. On one hand, it doesn’t quite have the flexibility of functions like strtotime(); on the other, the fact that dates are expressed as an object does make it easy to manipulate their components by adding to or subtracting from them, which in this case, is quite handy.

Handling Device Orientations

Onto the view itself. Since we want to display different content based on the orientation of the screen, we need to figure out when the user rotates their devices. That turns out to be quite easy; when the view is added to the stage, we simply add an event handler to Stage that gets notified whenever the orientation changes:

isLandscape = (stage.orientation == StageOrientation.ROTATED_LEFT ||
               stage.orientation == StageOrientation.ROTATED_RIGHT);

stage.addEventListener(StageOrientationEvent.ORIENTATION_CHANGE,
   function(e:StageOrientationEvent):void {
      var stage:Stage = e.target as Stage;

      isLandscape = (stage.orientation == StageOrientation.ROTATED_LEFT ||
                     stage.orientation == StageOrientation.ROTATED_RIGHT);
});

As you can imagine, isLandscape is a protected property of the view; as a result, all it takes to show or hide a particular element based on orientation is to use its visible and includeInLayout properties to check if isLandscape is true or false.

Segmenting the Results

Since our results are segmented by product, category and country, we might as well have our interface reflect the same breakdown. We can do this, for example, by displaying a segmented control (called ButtonBar in Flex) that allows the user to switch between the available screens:

<fx:Declarations>
   <s:ArrayCollection id="buttons">
      <fx:String>SKU</fx:String>
      <fx:String>Category</fx:String>
      <fx:String>Country</fx:String>
   </s:ArrayCollection>
</fx:Declarations>

<s:ButtonBar width="100%" selectedIndex="0"
          id="buttonBar"
          requireSelection="true"
          dataProvider="{buttons}"/>

Here, the ArrayCollection serves as a data provider to the ButtonBar, and that’s where we store the names of the various buttons. From this point on, we can track the selectedIndex property of the ButtonBar to determine which result set must be displayed.

Note also that, here, I have set the requiredSelection property to true to ensure that the user has at least one selected button at all times, since leaving all the buttons unselected would cause the application to be in an inconsistent state.

Displaying the Results

The results returned by a call to our backend can be displayed very easily using a tabular approach—which is exactly what the List component is designed to do. Each row in the table is drawn by an item renderer—essentially just an object that the list component recycles throughout its life to display each row.

Flash comes with a number of different item renderers that have been optimized for mobile display, and the one we’re going to use is called IconItemRenderer. Despite its name, we’re not going to use any icons—but we are going to take advantage of its ability to display both a primary and a secondary label: we’ll use the former to display the name of the line item, and the latter to display revenue and sales:

<s:List
    width="100%" height="100%"
    visible="{buttonBar.selectedIndex == 0 &amp;&amp; isLandscape}"
    includeInLayout="{buttonBar.selectedIndex == 0 &amp;&amp; isLandscape}"
    dataProvider="{salesData.resultsBySKU}">

    <s:itemRenderer>
        <fx:Component>
            <s:IconItemRenderer
                labelField="name" fontSize="14"
                messageField="description" messageStyleName="message" />
        </fx:Component>
    </s:itemRenderer>
</s:List>

It would be entirely possible to create our own item renderer—after all, it’s basically the same as building most other MXML components, although Adobe recommends that mobile item renderers be built in pure ActionScript for performance reasons. However, the built-in renderers, which are themselves quite similar to the ones that most mobile platforms provide, work just fine for most uses, particularly if you consider that you have nearly-complete freedom to alter their styling.

Visualizing the Data

What about the charts? These are usually not easy to generate and are even less easy to generate in a cross-platform way. We could resort to some server-side generation component, but the good news is that Flex actually comes with a rather rich set of charting components built in, making the generation of a chart as easy as this:

<mx:PieChart
    id="CountryChart"
    visible="{buttonBar.selectedIndex == 2 &amp;&amp; !isLandscape}"
    includeInLayout="{buttonBar.selectedIndex == 2 &amp;&amp; !isLandscape}"
    dataProvider="{salesData.resultsByCountry}"
    width="100%" height="100%">
    <mx:series>
        <mx:PieSeries
            displayName="Revenue"
            nameField="name"
            field="total"/>
    </mx:series>
</mx:PieChart>
<mx:Legend
    visible="{buttonBar.selectedIndex == 2 &amp;&amp; !isLandscape}"
    includeInLayout="{buttonBar.selectedIndex == 2 &amp;&amp; !isLandscape}"
    dataProvider="{CountryChart}"/>

As you can see, the visible and includeInLayout properties can be used to determine when either a chart or a table is visible. Here, I took advantage of the ability to write ActionScript expressions directly into the MXML code to decide whether to display a particular object depending on orientation and the user’s current selection.

Where to Go From Here?

There are a few things that I really like about this solution. Given our constraints (quick turnaround and cross-platform support) this turned out to be a good balance between features and requirements, particularly considering that the application is for our internal use. Considering the alternatives – either writing individual versions for each platform or using a web-based solution, which we didn’t want to do for a variety of reasons – the end result is quite good.

Naturally, I ended up having to write comparatively little actual code—Flash’s component set is rich enough in features that this is true most of the time. Since the underlying framework is open source, it’s normally also easy to extend the built-in components to add whatever functionality you need (despite Adobe’s deplorable insistence on using private methods and properties which makes extension sometimes difficult).

Alas, this solution is still tied to our backend, which was designed from the get go for the kind of uncoupled operation that makes Flash a very advantageous choice for front ends where the audience is captive and portability is essential. In the next two installments, my colleague Cal Evans will take over and show you how the same functionality can be built (and debugged) onto an existing system that uses Zend Framework.

Editor’s note: you can download the code for this article series here.

One thing that I’ve learned over the years is that smart people like to measure things. It’s impossible to understand how well anything works unless you have some way of understanding its effects in a quantitative way.

Here at php|architect, we are fortunate enough that the vast majority of our business runs almost entirely on the Internet, which means that all our information—from customer data to sales records—is safely stored in a single location.

Internally, our system is composed essentially of three different layers: a PHP-powered back end that encapsulates all our business logic, and then one or more front ends that provide interfaces to the various users. There is also a data layer, sitting at the far back, where our models are stored.

Setting the system up this way was, by far, one of the best decisions that we ever made. Our layers are physically separate, making it easier for us to contain the business logic neatly in a single place.

APIs Make Things Easier

Compared with building a website and then attaching an API to it as an afterthought, this enables us to easily create an arbitrary number of interfaces specialized for a variety of purposes. These include, obviously, our main website, but also a number of other subsystems that are not normally visible to the public.

For example, one of the subsystems, called Orion, is used by our staff to manage just about every aspect of site operations – like customer support, sales management, store maintenance, magazine publication, and so on and so forth.

In addition to being a bunch of highly opinionated hackers, we are also very peculiar about our work environments. Blue Parabola (BP) is a highly distributed company, with offices in four different cities across North America. Our staff uses the entire gamut of desktop operating systems, and because I find working in a web browser a less-than-elegant solution, we have always run our entire business using native applications.

Naturally, it would be prohibitively expensive to write and maintain a different app for each platform that we have to support (or to force everyone onto the same platform). As a result, we have written most of our internal applications using the Flex and Flash platforms that Adobe produces.

Flash, Seriously

When I tell people that we do this, I am usually met with puzzlement (and sometimes, with outright hostility), likely because Flash has gotten so much bad press in the past few years.

The problem, of course, is that even though the same Flash powers both all those ads in your browser and our management system, the results are quite different. Used on the desktop, Flash is a powerful and convenient way of building fully-functional applications that combine the convenience of a native environment with the ease of development associated with Internet technologies.

For the longest time, I’ve wanted to give our readers a glimpse into the way our system is built to show them what Flash can do if put to good use and how beneficial writing a system from the API up can be.

Unfortunately, our code is too complex to use as a simple example, and so I’ve been trying to think of a simpler project that could allow me to show the benefits of our setup.

Over the past couple of months, Cal and I had been actively bemoaning the fact that more and more of our daily lives are spent on a mobile device, and yet our backend didn’t really have any mobile capabilities.

As a result, we decided to write our own mobile dashboard.  Since the latest version of Flash supports mobile platforms and we use different devices (iPhone, iPad, and Android), we decided to use Flash Builder.

This, therefore, is the first of a three-part series in which Cal and I will show you how our mobile dashboard works. The principles are fairly simple, and we even built a little Zend Framework-based backend that feeds dummy data you can use to follow along (because even we are not quite so crazy as to share our actual sales number).

Getting Started

The goals of this project are fairly simple: pull up a breakdown of sales by product, category, and country for today, this week, and this month. To make things a little more visually interesting—always a good thing on mobile platforms—we have tweaked the app’s layout so that the numbers are shown as a scrollable table view when a device is oriented in landscape mode and as a pie chart when in vertical mode.

We’ll use Flash Builder for PHP to create a mobile app that can be compiled to run on iOS, Android and RIM’s Playbook without any changes, adapting automatically to the resolution of each target device. If you’ve never tried Flash Builder, you can grab a free trial from Adobe’s site.

In this first article, I will discuss the basic setup of the system, starting from the backend, where we assume that the retrieval of the data will go through a two-step process.

First, we’ll need to log in as an administrator on the system—this seems like an important step, considering that we’ll be dealing with highly sensitive data. Once the setup is complete, we can pull data remotely from the server by calling a method that returns a list of purchases for a given time period, optionally restricted based on country, category or SKU.

The actual interface to the backend is not entirely relevant at this point, since each backend will have a different API. In general, however, Flash Builder provides two methods for connecting to an external source.

The first is to use one of the IDE’s data connection wizards, which creates a proxy class in ActionScript with an interface that naturally matches the one offered by the remote system. The wizards are quite easy to use and work rather well, in my experience, but there are some cases where unusual interfaces require a more hands-on approach.

In Flex, this takes the form of HTTPService, which can be used to instantiate an HTTP call to a remote system.

Like most of Flex’s infrastructure, HTTPService works in a completely asynchronous way: once instantiated and asked to load a remote resource, it will work quietly in the background until either data becomes available or an error occurs. At that point, HTTPService will fire one of two events, advising the rest of the application that it’s time to take action.

HTTP Connections in Practice

From a practical perspective, connecting to a remote data source using HTTPService is a three-step process. First, you instantiate and populate an object instance with the appropriate information:

var localHttpService:HTTPService = new HTTPService();

localHttpService.url = "http://example.org/script.php";
localHttpService.method = "POST";

As you can see, the code simply instantiates HTTPService, then sets the URL and HTTP method of the request. Next, we need to set up callback closures that can be called when either a response is successfully received, or when an error occurs:

localHttpService.addEventListener(ResultEvent.RESULT, function(e:ResultEvent):void {
   // Do something
   trace(e.target.lastResult);
});

localHttpService.addEventListener(FaultEvent.FAULT, function(e:FaultEvent):void {
   // Handle error
});

The lastResult property of our HTTPService instance (which is the target of the ResultEvent) contains the text data returned by the remote server.

Detour: Handling JSON Information

In principle, HTTPService can also manipulate XML data, which ActionScript supports natively; however, I think it’s most likely that, these days, developers will have to contend with data encoded using JSON, which is a much more popular format.

Interestingly, the current AIR runtime doesn’t support JSON natively, which is a little odd if you consider ActionScript’s pedigree. Adobe is adding native JSON support to the next version of the runtime, but that won’t help you here; luckily, Flash Builder comes with a set of JSON serializers that can be used without having to resort to external libraries.

On my setup, making use of this serializer requires first adding two SWC files to the app’s build path. They are called serializers.swc and serializers_rb.swc, located in the eclipse/plugins/com.adobe.flexbuilder.project_4.5.1.313231/dcradSwcs/4.5/ folder of your Flash Builder installation.

Once these are linked into your application, you will be able to use the com.adobe.serializers.json.* packages to encode and decode JSON data:

import com.adobe.serializers.json.JSONDecoder;
import com.adobe.serializers.json.JSONEncoder;

...

// To encode:

var encoder:JSONEncoder = new JSONEncoder;
encode.encode(sourceData);

// To decode:

var decoder:JSONDecoder = new JSONDecoder;
var result:Object = decoder.decode(jsonData);

Receiving and Aggregating Data

Now that everything is set up, we can ask our HTTPService instance to reach out to the server and retrieve the appropriate information:

localHttpService.send({"data" : requestData});

As you can see, the send() method takes an object that contains a set of name/value pairs. These, in turn, are passed to the remote script either as query parameters (in the case of a GET operation) or as part of the HTTP request’s payload (in the case of a POST operation).

When data is returned by the server, it’s likely that we’ll need to manipulate it in some way—for example, we may want to aggregate it based on the category of the product. Assuming that the result is JSON-encoded and contains an array of these values:

• sku: the SKU (unique identifier) of the product
• productName: the name of each product
• quantity: the quantity of products sold
• price: the individual sales price of each product

We could aggregate the results using a simple loop:

for each (var result:ObjectProxy in resultCollection) {
	var bin:Object = skuResults[result.sku];

	if (!bin) {
		bin = {
			name		: result.productName,
			itemCount 	: 0,
			total		: 0
		};

			skuResults[result.sku] = bin;
	}

	bin.itemCount += Number(result.quantity);
	bin.total += Number(result.price) * Number(result.quantity);

	// Generate the final output

	var skuArray:Array = new Array();

	var formatter:CurrencyFormatter = new CurrencyFormatter();

	formatter.useCurrencySymbol = true;

	for each (entry in skuResults) {
		entry.description = "Sales: " + entry.itemCount +
		" — Revenue: " + formatter.format(entry.total); 

		skuArray.push(entry);
	}

	_resultsBySKU = new ArrayCollection(
		skuArray.sortOn("total", Array.DESCENDING | Array.NUMERIC));

The final line of this listing uses sortOn(), one of my favorite array manipulation functions in ActionScript, to sort the result sets by total revenues in descending order.

That’s All for Now…

The mechanics of pulling data from an external resource are not quite that complex—which allows us to focus on the actual functionality provided by our application.

In the next installment of this series, I will show you how to build the UI of the app, taking advantage of several mobile features provided by Flash that provide a rich feature set without having to deal with the intricacies of multiple platforms.