Tutorial 4: Building a mobile twitter client

At the start of this tutorial series, I made comparisons between using MadComponents, and using Flash Builder 4.5 mobile components.  Certainly, the MadComponents project is much more lightweight.  I believe it is also easier to develop.  In this tutorial, you’ll have the opportunity to compare for yourself.  We are going build the same application from a Flex Builder 4.5 tutorial, created by Narciso Jaramillo at Adobe.  Build your first mobile Flex application – Twitter Trends.  But we’re going to do it the MadComponents way.

UPDATE 4 September ’11: There was a small change in the twitter API, so I’ve updated the code to reflect this.

UPDATE 20 November’11: I’ve changed the code to compensate for further Twitter API changes.  The updated version is  here.  Please ensure you’re using the latest version of MadComponents.  This tutorial will be updated at a later date.

 

MadComponents is IDE agnostic.  So you can follow this tutorial using Flash, Flex, or some third-party IDE.  For development, you don’t need the latest version of the Flash Player, or AIR – and you can even develop and test your app in the browser if you like.

I’ll assume that you’ve got the latest version of the MadComponents library from my download page.  Or Flex users can check-out latest demos from the subversion repository.  If you’d like a sneak peek to the end result of this tutorial – it’s called MadComponentsJSON.as.  You can take a look here.  (Yup – that’s it.  Surprisingly simple with MadComponents, isn’t it.).

If you haven’t read the first three tutorials, I’d recommend that you do that – so you know what’s what.

Creating the project

So let’s go through the steps to build this app.  We create the project in the same way that we did for our hello world tutorial 1 project.  (In fact, I’ve copied and pasted the instructions below).

1. If you don’t have the latest version of MadComponents, you can download it from  http://code.google.com/p/mad-components/downloads/list

Although the pictures below depict MadComponentsLib0_5.swc, you’ll need the latest version.  Currently MadComponentsLib0_5_3.swc (or a newer version when available).

2A. If you’re using Flash.  You need to find your libs folder.  For Flash CS5, you’ll find this directory at the following path, from your Flash application folder:-

Adobe_Flash_CS5/Common/Configuration/ActionScript_3.0/libs

Once you’ve found this folder, put MadComponentsLib into it:-

2B. If you’re using Flash Builder (Flex), just include the .swc into the project in the usual way.

( Project -> Properties -> ActionScript Build Path -> Library Path -> Add SWC Folder… lib )

3. Create a new ActionScript application.  Call it “MadTwitterTrends”.  Either Adobe AIR ActionScript applications, or a browser based application.

4. For an Adobe AIR application, set your window size to 300 x 454.  (not applicable to a browser application).  In Flash, you’ll see this in the properties panel:-

( On a real device, it will adapt to the screen size, but in simulation – it assumes 300 x 454 pixels )

5. Now save your application.  In Flash, make sure you’ve made a new folder for it.

6. In Flex, you’ll already have a top ActionScript class.  In Flash you’ll need to create one.  File->New->ActionScript File.  Call it “MadTwitterTrends.as”.  Save it in the same folder as MadTwitterTrends.fla .

7. In Flash, create a link between the timeline project, and the ActionScript file.  (No need to do anything in Flex).  Click on the first cell on the timeline, and in the Actions Panel, type:

new MadTwitterTrends(this);

Now we’re ready to write some code.

The Model Tag

In the previous tutorial, we learnt about lists.  So we’re going to start with a list.  We can populate a list from an online server feed, and express this in our layout using the <model> tag as follows:-

<list id=”trendsView”>

     <model url=”http://api.twitter.com/1/trends/available.json&#8221; action=”loadJSON”>

          <name>label</name>

          <url/>

     </model>

</list>

We can see that the url specified the address of the JSON web service.  If we paste this address into the browser, we can see what the data looks like:-

