Tutorial : Using JSON with Flex 2 and ActionScript 3

One of the little gems you will find in the open source ActionScript 3 libraries that we released on labs, is the JSON class found in the corelib library. This class, written for Adobe by Darron Schall, makes it super simple to both serialize and de-serialize JSON data. What is JSON you ask? From the JSON website: JSON (JavaScript Object Notation) is a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate. It is based on a subset of the JavaScript Programming Language, Standard ECMA-262 3rd Edition - December 1999. JSON is a text format that is completely language independent but uses conventions that are familiar to programmers of the C-family of languages, including C, C++, C#, Java, JavaScript, Perl, Python, and many others. These properties make JSON an ideal data-interchange language. In a nutshell, JSON is a way to serialize data using JavaScript syntax. It is fairly compact, and easy to use. Furthermore, it has become increasingly popular due to the growth of AJAX applications, and the browser's native support of de-serializing JSON (via eval()).

If you look on the main page of my weblog, the Reading / Doing section on the left is actually a small AJAX widget I created that shows my latests diggs, delicious bookmarks, and items added to my ta-da lists. It gets its data from a JSON feed on the server, which is periodically generated by a PHP file. So, to show how to use JSON within a Flex / Flash application, we will load the JSON feed from my site into Flash and display it in a datagrid. Nothing earth shattering, but it will show how easy it is to use JSON. I am not assuming that you know anything about Flex / ActionScript or JSON. Because of this, the tutorial will be pretty long, as I want to make sure I cover every step of the process.

You can view the completed example here. (Requires Flash Player 8.5 beta 2). First, you need to make sure you have the following installed:

• Flex Builder or MXMLC command line compiler
• Flash Player 8.5
• corelib ActionScript 3 library

