Description
1. Manages Excel spreadsheet files
2. Reads a sheet from a spreadsheet file and stores it in a ColdFusion spreadsheet object, query, CSV string, or HTML string.
3. Writes single sheet to a new XLS file from a query, ColdFusion spreadsheet object, or CSV string variable.
4. Add a sheet to an existing XLS file.

The description as outlined above shows that this tag is very useful, and can write XLS files from cfquery objects, csv string variables, or html strings. You can also write a custom ColdFusion function to upload an XLS file, read the content, and input it into a database. However, XLS Exporting in Adobe Coldfusion 9 has its downsides.

The problems with using the cfspreadsheet tag arise when your code logic that builds a ColdFusion spreadsheet object becomes lengthy. When manipulating a ColdFusion spreadsheet object, it slows down your code exponentially. This means the more you have to process, the longer it takes to do so. I got to the point where I could pull a 10,000 record cfquery from the database in 3-4 seconds, but it would take me about 4-5 minutes to put together the ColdFusion spreadsheet object and formatting it the way I wanted it.

Below is an example of a lengthy ColdFusion spreadsheet object being put together and exported to an .xls file.

<cfscript>
	theDir=GetDirectoryFromPath(GetCurrentTemplatePath());
   theFile=theDir & "ExampleReport.xls";
	theSheet = SpreadsheetNew("testSpreadsheet");