[

      {“name”:”#listentoyourheart”,”url”:”http:\/\/search.twitter.com\/search?q=%23listentoyourheart”},

      {“name”:”#youneedtositdown”,”url”:”http:\/\/search.twitter.com\/search?q=%23youneedtositdown”},

etc…etc…

Within this data, is an array of records, called “trends”.  And we can see that each object contains a “name” and a “url”.  Let’s look again at our layout:-

<list id=”trendsView”>

     <model url=”http://api.twitter.com/1/trends/available.json&#8221; action=”loadJSON”>

          <name>label</name>

          <url/>

     </model>

</list>

Each object inside this array will become one row of our list.  The “name” field of the object will be mapped onto the label of the row.  The “url” field will also be stored inside each row (but in this case it won’t be displayed).

8. With your MadTwitterTrends.as file, write the following program:-

package
{
	import com.danielfreeman.madcomponents.*;

	import flash.display.Sprite;
	import flash.display.StageAlign;
	import flash.display.StageScaleMode;

	public class MadTwitterTrends extends Sprite {

		protected static const TRENDS_VIEW:XML =

			<list id="trendsView">
				<model url="http://api.twitter.com/1/trends/available.json" action="loadJSON">
					<name>label</name>
					<url/>
				</model>
			</list>;

		public function MadTwitterTrends(screen:Sprite = null) {

			if (screen)
				screen.addChild(this);

			stage.align = StageAlign.TOP_LEFT;
			stage.scaleMode = StageScaleMode.NO_SCALE;

			UI.create(this, TRENDS_VIEW);
		}
	}
}

9. Run the program, and you’ll see a list of twitter trends.

Well, that was easy.

A Custom Renderer

When we click on any twitter trend row, we want another list to be displayed.  A specific twitter feed.  The layout for this second list is as follows:-

<list autoLayout=”true” id=”tweetsView”>

 

    <model path=”results”/>

 

        <horizontal>

             <imageLoader id=”profile_image_url”/>

              <vertical gapV=”0″>

                     <label id=”from_user” alignH=”fill”></label>

                     <label id=”text” alignH=”fill”>{SMALL_TEXT}</label>

              </vertical>

    </horizontal>

</list>

If you read the previous tutorial, you’ll probably recognise this as a list with a custom renderer.  Each row, consists of an image, and two text labels.  Like this:-

The ids of each MadComponent (profile_image_id, from_user, text) actually correspond to the names of the fields inside the JSON array of records at path=”results”.  This is why we didn’t need to write anything between the <model> and </model> tags.

10. Let’s test out this list layout.  Modify your MadTwitterTrends.as file, so that it looks like this:-

package
{
	import com.danielfreeman.madcomponents.*;

	import flash.display.Sprite;
	import flash.display.StageAlign;
	import flash.display.StageScaleMode;

	public class MadTwitterTrends extends Sprite {

		protected static const SMALL_TEXT:XML = <font size="12"/>;

		protected static const TWITTER_VIEW:XML =

				<list autoLayout="true" id="tweetsView">

				<model url="http://search.twitter.com/search.json?q=%23listentoyourheart" path="results" action="loadJSON"/>

				<horizontal>
					<imageLoader id="profile_image_url"/>
					<vertical gapV="0">
						<label id="from_user" alignH="fill"></label>
						<label id="text" alignH="fill">{SMALL_TEXT}</label>
					</vertical>
				</horizontal>
			</list>;

		public function MadTwitterTrends(screen:Sprite = null) {

			if (screen)
				screen.addChild(this);

			stage.align = StageAlign.TOP_LEFT;
			stage.scaleMode = StageScaleMode.NO_SCALE;

			UI.create(this, TWITTER_VIEW);
		}
	}
}

Just for test purposes, we specified a url and an action:-

<model url=”http://search.twitter.com/search.json?q=%23listentoyourheart&#8221; path=”results” action=”loadJSON”/>

But when we write our application, we’re going to control this using ActionScript.

Load data under ActionScript control

In the example above, we’re always loading the same twitter page.  Notice the parameter after the ? in the url.  search.json?q=%23listentoyourheart.  We want this parameter to come from the twitter trends row that’s clicked.  We’re going to extract it from the “url” field of the twitter trends data.

{“name”:”#youneedtositdown”,”url”:”http:\/\/search.twitter.com\/search?q=%23youneedtositdown“}

Here is the code:-

var url:String = _trendsView.row.url;

_tweetsView.model.loadJSON(“http://search.twitter.com/search.json?q=”+url.substr(url.lastIndexOf(“/&#8221;)+1));

Notice that a UIList has a row property.  This gives you the data associated with the last row that was clicked.  So in the code above, we concatenate the query string from the “url” field, with “http://search.twitter.com/search.json&#8221;.

autoLayout=”true”

Usually, MadComponents only arranges the layout of each screen when it first renders it, or when the screen orientation changes.  It doesn’t change the layout when text or images are updated.  But in this example, the height of the text fields depend on how much text they contain, and size of the thumbnail picture might also affect the way each row is laid out.  And the position of each row, depends on where the row above it finishes.  Hence we say autoLayout=”true”.  Now the layout of the rows will be rearranged every time the data is updated.  Another way to think about it, is that we would use autoLayout=”true” in a list, if the rows of that list are different heights.

Navigation

We used a <navigation> container in the first tutorial.  We use it to contain a number of pages.  So if we want to put our two lists inside a navigation container, we would write:-

<navigation>

     {TRENDS_VIEW}

     {TWEETS_VIEW}

</navigation>

When we click on a list row, the navigation container will automatically change to the next page.  You don’t have to do any coding to make this happen.  You also automatically get a back button.

Putting it together

11. So let’s put the two pages into a navigation container.  Now our application looks like this:-

package
{
	import com.danielfreeman.madcomponents.*;

	import flash.display.Sprite;
	import flash.display.StageAlign;
	import flash.display.StageScaleMode;
	import flash.events.Event;

	public class MadTwitterTrends extends Sprite {

		protected static const SMALL_TEXT:XML = <font size="12"/>;

		protected static const TRENDS_VIEW:XML =

			<list id="trendsView">
				<model url="http://api.twitter.com/1/trends/available.json" action="loadJSON">
					<name>label</name>
					<url/>
				</model>
			</list>;

		protected static const TWEETS_VIEW:XML =

			<list autoLayout="true" id="tweetsView">
				<model path="results"/>

				<horizontal>
					<imageLoader id="profile_image_url"/>
					<vertical gapV="0">
						<label id="from_user" alignH="fill"></label>
						<label id="text" alignH="fill">{SMALL_TEXT}</label>
					</vertical>
				</horizontal>
			</list>;

		protected static const NAVIGATOR:XML =

			<navigation id="navigation" rightButton="refresh">
			{TRENDS_VIEW}
		    {TWEETS_VIEW}
		</navigation>;

		protected var _navigation:UINavigation;
		protected var _trendsView:UIList;
		protected var _tweetsView:UIList;

		public function MadTwitterTrends(screen:Sprite = null) {
			if (screen)
				screen.addChild(this);
			stage.align = StageAlign.TOP_LEFT;
			stage.scaleMode = StageScaleMode.NO_SCALE;
			UI.create(this, NAVIGATOR);

			_trendsView = UIList(UI.findViewById("trendsView"));
			_trendsView.addEventListener(UIList.CLICKED, trendsViewClicked);

			_tweetsView = UIList(UI.findViewById("tweetsView"));

			_navigation = UINavigation(UI.findViewById("navigation"));
			_navigation.navigationBar.rightButton.addEventListener(UIButton.CLICKED, refresh);
		}

		protected function refresh(event:Event):void {
			if (_navigation.pageNumber==0)
				_trendsView.model.loadJSON();
			else if (_navigation.pageNumber==1)
				_tweetsView.model.loadJSON();
		}

		protected function trendsViewClicked(event:Event):void {
			var url:String = _trendsView.row.url;
			_tweetsView.model.loadJSON("http://search.twitter.com/search.json?q="+url.substr(url.lastIndexOf("/")+1));
			_tweetsView.scrollPositionY = 0;
		}
	}
}

Notice how I’ve added a right “refresh” button to the navigation bar.  The loadJSON() method takes a url parameter, but without this parameter, it reuses the url that you used previously.  So loadJSON() without any parameters causes a refresh.

A Detail Page

Finally, we’re going to make a detail page that gives you some more information about a particular twitter page.  This page is based on a form consisting of an image and some label text fields.

<columns id=”detail” widths=”50,100%” autoLayout=”true”>

    <model path=”user”/>

    <imageLoader id=”profile_image_url”/>

        <vertical>

            <label id=”name” alignH=”fill”/>

            <label id=”screen_name”>{SMALL_TEXT}</label>

            <label id=”location” alignH=”fill”>{SMALL_TEXT}</label>

           <label/>

           <label id=”description” alignH=”fill”>{SMALL_TEXT}</label>

    </vertical>

</columns>

The details page web service is XML.  You might want to have a look at an example it in the browser.

http://api.twitter.com/1/users/show.xml?screen_name=e2easy

(I haven’t used my twitter account for a long time).  MadComponents can deal with JSON, XML, and AMF data.  In my layout I’m extracting the profile_image, name, screen_name, location, and description fields.

The Finished Application

So finally, with the detail page included, and an image skin (remember tutorial 2) for the refresh button.  We’re also going to add a search to the twitter list.  <search field=”text”/> means that we will compare the search string that the user types in with the contents of a field called “text”.  Remember, this is one of the labels in our custom renderer.

12. Our finished application looks like this:-

package
{
	import com.danielfreeman.madcomponents.*;

	import flash.display.Sprite;
	import flash.display.StageAlign;
	import flash.display.StageScaleMode;
	import flash.events.Event;
	import flash.events.MouseEvent;

	public class MadTwitterTrends extends Sprite {

		protected static const SMALL_TEXT:XML = <font size="12"/>;

		protected static const TRENDS_VIEW:XML =

			<list id="trendsView">
				<model url="http://api.twitter.com/1/trends/available.json" action="loadJSON">
					<name>label</name>
					<url/>
				</model>
			</list>;

		protected static const TWEETS_VIEW:XML =

			<list autoLayout="true" id="tweetsView">
				<model path="results"/>

				<search field="text"/>

				<horizontal>
					<imageLoader id="profile_image_url"/>
					<vertical gapV="0">
						<label id="from_user" alignH="fill"></label>
						<label id="text" alignH="fill">{SMALL_TEXT}</label>
					</vertical>
				</horizontal>
			</list>;

		protected static const USER_DETAIL:XML =

			<columns id="detail" widths="50,100%" autoLayout="true">
				<model path="user"/>

				<imageLoader id="profile_image_url"/>
				<vertical>
					<label id="name" alignH="fill"/>
					<label id="screen_name">{SMALL_TEXT}</label>
					<label id="location" alignH="fill">{SMALL_TEXT}</label>
					<label/>
					<label id="description" alignH="fill">{SMALL_TEXT}</label>
				</vertical>
			</columns>;

		protected static const NAVIGATOR:XML =

			<navigation id="navigation" rightButton="" title="Twitter Trends">
				{TRENDS_VIEW}
				{TWEETS_VIEW}
				{USER_DETAIL}
			</navigation>;

		[Embed(source="images/refresh.png")]
		protected static const REFRESH:Class;

		protected var _navigation:UINavigation;
		protected var _trendsView:UIList;
		protected var _tweetsView:UIList;
		protected var _detail:UIForm;

		public function MadTwitterTrends() {
			stage.align = StageAlign.TOP_LEFT;
			stage.scaleMode = StageScaleMode.NO_SCALE;
			UI.create(this, NAVIGATOR);

			_trendsView = UIList(UI.findViewById("trendsView"));
			_trendsView.addEventListener(UIList.CLICKED, trendsViewClicked);

			_tweetsView = UIList(UI.findViewById("tweetsView"));
			_tweetsView.addEventListener(UIList.CLICKED, tweetsViewClicked);

			_detail = UIForm(UI.findViewById("detail"));

			_navigation = UINavigation(UI.findViewById("navigation"));
			_navigation.navigationBar.rightButton.skinClass = REFRESH;
			_navigation.navigationBar.rightButtonText = "";
			_navigation.navigationBar.rightButton.addEventListener(UIButton.CLICKED, refresh);
			_navigation.navigationBar.backButton.addEventListener(MouseEvent.MOUSE_UP, goBack);
		}

		protected function refresh(event:Event):void {
			if (_navigation.pageNumber==0)
				_trendsView.model.loadJSON();
			else if (_navigation.pageNumber==1)
				_tweetsView.model.loadJSON();
		}

		protected function goBack(event:MouseEvent):void {
			_navigation.navigationBar.rightButton.visible = true;
		}

		protected function trendsViewClicked(event:Event):void {
			var url:String = _trendsView.row.url;
			_tweetsView.model.loadJSON("http://search.twitter.com/search.json?q="+url.substr(url.lastIndexOf("/")+1));
			_tweetsView.scrollPositionY = 0;
		}

		protected function tweetsViewClicked(event:Event):void {
			var user:String = _tweetsView.row.from_user;
			_detail.data = {profile_image_url:null};  //Clear the old image
			_detail.model.loadXML("http://api.twitter.com/1/users/show.xml?screen_name="+user);
			_navigation.navigationBar.rightButton.visible = false;
		}
	}
}

You can download my refresh.png image from here.  Or the subversion repository.  It’s in the images folder.

So that’s it.  We’ve built a twitter client application for mobile.  And MadComponents handled all the tricky stuff for you.  Easy, wasn’t it?

What’s next ?

In the next tutorial we’re going to learn about how to build your application for mobile devices (iPhone, Android, etc.), using Adobe’s FREE command-line tools.  amxmlc, and adt.

Further reading

To find out more about MadComponents, you can read the other related threads on this blog, or download the documentation at http://code.google.com/p/mad-components/downloads/list

There are also lots of code examples to view or check-out from the subversion repository at http://code.google.com/p/mad-components/source/checkout

Please subscribe to this blog if you want to catch subsequent tutorials.