Packt Publishing

Including the Facebook ActionScript 3 SDK in a Flash Builder project

Your situation, experience, personal preferences and the complexity of your final project dictate exactly how you'll integrate the Facebook ActionScript 3 SDK into your project. In this recipe we're going to use the precompiled SWC files that we've downloaded in our earlier recipe, Downloading the Facebook ActionScript 3 SDK, and integrate them with a new Flash Builder project.

How to do it...

Within your project structure you will, by default, have a libs folder. Copy your downloaded SWC file into that folder, and at a basic level, that's all there is to it.

The classes from the Facebook ActionScript 3 SDK will now be available to your project—you should get auto-complete code suggestions as you type, and more importantly, be able to compile your code!

How it works...

An SWC file is a compiled set of source files—which could be ActionScript source code or symbols and images—and is a useful way of making your source code available for others to use, while still protecting the actual original code. Anyone with the SWC can get access to the classes it contains and all their properties and methods, but can't actually see the code behind those methods. Of course, protecting the code isn't a huge concern for the Facebook ActionScript 3 SDK, as we can get all of the source code from other sources anyway.

The great thing about using a SWC file is that it minimizes the clutter of source files in your project—you don't need to include anything more than the SWC, whereas if you wanted to use the actual source files, you'd need to add 20-odd additional ActionScript files. That might not sound bad, but when you start using the source-code versions of multiple ActionScript libraries, you can easily end up with 10, 20, 50, or more ActionScript files that aren't actually written by you for this project.

Another little plus with SWC files are that they're precompiled, which theoretically means lower compile times for your project. I don't think it actually makes much of a difference for this SDK, but every little bit helps I guess!

There's more...

What about the downsides of SWC files? Well, the main downside of a SWC file is also partially the reason it exists—that you can't see the actual source code. If you want to browse through the source code, but still get the advantages of using a SWC file in your project, follow the next recipe Including the Facebook ActionScript 3 SDK as a Flash Builder library project.

If you're using a SWC exclusively then you'll be flying blind if you should trigger errors on the classes you don't have the source code for, and will be presented with a dialog similar to this:

Informative, but really not helpful when you're trying to find out where your code is breaking down. Luckily there's a solution for that, and it is by linking source files to an included SWC.

Of course, when it comes to Runtime Errors, it's more likely that the error is in your code, rather than the Facebook ActionScript 3 SDK. Linking to the source is more about helping you find and debug your own errors, rather than searching for errors in the SWC.

Linking source files to an included SWC

Before we start out, it's important to note that linking source files to an included SWC file doesn't actually have any effect on the SWC itself. Instead, what we're doing is giving Flash Builder the location of the SWC's source files.

When Flash Builder tries to open your project in debug mode it will use this information, but it won't magically enable Flash Builder to recreate the SWC file for you—for that you need to set up the code as a Flash Builder library project (which is, coincidentally, the subject of the next recipe).

Once you've downloaded the Facebook ActionScript 3 SDK source files, place them in a sensible location somewhere on your computer—it doesn't matter where exactly, only that you remember the location.

Open your project preferences screen, and switch to the tab Flex Build Path and within that, Library path:

In the preceding screenshot, you can see the GraphAPI_Web_1_0.swc file, and underneath that you can see there is a Source attachment option—double-click on that to open a new window, labeled Edit Folder Path:

From this dialog you can select the location of the source files for the SWC. There won't be any visual confirmation whether the location you've selected is correct or not, but when you start coding or debugging, you should be able to explore the source code of the classes in the SWC, and see far less of the Code Navigation Error dialog.

Including the Facebook ActionScript 3 SDK as a Flash Builder library project

An alternative to including the Facebook AS3 SDK in its precompiled SWC form is to set up the SDK as a Flash Builder library project.

The end result, as far as the compiler and the user are concerned, is no different, but our own way of developing, reusing, and exploring the code is a little simpler. And unlike the precompiled SWC files that can be downloaded from the GitHub repositories, by using a Flash Builder library project, we can make modifications to the source code.

Using a Flash Builder library project makes it easy to reuse the code in the library in multiple other projects, and for the remaining recipes in this article we're going to be linking to the library projects that we set up in this recipe.

There are two versions of the Facebook ActionScript 3 SDK, and just as there are two versions of the precompiled SWC to download, we will also need to create two Flash Builder library projects. In this recipe we're going to cover setting both of these library projects up and linking to these library projects from other projects.

How to do it...