</cfscript>
<cfset spacer = ",,">
<cfset newTitle = "Event / Ticket Type,Quantity">
<cfset SpreadsheetAddRow(theSheet,newTitle)>
<cfset tempCITY = ''>
<cfset tempTIME = ''>
<cfset totalTicketsArray = ArrayNew(1) />
<cfloop query="collection.TICKETTYPES">
	<cfif #CITYNAME# NEQ tempCITY OR #PERFORMANCETIME# NEQ tempTIME>
		<cfset tempCITY = #CITYNAME#>
		<cfset tempTIME = #PERFORMANCETIME#>
		<cfif currentrow NEQ '1'>
				<cfset arraySum = "Total Tickets: ,#REReplace(numberFormat(arraySum(totalTicketsArray)), ",", "", "All")#" />
				<cfset SpreadsheetAddRow(theSheet,arraySum)>
				<cfset tmp = ArrayClear(totalTicketsArray)>
 				</cfif>
 				<cfset SpreadsheetAddRow(theSheet,spacer)>
		<cfset newRowHeader = "#CITYNAME#  ( #timeService.getFormattedDateDSTSimple(PERFORMANCETIME,TIMEZONEOFFSET)# @ #timeService.getFormattedTime(PERFORMANCETIME,TIMEZONEOFFSET)# )">
		<cfset SpreadsheetAddRow(theSheet,newRowHeader)>
	</cfif>
	<cfset newTicket = "#REReplace(TICKETNAME, ",", "", "All")#,#TICKETQTY#">
	<cfset SpreadsheetAddRow(theSheet,newTicket)>
	<cfset arrayAppend(totalTicketsArray, #TICKETQTY#) />
	<cfif currentrow EQ recordcount>
			<cfset arraySum = "Total Tickets: ,#REReplace(numberFormat(arraySum(totalTicketsArray)), ",", "", "All")#" />
			<cfset SpreadsheetAddRow(theSheet,arraySum)>
			<cfset tmp = ArrayClear(totalTicketsArray)>
				</cfif>
</cfloop>
<cfset SpreadsheetAddRow(theSheet,spacer)>
<cfset newTitle = "Payment Method,Amount">
<cfset SpreadsheetAddRow(theSheet,newTitle)>
<cfset tempCITY = ''>
<cfset tempTIME = ''>
<cfset tmp = ArrayClear(totalTicketsArray)>
<cfloop query="collection.CARDTYPES">
	<cfif #CITYNAME# NEQ tempCITY OR #PERFORMANCETIME# NEQ tempTIME>
		<cfset tempCITY = #CITYNAME#>
		<cfset tempTIME = #PERFORMANCETIME#>
		<cfif currentrow NEQ '1'>
				<cfset arraySum = "Total Tickets: ,#REReplace(dollarFormat(arraySum(totalTicketsArray)), ",", "", "All")#" />
				<cfset SpreadsheetAddRow(theSheet,arraySum)>
				<cfset tmp = ArrayClear(totalTicketsArray)>
 				</cfif>
 				<cfset SpreadsheetAddRow(theSheet,spacer)>
		<cfset newRowHeader = "#CITYNAME#  ( #timeService.getFormattedDateDSTSimple(PERFORMANCETIME,TIMEZONEOFFSET)# @ #timeService.getFormattedTime(PERFORMANCETIME,TIMEZONEOFFSET)# )">
		<cfset SpreadsheetAddRow(theSheet,newRowHeader)>
	</cfif>
	<cfset newTicket = "#REReplace(CARDTYPE, ",", "")#,#REReplace(dollarFormat(TICKETSALES), ",", "", "All")#">
	<cfset SpreadsheetAddRow(theSheet,newTicket)>
	<cfset arrayAppend(totalTicketsArray, #TICKETSALES#) />
	<cfif currentrow EQ recordcount>
			<cfset arraySum = "Total Tickets: ,#REReplace(dollarFormat(arraySum(totalTicketsArray)), ",", "", "All")#" />
			<cfset SpreadsheetAddRow(theSheet,arraySum)>
			<cfset tmp = ArrayClear(totalTicketsArray)>
				</cfif>
</cfloop>
<cfspreadsheet
    action="write"
	format="csv"
    filename="#theFile#"
	sheetname="ExampleReport"
	name="theSheet"
    overwrite="true" />

The first part of the code is a cfscript tag, which puts together the directory and spreadsheet variables that will be used to create the final spreadsheet file. Then follows some complex code logic that iterates through a ColdFusion variable called “collection”. This variable I instantiated previously as a ColdFusion structure that holds two cfquery variables, TICKETTYPES and CARDTYPES. I wanted both these queries to be added to the .xls spreadsheet.

In this complex code, I iterate through portions of each query, ordering them by a specific date value inside each query row. So, for example, my .xls spreadsheet would have headers on the top and for each instance of a specific date, include the TICKETTYPES (and then for the second part of the spreadsheet, the CARDTYPES).

For two queries of 10,000 rows each (one for TICKETTYPES and one for CARDTYPES) this complex code was taking forever to format a ColdFusion spreadsheet object. So I came up with a simple solution. When you format a query inside the SQL to display the way you want it on the spreadsheet, it offloads work from the ColdFusion server and onto the SQL database. In the end, all I had to do was include the below code to turn the generated cfquery into an .xls spreadsheet.

<cfscript>
	theDir=GetDirectoryFromPath(GetCurrentTemplatePath());
    file1=theDir & "ExampleReports.xls";
</cfscript>
<cfspreadsheet
    action="write"
    filename="#file1#"
	sheetname="TicketTypes"
	query="collection.TICKETTYPES"
    overwrite="true" />
<cfspreadsheet
    action="update"
    filename="#file1#"
	sheetname="CardTypes"
	query="collection.CARDTYPES" />

The code for the first cfspreadsheet tag takes the first query and writes an .xls file to display records exactly as shown in the query variable. The second cfspreadsheet tag updates the current .xls file and adds a second spreadsheet onto it (Excel Spreadsheets can have multiple pages, or different spreadsheets in the same .xls file).

This brings the entire processing time down from 4-5 minutes, to 4-5 seconds. That’s a HUGE difference! Sure, I don’t have all the formatting capabilities that ColdFusion allows for me to have. But the point of understanding came when I realized the people using the spreadsheet need everything laid out in simple rows. They didn’t need headers, spacers or data that was spread out in any fashion. They just needed a row-by-row list of raw data. So, this solution worked out perfectly. This makes XLS Exporting in Adobe Coldfusion 9 very easy to use.

Always remember, when programming using a combined group of different languages (i.e. – Adobe ColdFusion 9 with an MS SQL Database) you can always offload work from one to the other, depending on the application. Here, we took a 4-5 minute process in ColdFusion and gave that job to the database, which helped it run in less than 4-5 seconds. Using this methodology, you can program less and achieve more, and produce efficient applications and web sites!

“The NetConnection class creates a bidirectional connection between a Flash Player or AIR application and a Flash Media Server application or between a Flash Player or AIR application and an application server running Flash Remoting. A NetConnection object is like a pipe between the client and the server. Use NetStream objects to send streams through the pipe.
Without Flash Media Server, you can use the NetConnection class to play video and MP3 files from a local file system or from a web server.”

As you can see, NetConnection already opens up an array of possibilities. In this specific case scenario, let me first start off by saying that I was implementing the MVC design pattern (Model View Controller). I was building a small Adobe Air Application using the Flex 4 SDK, and heavily relying on ActionScript 3.0 for most of the coding. My objective was to call remote services on three different remote servers, which would return values stating that “Yes, this server is online.” Then using the variables that it returned, set up a custom event that would fire off stating whether or not the specific server was online. My Controller would listen for the event, and upon receiving it call the respective function that would change my view to say “Let’s turn on the green button instead of the red button, because this server is online!” Here is the code to set up a connection for a specific server:

NetConnection Example

Step 1: Import related classes
You’re going to want to import flash.net packages; NetConnection, ObjectEncoding, and Responder.

Step 2: Implement variables and Constructor
Implement whatever public class variables you want, and then pass in an null IEventDispatcher object in the constructor function and call the super of that class. This is only to prevent any issues with dispatching events from this ConnectionController class.

Step 3: Create a function to check a server
Make sure the return type of this function is void. Inside this, create a private variable by declaring the var keyword, for an instance of NetConnection, and any other variables having to do with this one specific function. Declare the ObjectEncoding variable, and the connect variable in the new NetConnection variable you just declared.

Step 4: Call a function and set up dispatchers
Use _gateway.call(locationOfFunctionOnRemoteServer, new Responder(functionIfReturnValue, functionIfError), ….arguments); to make a call to the server, you can implement this line for however many functions you want to call in this one operation. After this, set up the nested functions that are called in the _gateway.call method, and fire off dispatchers with the related custom event based on a return from the server.

And there you have it, a simple way to call and get a return value from a remote server in AS3.

There’s no point doing good work if others don’t know about it or can’t understand what you did. When it comes to developing lengthy applications a well written documentation is a must. A well written documentation which compliments your project’s design shows commitment to the project and a professional feel.

In Part 1 of this tutorial we covered ANT installation. Part 2 explains the best practices for writing comments inside your project’s classes which later are read by ANT and included in the project documentation. Part 3 is the final part of this series. It will help you understand how your documentation is structured, and what can be done to customize the HTML template used by ANT to generate the documentation.
The default documentation template is the same as the one used by Adobe to document the ActionScript 3.0 language. Here is a link which I am sure you have visited before:

http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/class-summary.html#top

Good to know:

What are HTML templates? An HTML template is a ready-made design of the HTML page. The HTML template usually include most of the source files necessary for further customizing the template. It can be edited using WYSIWYG editors such as Frontpage, Dreamweaver etc.

CSS - Cascading Style Sheets is a language used to create stylesheets in which you can describe presentation semantics, its used mainly with HTML and XHTML pages. It can also be used with Adobe Flash Builder and other. It’s a good practice to separate the styling of your project in a CSS file. This way the designer and the developer for example can work together and have a smooth workflow.

Where is the template used by ANT ?

The path to the template should look like this:
/Applications/Adobe Flash Builder 4.5/sdks/4.5.0/asdoc/templates/.

Inside the “templates” folder you will find all the components that make the HTML template. You cannot modify the template directly, but you can create a copy and assign it’s path in the ANT build script instead of using the default.

The CSS:

Through this CSS file you can assign styles to all the components that make your documentation pages. You can easily make changes to the documentation pages by modifying the styles.css (path: /Applications/Adobe Flash Builder 4.5/sdks/4.5.0/asdoc/templates/style.css).

In order to modify an element’s style you need to begin your declaration with the element’s class name. From then it’s simple. Assign the new properties as shown on the image above.

You can see the class names of the elements you would like to modify by opening the .html files of the template. Here is an example that shows where and how the class is defined for the elements and also how the stylesheet is assigned to the HTML page. If you have found a CSS stylesheet that fits your needs you could even save time and assign it instead of the default one. Then just make sure to change the class names for the elements that require customization. The global settings would stay the same.

Manipulating the HTML itself:

You could manipulate the HTML directly and change the layout of your page as well. I would recommend using Dreamweaver or other free editing software both for the CSS and the HTML. This would help you edit quickly and to see the results immediately as Dreamweaver for example has views that allow you to see the modifications live as you are making them.

Finishing up:

The range of modifications you can make to your template has almost no limits. All you need is a basic understanding of the HTML and CSS language and a good editor software.

Once you are ready to use the template or test it you need to assign it inside your build.xml file. (explained in Part 2) Here’s the example syntax:

<arg line="-templates-path '/Applications/Adobe Flash Builder 4/sdks/4.1.0/asdoc/YourTemplateName'"/>

Above is a snippet of one of CuriousMinds’ project documentation build.xml files.  As you can see there are settings editable directly through the build.xml file like the window-title and other. One of my favorite things to do is to make sure the company branding is displayed as well as the client’s. An ideal place for the Author’s name and the Company branding is the footer (line 66).

This is all there is to customizing you template. If you have any questions post and I will try to be quick to answer.

Happy coding!

NOTE: Please download attached source files from here to help you with this tutorial.

I wanted to make use of the Spring framework in my Java backend because of its flexibility and streamlined development. I wanted Hibernate integration also for data persistence to a MySQL database, which I knew Spring could provide me. It seemed to me that this stack would be the perfect combination of tools to get my application off the ground, but I wasn’t quite sure how to go about putting all these pieces together.

A little research on this topic revealed some solutions like Spring Roo with the Flex scaffolding extensions which, at least at first, seemed would glue all these components together with ease. I’m sure the Spring Roo project, once it matures a little and stabilizes, will be a viable way to generate the Java classes and Flex remoting scaffold necessary to build an application. That being said, the amount of difficulty I had in getting Spring Roo and Flex to work together was immense. I also have a huge aversion to using new tools to generate code for me that are not yet widely embraced or supported by the community at large, and which I don’t fully understand inside and out. When eventually the excrement hits the air circulation device, I want to know exactly where a system is failing and why, even if it means spending a few extra hours writing boilerplate code from scratch. I do, however, appreciate the work that Jeremy Grelle et al. have done on this project, but at present, the Roo-Flex project isn’t stable enough for my tastes. Upon realizing this, I decided to roll up my sleeves and tie the pieces together myself.

Setting up BlazeDS and Tomcat

BlazeDS is a great way to get Flex and java talking to one another. It is free, which lowers the cost barrier for you and your client, and is relatively easy to install. A popular method of getting up and running quickly is to install the BlazeDS turnkey server. This is ostensibly a Tomcat server, bundled with a bunch of very typical examples of how BlazeDS can be utilized. You can download this package from the Adobe Labs Website, or if you already have a Tomcat installation you want to develop against, you may grab the WAR file and deploy it yourself. Instructions for deploying BlazeDS, starting the server and running the examples can all be found on the website, and in the enclosed documentation.

Maven Management

Once you have a Tomcat installation and BlazeDS running in the container, we can start thinking about how to structure our java project and how to incorporate the Spring and Hibernate libraries into our project. I found SpringSource Tool Suite (STS) to be a useful IDE to develop the java side of my application. It is another Eclipse spinoff, so those familiar with this IDE will feel right at home in these environs. If you use Maven to manage your project dependencies, you can get almost everything you need by adding the requisite nodes to your pom.xml file, or by using the M2Eclipse pom editor to search for and manage your project jars. You can find instructions on installing M2Eclipse for STS on the M2Eclipse project website, and you can get SpringSource Tool Suite from here.

Once we have these pieces in place, let’s start by making a new project in STS. Choose ‘New Java Project’ from ‘File’ in the main menu of the application, and give it a name. This is the most basic java project configuration, to which we are going to add Maven support, as well as some project facets to get the resources and structure of our project tightened up. The next thing we want to do is enable dependency management with Maven. We’ll do that by right clicking on the project in our package explorer, and choosing ‘Maven -> Enable Dependency Management’. Here we are presented with some options. Because we are just creating a simple tutorial application here, I’m leaving my Group Id and Artifact Id alone, and providing a simple name and description for the heck of it. When finished with this step, a pom.xml file will be created in the project folder which we can edit to add dependencies automatically to the build path.

Project Facets

The way Eclipse organizes a project and structures a project to make it runnable in different environments is to add ‘facets’ to the project. We are going to add facets to this project now to transform this ‘vanilla’ java project into web application deployable to our Tomcat server. Again, right click on the project folder in the Package Explorer and choose ‘Properties’. You’ll see a menu item in the list called ‘Project Facets’. Choose that, and click the link to ‘Convert to faceted form…’. From the list that appears in the Project Facets Pane, select the ‘Dynamic Web Module’ checkbox, leave the ‘Java’ checkbox selected and click ‘OK’.

If you were paying attention you’ll notice that Eclipse just created a folder called ‘WebContent’, and  ‘META-INF’ and ‘WEB-INF’ folders inside that folder. This is the basic structure our java web application will take on when we export and deploy it.

Spring Dependencies

The Maven dependencies found in the attached project’s pom.xml file will give you the libraries we’re going to make use of in the next step of our tutorial. Note that there may be updates to some of these release jars by now, but avoiding the confusion of dependency compatibility is one of my goals in writing this post. Try using this list of dependencies before looking for newer releases, and save yourself some aggravation.

Feel free to copy this list directly into your project’s pom. Once we have done this, we are ready to begin building our java application’s context. You should also see that in the package explorer, our folder containing Maven Dependencies has 17 new jar files in it. These are, of course, the dependencies we’ve just added to our pom.xml.

Spring Flex Integration Jars

In addition to the above resources, we’re going to need the Flex Spring integration jars. You can get them from the following address.

Once you’ve downloaded these jars, you’ll want to make sure they get deployed along with your maven managed jars. I made a folder inside my project called ‘jar’ into which I’ve placed additional dependencies. I’ve included my jars folder here in the project archive, so you can unzip that folder into your project directory and use them. There are a few other jars in this folder. Do yourself a favor and use my jars because there are some dependencies that we have not discussed, which I spent too many hours starting and restarting my server, getting ClassDefinitionNotFound errors, and searching the web for the correct jars containing the right Classes to get this project running. Please trust me on this one. To get the items in the ‘jars’ folder to deploy properly, you want to make sure there is a corresponding entry in your ‘Web Deployment Assembly’ properties for this project. Go into the Properties for this project and select Deployment Assembly. This is where we can define mappings for deployment of our resources. If it isn’t done already, map your jar folder to ‘/WEB-INF/lib’. Our jars will now be in place when we deploy our web application.

Part I Wrap Up

Because this process of building all the components that make up this application is quite involved, I am breaking this into smaller, less daunting steps. We now have an STS project with all of the foundation to start coding our backend, and after that, to call our services from a Flex client. Be sure to check back soon for the second part of this tutorial, when we get into some of the more fun aspects of building this project.

Option #1. Import the .fl classes into Flash Builder.

This probably the easiest way to get some components on the screen, and the only way that I have gotten controls to work properly.  Go into Flash and create a new AS3 project. Drag the components that you need onto the stage, and export as a .swc . Import this .swc into the classpath of your FlashBuilder project and you will have access to scrollbar, button, list and slider .fl classes.

Option #2. Try to bootstap mxml (not a real great idea.)
The other option, for example, if you would like to use the super cool FlexPadLib. This is extremely difficult to get right, but you can find some resources on it here.

Option #2a. Hack Flex Mobile Project to compile to Ipad. This is probably your best option. The walkthrough can be found here.

Option #3 try using Iphone styled components for As3. I don’t know the status of the project, but you can check it out here.

Option #3a use a very minimal comp set such as MinimalComps, or Reflex

Option #4. Wait for Adobe to update Air for iOs Devices. Along with using the Flex Mobile components, we would also like to see some other nice to haves like native alert window, and background alerts.

This tutorial covers the documentation process for Ant on Adobe® Flash Builder 4.5. You will be presented with the most common ASDoc comments, their purpose and output in the generated documentation, and examples of documentation page templates and their customization process.

This is Part 2 of the Ant and Flash Builder 4.5 tutorial. If you have not yet installed and setup Ant on the standalone version of Flash Builder you can refer to Part 1. There you can get a step-by-step instruction on how to install and setup Ant.

Once you have installed and properly setup Ant on Flash Builder, it’s time to write some ASDoc comments in ActionScript® . When you generate the documentation later this code will be recognized by the Ant documentation tool and included in the generated project documentation. If you are thorough in your comments and update them along with the project’s development process, you will end up with one well written and detailed documentation and you will never forget what each class is used for.

Good to know:

•  Adobe’s help documentation is very detailed and shows all the best practices regarding the documentation process. It contains AsDoc comment examples and their formatting for all types of ActionScript classes.You can visit their documentation here.

This post is an addition which will help you instantly see what the result of the most common AsDoc comments looks like in the generated documentation. I will also cover a few mistakes that are common and if not minded can slow down your workflow or be the cause for errors which can go unnoticed by the documentation tool.

•  There is a list of HTML tags you can use to format you AsDoc comments. Bear in mind that this list of tags is limited, and that while in some sections of an AsDoc comment you can use them, in other places they are not accepted and can produce an error.
A summary of these HTML elements can be found here

•  There are two types of AsDoc comments: ActionScript comments and MXML comments.

Examples:

ActionScript comments are declared to start with  /**  character sequence and the end is declared by */. Read the example below:

 /**
*  The first sentence would be used to describe
*  the class. Next sentences only show in the
*  class' detail view.
*/

An example of an AsDoc comment used to describe a class.
output:

Above is a list of classes and their short descriptions generated by the documentation tool. The short description on the right is the first sentence in your AsDoc comment for that class.

Below is a view of the same class’ Detail Page.

• Commenting Functions:

/**
* AsDoc comment for the <code>onViewClick</code>
* method.  HTML tags <strong>can</strong> be used
* here.
* @param evt Parameter tags are
* descriptions of the parameters this
* method can take in.
*/
override protected function onViewClick(evt:MouseEvent):void{
switch(evt.currentTarget){

output:

Above is a snapshot of a Class Detail View page generated by the documentation tool.

MXML AsDoc comments:

Comments start with the <!--- characters and
end with  --> character.

This comment is placed after the xml ecoding declaration and does not require a CDATA block. You can use the same comment structure when you are commenting MXML components such as buttons, DataGrids, etc.

Here is an example of invalid implementation of the <h1>Header 1</h1> tag used where it does not belong. The text encapsulated in the wrong tag is simply omitted in the output. If these errors are not corrected you would end up with unreadable documentation.

This is an MXML AsDoc comment.
output:

Above is a snapshot of a Class Detail View page generated by the documentation tool.

Errors

My advice is when you start a new project always setup your documentation along with the project. There is nothing worse than an already built project that you have to create documentation for. When you are put in a situation where you have to document an already created project prepare to be patient and expect errors.
Here are a few common things that would cause a Build fail:

• Improperly imported classes or classes that have not been imported at all. Even though Flash Builder will run your project, and build successfully, the documentation tools will fail at that obstacle.

• Undeclared in the build file external resources and related projects. If you have read Part 1 of this tutorial, you must now know about the “-source-path”, “-doc-sources”, “-external-library-path”, and my personal favorite “-exclude-classes”. Declare all external resources because they are mentioned in your project’s code and the documentation tool would look for them, but will not find them unless you specify their paths in your buildFile.xml.

• Be careful where you place your build-file. You cannot modify the example build-file you will find in the Ant folder, but you can copy and customize it. I place my build-files directly in this location: /Applications/Adobe Flash Builder 4/sdks/4.1.0/ant/yourBuildFile.xml.

• Spark and Halo do not always mix when it comes to documentation. Below is an example of what happens when you have halo for a project theme but you have used a spark component. 
Ant build Error.

I will keep adding to this list every time I meet a new issue regarding documentation generation.

Next is Part 3 of this tutorial, where I will cover template customization. This way your documentation can take on a view and feel closer to that of your project, and I promise you good presentation always pays!

Happy coding!

Many of the differences you’ll encounter in connecting to popular social media sites has to do with the tooling available to Flex Developers targeting the AIR runtime. Many services (Facebook, Twitter, LinkedIn to name a few) utilize OAuth 2.0 protocol for interacting with users’ data in a secure way. OAuth, in case you’re not familiar (and you will be very shortly), is “an open protocol to allow secure API authorization in a simple and standard method from desktop and web applications”. You can read the specification at http://tools.ietf.org/html/rfc5849 if you want to find out more.

OAuth basically requires that you do the following steps in order to allow the user the opportunity to grant access to your application to manage data on his or her behalf. This is an overview of the process. We will look at the specifics of how to connect to LinkedIn in a few moments, using the following basic information as a primer (or a review depending on your level of familiarity with this process).

Step 1: Register your application with the service you wish to connect to and receive a Consumer Key and Consumer Secret.

Step 2: Your application makes a request to the service to authenticate a given user. Successful completion of this step will yield a Request Token.

Step 3: The application redirects the user to the service’s sign-in and authorize page, where the user must agree to allow the app to make service calls on his behalf.

Step 4: The application, upon receiving the consent of the user, exchanges the Request Token for an Access Token. This token consists of two Strings, the token and the token secret, and will be used to “sign” (a secretive process we’ll discuss in a moment) the API requests.

Step 5: Call the resource you wish to consume (status update, personal info, etc..), using your Access Token (and a few other variables) to sign the request.

There are a numerous code libraries available for connecting to the various social media. Probably the easiest to use of these is the FacebookDesktop Object, part of the com.facebook.graph package. Right out of the box, this tool makes it quite easy to connect to Facebook’s “Graph” API, abstracting most of the ugly details of the OAuth process we’ve just enumerated. This nice little kit practically does all of the work for you, and is very simple to set up and use in your desktop app. If you need to communicate with Facebook, I highly recommend this tool.

For the purposes of this post however, I’d like to focus on LinkedIn’s API. Connecting to this service represents the other end of the difficulty spectrum in my opinion, and required quite a lot of tinkering to implement successfully. I have spent many hours refining this code. It is my hope that this tutorial will fill the enormous informational void on this topic, and help out some others where I had quite a lot of difficulty. Please grab the src folder for this sample application here. There are some functions in the source that are not included in the text of this tutorial, and I think it will serve you best to actually run this application while reading along. The tools I used to connect to LinkedIn were from the same code library I used to connect to Twitter, the OAuth lib called “oauth-as3” from iotashan http://www.iotashan.com. You can grab the latest source for this project from the following svn location: http://oauth-as3.googlecode.com/svn/trunk/. There is also a dependency introduced when we include the iotashan packages. Go ahead and grab the as3crypto swc from the following URL http://code.google.com/p/as3crypto/downloads/detail?name=as3crypto.swc and include that in the build path for your project. Alternatively, you can also grab the source from google code if you prefer to see what exactly is going on under the hood, as I have in the sample application.

So, let’s get into the code now. Admittedly, this isn’t the most impressive application I’ve ever written (from a UI standpoint), but the control flow is what we’re concerned with here, and the functional elements are pretty straightforward and informative. In order to run this application, you’ll need to register an application with LinkedIn to obtain your own Consumer Key and Consumer Secrets. I’ve indicated on lines 45 and 46 of my source where your Strings should be inserted to make your application unique from LinkedIn’s perspective. The entry point for this whole handshake process is found on line 60 in the ‘post()’ function below. This is called after you enter some comment text into the field, and hit the Submit Button on the UI.


private function post():void{
_comment = commentArea.text;
var shOb:SharedObject = SharedObject.getLocal(_sharedObName);
var tmpTok:Object = shOb.data["accessToken"];
_oauthConsumer = new OAuthConsumer(_consumerKey, _consumerSecret);
_signatureMethod = new OAuthSignatureMethod_HMAC_SHA1();
if(tmpTok){
var token:OAuthToken = new OAuthToken(tmpTok.key, tmpTok.secret);
doStatusUpdate(_comment, token);
} else {
hiOauth_CareToDance();
}
}


In this function we set up some basic variables (our OAuthConsumer and OAuthSignatureMethod_HMAC_SHA1 Objects) which we’ll need for making our requests, as well as check for the possibility that we’ve already got a valid Access Token stored in a Shared Object called ‘linkedInData.acessToken’. Let’s assume that tmpTok comes back null (line 68), and we need to go through the entire process of getting both the Request and Access Tokens from LinkedIn. We proceed to the function called ‘hiOauth_CareToDance()’ which is the point at which we’ll be requesting the Request Token.


private function hiOauth_CareToDance():void{
_requestParams = generateParams(_consumerKey);
_oauthReq = new OAuthRequest(_reqMeth, _requestTokenURL, _requestParams, _oauthConsumer, _token);
var postData:Object = _oauthReq.buildRequest(_signatureMethod, OAuthRequest.RESULT_TYPE_POST);
var urlReq:URLRequest = new URLRequest(_requestTokenURL);
urlReq.method = _reqMeth;
urlReq.data = postData;
var loader:URLLoader = new URLLoader(urlReq);
loader.addEventListener(Event.COMPLETE, onComplete);
loader.addEventListener(IOErrorEvent.IO_ERROR, onIOError);
loader.load(urlReq);


function onComplete(evt:Event):void{
loader.removeEventListener(Event.COMPLETE, onComplete); loader.removeEventListener(IOErrorEvent.IO_ERROR, onIOError);
_token = generateToken(evt.currentTarget.data);
_requestParams.oauth_token = _token; authenticate(_requestParams, _token);
}

function onIOError(evt:IOErrorEvent):void{
trace('FAIL!');
loader.removeEventListener(Event.COMPLETE, onComplete); loader.removeEventListener(IOErrorEvent.IO_ERROR, onIOError);
}
}

You’ve seen URL Requests similar to this already, but the important thing to note here is that we want to make use of our OAuthRequest Object to create the data we’ll add to the URLRequest’s ‘data’ property to send along in our POST Request. I’ve passed a few variables into the constructor of this Object to set it up, and called the instance’s buildRequest method to get back an Object containing everything LinkedIn wants to see in order to issue us a Request Token. On Event.COMPLETE we move on to the function called ‘authenticate’ after adding our token (_token) to _requestParams.oauth_token. I’ve created a convenient little utility to parse the returned data from this request and turn it into an OAuthToken Object. This function is called ‘generateToken’. In the ‘authenticate’ method we’re navigating to LinkedIn’s authentication URL, which allows the user to grant our application control to access and manipulate personal data on the user’s behalf. We also pop up a little window which gives the user a text input into which he or she will enter the 5 digit PIN number that LinkedIn’s authenticate window will supply us with. This function is called ‘popAuthWindow’.


private function authenticate(params:Object, token:OAuthToken):void{
var getReq:URLRequest = new URLRequest(_authenticateURL + '?oauth_token=' + token.key); navigateToURL(getReq, '_blank');
popAuthWindow();
}

PopAuthWindow is really quite basic as well, but the one thing to notice here is that I’ve set a variable called ‘submitCallbackFunc’ to a function called ‘authenticateCallbackFunc’ which will get called when the user clicks the ‘submit’ button in the popup window. I find this to be a little easier and more straightforward than creating a custom event for communicating between the popup and the main application, but you may have your own opinion about the cleanest way to accomplish this. This function will accept the pin number. Let’s look at this function now.


private function authenticateCallbackFunc(pin:String):void{
_requestParams.oauth_verifier = pin;
var authReq:OAuthRequest = new OAuthRequest(_reqMeth, _accessTokenURL, _requestParams, _oauthConsumer, _token);
var postData:Object = authReq.buildRequest(_signatureMethod, OAuthRequest.RESULT_TYPE_POST);
var urlReq:URLRequest = new URLRequest(_accessTokenURL);
urlReq.method = _reqMeth;
urlReq.data = postData;
var loader:URLLoader = new URLLoader(urlReq);
loader.addEventListener(Event.COMPLETE, onComplete);
loader.addEventListener(IOErrorEvent.IO_ERROR, onIOError);
loader.load(urlReq);


function onComplete(evt:Event):void{
loader.removeEventListener(Event.COMPLETE, onComplete); loader.removeEventListener(IOErrorEvent.IO_ERROR, onIOError);
_token = generateToken(evt.currentTarget.data);
_requestParams.oauth_token = _token.key;
_requestParams.oauth_token_secret = _token.secret;
var so:SharedObject = SharedObject.getLocal(_sharedObName);
so.data["accessToken"] = _token;
so.flush();
doStatusUpdate(_comment, _token);
}

function onIOError(evt:IOErrorEvent):void{
trace('FAIL!');
loader.removeEventListener(Event.COMPLETE, onComplete); loader.removeEventListener(IOErrorEvent.IO_ERROR, onIOError);
}
}

This looks an awful lot like the ‘hiOauth_CareToDance’ function we’ve already discussed, but were the ‘_token’ variable was null before (we hadn’t yet gotten our Request Token) we are now going to have the data returned from our call to the Request Token resource. In this step, we are ostensibly trading the Request Token for an Access Token. We make use of our handy OAuthRequest Object once again to put together the variables and the signature needed to gain access to LinedIn’s Access Token resource, and populate the URLRequest’s data property with our return from the buildRequest method. On our Complete Event, we will again be given another bit of data from which we can parse our ‘oauth_token’ and ‘oauth_token_secret’. At this point we have been fully authenticated, and have everything we need to call the actual API resources we might wish to utilize in our application. So, knowing this we can finally call the status update resource, and submit our comments we had typed into our comments text input. We do this in the ‘doStatusUpdate’ method.


private function doStatusUpdate(comment:String, tok:OAuthToken):void{
if(!_requestParams){
_requestParams = generateParams(_consumerKey);
delete _requestParams.oauth_token_secret;
delete _requestParams.oauth_verifier;
var oauthGen:OAuthRequest = new OAuthRequest(_reqMeth, _statusUpdateURL, _requestParams, _oauthConsumer, tok);
var header:URLRequestHeader = oauthGen.buildRequest(_signatureMethod, OAuthRequest.RESULT_TYPE_HEADER);
var urlReq:URLRequest = new URLRequest(_statusUpdateURL);
urlReq.method = _reqMeth;
urlReq.requestHeaders.push(header);
urlReq.contentType = 'text/xml';
urlReq.data = generateLinkedInStatusXML(comment);
var loader:URLLoader = new URLLoader(urlReq);
loader.addEventListener(Event.COMPLETE, onComplete);
loader.addEventListener(IOErrorEvent.IO_ERROR, onIOError);
loader.load(urlReq);

function onIOError(evt:IOErrorEvent):void{
// if we hit this.. our token must be expired..
hiOauth_CareToDance();
}
}


We see some familiar elements in this, such as the OAuthRequest and the URLRequest variables, but you’ll also notice that we have introduced a URLRequestHeader in this function which we did not have previously. The reason for this is that we are now transmitting two necessary pieces of data over the wire, not just one. We have to supply our Access Token so that we can demonstrate to LinkedIn’s servers that we are legit, but we also want to send some data to update our status at the same time. This was a little tricky for me to figure out, so I’m hoping that this demo makes even one developer’s life a little easier (ten would be even better). In order to do this, we will again build the OAuth signature with the OAuthRequest, but since we are going to want to use the data property of our URLRequest for the status update XML, we need to change the mode of our OAuthRequest to OAuthRequest.RESULT_TYPE_HEADER. You’ll notice this on line 89 of the sample application. When we change the request type to header, we get back a URLRequestHeader instead of a generic Object. This we can then push into our requestHeaders array. LinkedIn is able to deal with this accordingly, and will verify the validity of this request based on the header, and not the data of our request as we had done previously. As for the data in this step (the actual status comment), I have created a very basic ‘generateLinkedInStatusXML’ function which creates the most basic status update markup from our comment input text. You can do more with this data if you so desire. Please refer to the LinkedIn API reference pages for more information on this.

In addition, make sure you set the content type of your URLRequest to ‘text/xml’ or you will not have success in making this call (yet another trap I fell into during this arduous process). There are also 2 lines of code deleting certain items from the _requestParams data before we make this request. These 2 variables were necessary in previous steps of the OAuth authentication process, but which we no longer need now that we have the Access Token. Don’t pay too much attention to these. I believe you can leave those intact, and it will have zero effect on the success of this call.

OK, with a little bit of luck this request will come back successfully and our application will alert us to the fact that our status has been updated. Hop on over to your LinkedIn profile and verify that the message did make it onto your wall (or whatever they call it in LinkedIn parlance).

Congratulations! You have just successfully navigated the tedious OAuth handshake, and are now able to build out a more useful and full featured application based on this new knowledge.

Okay, manifesto or thesis time. My main points for this reality check are these:

1. I don’t want the flash player on my iphone at all. Not anywhere near it.
2. HTML 5 is not going to replace Flash for web interactive anytime soon.
3. Goddamn, coding for the IPhone is tedious.  (more of an observation, really)

You probably don’t agree with me on some of the points above, and I am sure that the bad – ass Ob C devs out there are going to flex, (no pun intended) but let me explain myself here. Point #1. The Flash player is a memory gobbling whore. There, I said it. There is no way that Adobe or anyone else will be able to get any virtual machine running efficiently enough for me to what to run it on my Iphone.

The code that I want running on my Iphone is stuff that uses memory like it was the early 80′s. Especially when its running on a device that I could wind up really needing in an emergency. (or for that matter all of the time.)

Point #2. I may eat my hat on this but HTML5 canvas element? Really? Am I not the only one who remembers the marquee tag? How about the fact that I have to create 6 different versions for every HTML website we put out? The real beauty of the Flash player is it’s consistency across platforms. Nothing is perfect in this regard,  but Flash is pretty damn good.

Point #3. Garbage Collection aside, coding for the IPhone is pretty darn laborious. And that brings me to an important point: Flash, hands down has the best toolsets to code in, period. (I say this as I’ll be cursing a corrupted Flex dot-dammit project file tomorrow.)

The conclusion of this ill advised mess is that Flash is going to be around for quite sometime. Not on Apple’s mobile devices, and for good reason. And honestly, not for serving up video on the web either. And here is the kicker. I think that the flash developer’s toolset will evolve to match the current popular platforms, One IDE to rule them all…