You can grab Flex Builder and MXMLC from labs (the MXMLC compiler is included with the Flex Builder install, and also in the SDK download (in case you are on MAC or Linux). Once you download the zip file for the corelib library, unzip it and you should see three subfolders: src, bins, docs.

• src : contains the source code for the library
• bin : contains a compiled SWC of the library (you can think of this as a DLL)
• docs : contains the API docs for the library

You can link the project against either the source, or the SWC. For this example, we will use the SWC since we don't need to edit the source code any. Once Flex Builder is install, open it and make sure that you are in the Flex Development perspective. Window > Open Perspective > Flex Development Next, make sure the navigator view is open (it is usually on the left). This view shows all of your projects and files. If the view is not open, you can open it via: Window > Show View > Navigator Right click in the navigator and select: New > Flex Project Name the Project "JSONExample" and make sure "Use default location" is checked. Then, click the "Next" button (not finish), this takes us to a screen that will allow us to add items to our class path, or to link against libraries. (you can access this at anytime, by selecting the project, and then selecting Project > Properties). Select the Libraries tab, and click Add SWC. Browser to the corelib.swc file which was including in the bin directory of the corelib zip file. Click the Finish button. The first thing we need to do is to add a datagrid to display the data. Our grid will contain two columns. One for the title, and one for the type of service (delicious, digg, tada). Make sure that the JSONExample.mxml file is open in the editor (double click it in the Navigator), and then switch to design view (click the Design button in the top left of the editor). This brings us to design view which allows us to visually layout and manipulate our components. Once you are in design view, you should see a Components view. If not, you can open it via Window > Show View > Components. This view contains all of the built in (and any custom components) that are available to the project. Select a DataGrid component from the Controls folder and drag it onto the stage. Once on the stage, resize it so that it takes up most of the space. The grid should snap to the edges when it gets close. Make sure the grid is selected then go to the Flex Properties view. It should be open on the right, but if it isn't you can open it via Window > Show Views > Flex Properties. We need to do two things here:

1. Give the control an ID
2. Set the layout constrains

Select the Id field at the top of the Flex Properties panel, and enter "grid". This basically gives the grid a variable name so that other controls and ActionScript can reference it. Next, scroll all the way to the bottom of the Flex Properties view to the Layout section. This will show your component with anchor points. Make sure that the following check boxes are checked:

• Top Right
• Top Left
• Left Top
• Left Bottom

This basically tells the controls to keeps its sides the same distance from the application's sides, even if the app / windows resizes. At this point, we are ready to switch back to source view, and load the JSON data. So, switch back to source view (click the Source button in the top left of the editor). You code should now look something like this: [code] [/code] Lets add an HTTPService tag to actually load the data. Add the following tag right under the Application tag. [code] [/code] If you save this, you should get an error in the problems view (Window > Show Views > Problems): Call to a possibly undefined method 'onJSONLoad' This is ok. We just need to define the onJSONLoad event handler. But first, lets look at the code we just wrote:

• id - Give the control a variable name so we can reference it later.
• url - the url that points to the JSON data we are loading
• resultFormat - the format that we want the data returned to us in. (In this case, just the raw text).
• result - event handler that is called when the data loads.

At this point, your code should look something like this: [code] [/code] Next, we need to create a script block to define our event handler function. Add a Script tag block just below the Application tag: [code] [/code] and then inside the Script block, lets define our event handler. You script block should now look like this: [code] [/code] If you look at the API docs, ResultEvent is the type of event broadcast when the data has loaded from the service. Next, all we need to do is:

• Get the raw JSON data from the URL
• De-serialize it from JSON to ActionScript
• Set the data as the dataProvider for the grid

Here is the completed function, with comments: [code] [/code] Notice that we also added some import statements to bring in the relevant classes. The actual JSON de-serialization part is pretty trivial and consists of this one line of code: [code]var arr:Array = (JSON.decode(rawData) as Array);[/code] JSON.decode returns a Object (since it doesn't know before hand what it will be de-serializing), so we have to cast the result to an Array using the "as" operator. (can't cast using Array() for legacy reasons). At this point, we only have two things left to do:

1. Actually tell the service to load the data.
2. Customize the DataGrid to map to the data we are passing it.

Telling the service to load the data is easy. Since we want it to load the data as soon as the app loads, we can just specify in in the creationComplete event for the app (this is called once the app has been loaded and the controls laid out). (You can think of this as the same as onload in HTML / JavaScript). We just need to add this attribute to the Application tag: [code]creationComplete="service.send()"[/code] Remember that service is the id / variable name for our HTTPService control. Basically, this says when the app has loaded and initialized, tell the HTTPService control to load its data. Finally, we need to tweak the DataGrid to show our data. In this case, we only need to tweak the columns within the DataGrid. First, remove one of the three column tags, since we only need two. Next, we need to add better column heading titles (through the headingText attribute), and map each column to a property in the data we loaded. If you look at the JSON data, you can see the following fields in each item:

• title
• src
• url
• date

For this example, we will just show the source and title. We specify this for each column through the dataField property. So, the new columns should look like this: [code] [/code] Basically, this tells the first column to use Service as the column title, and get its data from the "src" property of the loaded data. The second column gets it data from the title property. The completed code should now look like this: [code] [/code] If you debug / run your app, you should see a datagrid that contains all of the data from the JSON feed. (You can debug by clicking the little Bug icon on the toolbar, or selecting Run > Debug). If you are feeling generous, you can also easily publish your source code. Go back to Flex Builder, and select the JSONExample. Then select Project > Publish Application Source. Once you do this, re-run your application, and then right click on it and select View Source. This is a pretty simple example, but it shows how easy de-serializing JSON in ActionScript is (serialization is just as easy). You can view the completed example here. (Requires Flash Player 8.5 beta 2).

Updated : You can also view a screencast of this tutorial. Here are the links for the resources used in the tutorial:

• Flex Builder or MXMLC command line compiler
• Flash Player 8.5
• corelib ActionScript 3 library

I will update the post with images a little later, and am considering doing a screencast of building the example. If you liked the tutorial, make sure to digg it. Post any questions, suggestions and / or corrections in the comments.

March 28, 2006 11:09 AM | Bloglines | digg this

Related Entries

• Log your AS3 corelib Library bugs / features
• Global Variables within Flex Applications
• How to log bugs for the AS3 Libraries
• Twitter AS3 API
• AsDoc (AS3 Doc Generating Tool) on Labs

Comments

1. Rick
   March 28, 2006 2:41 PM
   Great tutorial Mike. I like that you took the time to explain every detail...makes it much easier for someone new to Flex (ie. me) to find my way around and figure out what's going on.
2. zikey
   March 29, 2006 5:25 AM
   It is very usefull.
3. Stefan Richter
   March 31, 2006 1:12 AM
   Very good Mike. I totally agree with Rick, having every step explained is a great help. More of it please, we're all hungry for Flex2.
4. Nilu
   April 1, 2006 7:05 PM
   Mike,

   this is very nice attempt. I do have one question, is there a good way to do nested data structures and get a corresponding object. Something like.

   {'EMPL':{'ID':1005,'Login_ID':'galileo','Name':'Galileo Galilei'}}

   {'BOSS':{'ID':1005,'Login_ID':'galileo','Name':'Hudini Galilei'}} I would like to get a a JSON object which may have multiple arrays in it.

   Thanks in advance!

   Nilu.

   P.S. We are *very* interested to get this Flex2 when ready. Can't wait.

5. Anonymous
   May 13, 2006 3:06 AM
   Hi Mike, the new versions fo your libraries do not contain the swc files or the bin directory (as stated). Is this intentional?
6. mike chambers
   May 13, 2006 8:44 AM
   >the new versions fo your libraries do not contain the swc files or the bin directory (as stated). Is this intentional? Oops. Sorry about that. I just uploaded an fixed version of corelib that includes the swc, and will fix the rest later today. Sorry about the hassle. mike chambers mesh@adobe.com
7. Mike Britton
   June 7, 2006 11:08 PM
   Thanks for this great tute. This is exactly the kind of thing needed to walk people through Flex Builder's workflow and showcase its features.
8. Troy Gardner
   July 5, 2006 12:30 AM
   If you use this with FlexBuilder 2, you'll need to change com.macromedia.serialization.* to com.adobe.serialization.*
9. stef
   July 12, 2006 7:51 PM
   mike great tutorial, so many thanks. Q: could you give a brief overview of how you create the JCON file using PHP? i mean is it a simple act of calling something like JCON.encode(phpObject)? i take it the php object needs to represent the DataProvider class? THANKS AGAIN!!! STEF
10. Dan
    October 30, 2006 11:55 PM
    Mike, thanks for the posting on the webapis. I'm trying to work with the flickr api, and can't seem to get past the sandbox security. Flickr has a wildcard crossdomain.xml Loading that doesn't seem to work when viewing as localhost or on a server. Can you take a brief moment to give us an example of how to set up a flex app to allow flickr images to display? It looks like a lot of effort went into the webapis, so I think it would be beneficial to all, considering there's no tutorial on the flickr api.
11. ian morton
    November 14, 2006 11:12 AM
    Thanks a lot for the example. Give us more lease. One note for cut and pasters like me, the import com.macromedia.... should now be import com.adobe...
12. infimate
    December 4, 2006 10:51 PM
    I tried out the library. One thing i found was that the json decoder does not seem handle new lines and single quotes in json text. I would also like to know if it there is something like like they have for xml so that i could bind form elements to json. I can't seem to find it.
13. Alphonso
    December 20, 2006 7:35 AM
    I'm very interested in Flex2 and would've liked to check your example, but the example ain't working. (I've the latest Flash Player on my machine). http://weblogs.macromedia.com/mesh/files/flex/jsonexample/ The screen in empty!

Post a comment