Create a new library project in Flash Builder, using the basic Flex SDK only (don't include the Adobe AIR libraries), and call it Facebook Web SDK.

Copy the files and folders from the downloaded facebook-actionscript-api folder to the root folder of our project, setting up the following folder structure:

That will create a library project which we can use in basic Flash Player-based web projects. Next, we'll create a project that gives us the Adobe AIR version of the SDK.

Keep the Facebook SDK Web project open, and create a new Flash Builder library project; call it the 'Facebook Desktop SDK', only this time, be sure to include the Adobe AIR libraries in your project.

As with the web version of the SDK, copy the files you've downloaded from the facebook-air-api folder into our new library project, creating the following folder structure:

Not much to see in terms of source code, is there? Unlike the web version of the SDK, the desktop version isn't completely standalone; it relies on core classes from the web project—so what we need to do now is add the web project to the desktop project as a linked library.

Open your project preferences, go to the Flex Library Build Path and then the Library path' tab, then click Add Project... and select the Facebook Web SDK project.

Once the web project is added as a library for the desktop library project, both of those projects should be able to compile, and that's it for this recipe.

How it works...

The complexity in this setup is just realizing that the Desktop version of the SDK is not a standalone library, and does, in fact, require all of the code from the web version. The source code files aren't duplicated for both versions because that would make things more complex to manage, and rather than merging the two sets into a single library project, we have to set things up in a way that keeps all of the AIR-specific source code in its own project.

Both versions of the Facebook ActionScript 3 SDK—Web and Desktop—rely on a core set of classes. The source code for the web version of the library contains all of these classes, whereas the desktop version of the library contains only the classes that require the AIR libraries, which is why it needs to be set up like this—to inherit those core files from the web project.

There's more...

The original release version of the Graph API—version 1.0—included an additional JavaScript file—the FBJSBridge.js file. Since version 1.5 of the SDK there's no need for this additional JavaScript file—the Facebook ActionScript 3 SDK works to inject the original contents of that file into the containing HTML page, removing the necessity for those additional files, leaving only the ActionScript SDK as a requirement.

Summary

Before our web-based application will be able to work with the Facebook Graph API, it will need the Facebook JavaScript SDK to be included in the host HTML page, and it will have to be hosted on a domain or subdomain specified in our Facebook Application settings.

Packt Publishing

How it works...

The web-based version of the Facebook ActionScript 3 SDK has been developed with a reliance on the Facebook JavaScript SDK being included in the containing HTML page—hence the requirement for us to extend our HTML template to incorporate this SDK.

When we add the script tag to our HTML template—using the URL http://connect.facebook.net/en_US/all.js as the source location—we are importing the Facebook JavaScript SDK from the Facebook.com servers. There are a few fringe benefits to loading the JavaScript SDK in this way—it keeps the SDK up-to-date and it helps with caching resources, but the primary reason for loading the SDK from the Facebook.com domain, rather than downloading it and packaging it alongside the HTML and SWF files on our own servers, is that this avoids a lot of potential for cross-domain scripting issues, and makes domain-restricted information such as cookies available to our application.

The addition of an HTML element with an ID of fb-root is part of the basic requirements for the JavaScript SDK, which are also discussed in more detail in the Facebook Developer documentation:

In short, the JavaScript SDK needs an actual element on the HTML page to hook into, and that element is one with an ID of fb-root—which is hardcoded into the SDK itself.

There's more...

What we've done is in this recipe is simply to set up our project so that it will be able to work with the Facebook APIs, when it's uploaded to the domain that we've specified for our application, in the applications' settings, in the Facebook Developer center.

Testing and debugging our Flash Builder project locally

The Graph API automatically rejects requests that use our Application's API Key if those requests come from a domain other than the domain specified by the Site URL and Site Domain settings—which means that if we try to test our code using URLS like:

C:\Workspace\Facebook Example\bin-debug\Facebook.html

or

file://Users/Admin/Workspace/Facebook Example/bin-debug/Facebook.html

the Graph API would automatically reject requests originating from those URLs, because they're not on the domain specified in our Facebook Application settings.

In actual fact, trying to work with these URLs would likely throw a Security Sandbox Error from the Flash Player before things even got to the point of communicating with the Graph API. The ideal setup to avoid this is instead to have a HTTP server running locally that can deliver these same HTML files, but from an http:// protocol, such as:

http://localhost/Facebook%20Example/bin-debug/Facebook.html

This would avoid any Flash Player security issues, but requests to the Graph API would still be rejected, because the domain, localhost, is not the same as the domain specified in our application settings (in my case, psyked.co.uk).

To develop efficiently for Facebook, we should expect to be able to code and test frequently, without the constant need to upload and re-upload our Flash application to a remote domain, yet still have everything work as if our application were online at the domain outlined in the Site Domain setting we previously specified.

To test our application locally, we must have an HTTP server installed and running on our computer, something like the Apache HTTP Server, which is available from: http://httpd.apache.org/.Support for server-side languages isn't important for our needs—all we require is the ability to launch our Flash Player application from an http://-based URL, rather than a local or network path.

There are two approaches we can take to get a Project that we have running locally to work with the Graph API:

Adjust the Site Domain project setting to work exclusively with the domain localhost. OR

Use setup a subdomain (such as localhost.psyked.co.uk) on our live website domain that points at our local machine.

Either of these solutions is valid—they both conspire to ensure that the Site Domain in our Facebook Application settings and the current URL that we're viewing match up.

If we choose the first option—adjusting our Site Domain property to say localhost—it should allow our local machine to work with Facebook, but at the cost of our live, publicly-accessible website not being able to communicate with the Graph API. Of course, that doesn't preclude us from setting up more than one Facebook application—a local development and live deployment application, if necessary.

The other alternative—using a subdomain—assumes that we can manage our top-level domain and create entries for new subdomains. All that is actually required for domain validation with the Graph API is that the computer on which the code is running believes that it is running on a specific domain—not that the domain is actually valid, or even that the domain even exists.

Thus we could create a new subdomain on our live website, such as localhost.psyked.co.uk, and have it point at the IP Address 127.0.0.1. For users without an HTTP server installed, they'll see nothing, and for developers like us, we'll see our own local HTTP server.

With our allowed domain effectively being *.psyked.co.uk the requests from localhost.psyked.co.uk will be accepted by the Graph API, and we can test our code much faster.

Where can users access our Facebook application from?

There are (currently) three main kinds of Facebook-enabled applications. These are:

Facebook Canvas applications

Facebook Page Tab applications

Websites with Facebook integration

This categorization represents the route by which users discover our application, as much as anything else. From a technical perspective, our application is always an HTML page, with a Flash Player application nested inside.

Canvas and Page Tab applications are actually HTML iframe elements on the Facebook.com website—they appear within the normal Facebook website interface, but the content that's being displayed comes from your own web server, and the same content is technically available from outside those iframe elements, if you have a direct link.

For example, we can have a Canvas application accessible from the URL:

http://apps.facebook.com/packt_facebook/

But the HTML source for this Canvas application is actually located at the URL:

http://facebook.psyked.co.uk/packt/

The integration of these two separate websites is seamless for the end user, but the context of each places different constraints on our application in terms of the dimensions of the application.

Setting up a Canvas or Tab application on Facebook.com

To set up our application so that it appears within the Facebook.com website as a Canvas or Page Tab we need to visit the Facebook Developer center and edit the settings of our Facebook Application, which we can do via the URL:

Select an application, click Edit settings, and then go to the Facebook Integration section, where you can make specific entries for the Canvas URL and Tab URL parameters—choosing exact URLs that point to an HTML page that would be formatted correctly for the dimensions of the iframes. Canvas applications are 760 pixels wide and Tab applications are only 520 pixels wide.

Not every application has to be a Canvas or Page Tab application, however. It doesn't even have to be an application on Facebook—it can just be one that interacts with Facebook, so long as our Flash application remains within the Site Domain boundaries we've specified in the Facebook Developer center.

Working without the JavaScript SDK?

If you are adding Flash elements to a Facebook application you've already developed in a server-side language, then you may find that you don't need to worry about adding additional JavaScript files to the mix.

Say for example you've already developed a Facebook login process; using Facebook's own PHP SDK, you could simply forget about including the JavaScript SDK and instead use FlashVars to pass in the session data and authorization tokens at the point the page is generated. Not only would you not need to load an additional JavaScript file, but you'd also not have to make duplicate session requests with Facebook, which should speed things up a little.

Summary

The key point is that Facebook cannot always know—and doesn't really care—how you're making requests to its APIs, only that you do so with valid authorization tokens and request parameters.

Packt Publishing

Corporate Identity

Since this has worked so well, we will waste no time and get to the other relevant jdoc tag insertions. The command: <jdoc:include type="modules" name="top" style="none" /> for example, expects the type of insertion as type parameter, in our case modules. The name parameter marks the position of the module (top, right, left, user1, ...) on the website. You can assign this position to your module from the Extensions | Module menu in the Module Section. The style parameter, finally, contains a value that pertains to the type of HTML code that is being delivered by the module. For example, none delivers pure HTML output without the surrounding <div> tags. The following table describes the module parameters:

Parameter

Output

table

The module is displayed in a table.

horz

The module is displayed horizontally in a cell of a surrounding table.

xhtml

The module is output in an XTML-compliant div element.

rounded

The output is in a format in which round corners can be displayed. The class of the element is changed from moduletable to module.

beezDivision

Special switch for the Beez template. The size of the header can be changed with this. This switch is not available outside of the Beez-template.

none

The module is output without any formatting.

You can get a description of the jdoc insertions in the index.php file in the following listing.

If you call up the website with the modified HTML code on the local server, you can already see the dynamic content. Your new template has already been filled with all of the data. The visual aspect of the result could still use some improvements, but nonetheless the concept works.

Now we still have to pack the template into an installation package.

Creating a Template Package

To give your template to others, you have to compress it into a ZIP archive. Before you do that, create a current preview image of your template (template_thumbnail.png) with a size of 227 x 162 pixels. This thumbnail should now be displayed if you pass your mouse pointer across the name link in the template section.

Now pack all of the joomla150book files and all of its subdirectories into a ZIP archive. In addition, select of all of the files and folders in the [PathtoJoomla]/templates/joomla150book/ folder and pack them all into the joomla150book.zip file. Make a backup of this file and the ZIP file.

Uninstallation of the Template

You can now pass this package to others or you can install it yourself. If you want to try the installation, you have to remove the newly created template again from your Joomla! system.

To remove it, you first have to designate a different template as the default template. Click on the Extensions | Template Manager menu, select the desired template, and click on the Default icon.

Now you can uninstall your template. Go to the Extensions | Install/Uninstall menu and click on the Templates tab. Select the newly created joomla150book template and click on the Uninstall icon.

Installation with the Joomla! Template Installer

After you have eliminated all traces of your development and have backed up your work, go to the Extensions | Install/Uninstall menu.

You can install your ZIP package from here. Select the joomla150book.zip file and install it by clicking on the Upload File & Install button. The installer will report that the installation was successful and this success message will also display the description from the XML file.

What Source Code Comes from Joomla?

After we have jumped the most difficult hurdles by creating the template, let's take a look into the HTML code that Joomla! delivers to us.

Joomla!, naturally, creates code that is inserted into the container we have created. This code consists of HTML with sprinkled in CSS classes and CSS IDs. Among other things, Joomla! incorporates two CSS files that describe particular classes and IDs and that are inserted into each and every template.

These are the /templates/system/css/system.css and the /templates/system/css/general.css files.

In this case the CSS blocks take care of the rounded corners in the menu. There are additional items in the CSS file that format the third-order heading (<h3><h3>) and a non‑sorted list (the menu links) for this case.

So far, so good. This type of formatting is deliberate and the output of the necessary <div> tags can also be changed with the style attribute. We used the style xhtml parameter in our example template; in this template, the style rounded parameter is used. It delivers the respective four-part <div> tag.

This type of code creation is really suitable for CSS formatting. If you continue reading through the source code, you will also run across tables again. The Content Component still works with tables! This is where the problems start if you want to format the content (the part in the middle) separately without tables. However, Joomla! has a solution for this as well.

In order to get grip on the problem of table display, you would normally have to change the Joomla! core files. Your content would then be free of tables, but the file could possibly be overwritten with the next update.

From Joomla! 1.5.0 on there are now the so-called views that present a solution for this problem; you will find a number of different views for the display of logic components. With the com_content component, these are, for example, archive, article, category, frontpage, and section. These five folders contain files that make different content views available. I hope you remember the table and the blog view. Each of these five folders also contains a tmpl folder, which in turn contains various files that are responsible for the display.

In order to travel down that route you need an additional directory in your template directory. If we are staying with this example, this directory must be called com_content/article, since you want to change the layout of the content component in display type article.

In other words, you have to copy the files from:

[PathtoJoomla}/components/com_content/view/article/tmpl/*.*

into your new template directory and then you can do the customizations that you need.

[PathtoJoomla}/templates/[yourtemplate]/html/com_content/article

This can easily be duplicated in the Beez template. The aforementioned files are here in:

[PathtoJoomla}/templates/beez/html/com_content/article

and thus overwrite (override) the core files without changing them.

Joomla! looks for these files in the template directory. If they are there, they are used. If they are not there, the core files from the components are used.