Basic Browser History in Flex 3

A friend of mine asked me to explain how browser history (a.k.a deep linking) is done in Flex 3. There is a semi-automatic way to enable it by making sure that you use the Flex Builder 3 html templates and putting historyManagementEnabled=”true” in the Application tag of your MXML project. Like so (I think it’s even on by default):

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" historyManagementEnabled="true"/>

However I don’t personally think this is the best way to do it. It works OK when you are just using the standard Flex components that come with the SDK. Typically though the Internet applications that we build at StudioNorth are super customized and the built in history management just flat out doesn’t work.

I prefer to build it in manually instead. It’s actually pretty easy. You really only need one class and a few events. Using the example below adds a hash mark to the url and a string fragment. It’s that string fragment that we use to do our deep linking. So say http://www.studionorth.com/#home we know is the homepage, and http://www.studionorth.com/#brand_calculator is the Brand Calculator page. When a user changes to a new page, we change the string fragment programmatically so if the user want to bookmark it or copy it and send to a friend they can. One more note, we always try to make them as friendly as possible. A url should be nice and readable.

Here a little sample app stub to get you started. If you have any questions feel free to leave a comment.

<mx:Application
 backgroundColor="#212930"
 pageTitle="{siteTitle}"
 xmlns:mx="http://www.adobe.com/2006/mxml"
 initialize="init()"
 applicationComplete="onApplicationComplete()"
 historyManagementEnabled="false">

<mx:Script>
<![CDATA[

 // these are the imports we need to get a look into the current url
 // don't forget that these use the javascript routines included in the Flex Builder 3 html templates
 // they won't work if you don't include those javascripts stuffs
 import mx.managers.IBrowserManager;
 import mx.managers.BrowserManager;

 // a string to hold the current title of the page
 // especially useful for users when bookmarking.
 private var siteTitle:String = "";

 // the object we will use to get and set the "friendly" url
 private var browserManager:IBrowserManager;

 // first initialize the BrowserManager to tie Flex into the browser
 private function init():void {
  browserManager = BrowserManager.getInstance();
  browserManager.addEventListener(BrowserChangeEvent.BROWSER_URL_CHANGE, browserUrlChange);
  // set the site title to something initially here if you'd like
  browserManager.init("", siteTitle);
 }

 // here we are checking to see where folks are trying to go when they first hit the website / webapp.
 private function onApplicationComplete():void {
  if(browserManager.fragment.length>0) {
   // hey someone is trying to deep link right away!
   // this could be from a bookmark, a direct link, etc.
   // read the browserManager.fragment and send them where they want to go
   // say something like - setInitialPage(browserManager.fragment); maybe?
  } else {
   // nothing special, let's just show them the homepage and indicate that's what we are doing on the url
   browserManager.setFragment("home");
  }
 }

 // the is the guy that gets called when the url changes, tells us that someone is trying to get somewhere manually via the url
 private function browserUrlChange(event:BrowserChangeEvent):void {
  Alert.show(browserManager.fragment);
  if(browserManager.fragment.length == 0) {return;} // nothing really happened that we care about so leave
   // something on the url changed that we care about, let's
   // do something with browserManager.fragment here
   // maybe navigate to a new section or page or unload / load a different part of the application
   // once you do it, don't forget to do browserManager.setFragment("THE_NEW_SECTION");
   // you should also change the site title to match the section / page - browserManager.setTitle(siteTitle+" - "+section);
 }

]]>
</mx:Script>

</mx:Application>

One thing that I eluded to a few times was the site title. Don’t forget that you should update it when you update the url fragment. I’d doesn’t do anyone any good to look at their browser history on your site and just see the same page title over and over again.

Andy leads the interactive offerings and staff engineers at StudioNorth. He consults with clients on strategic technology direction and personally oversees the key phases of the iterative development cycle for many large technology projects. Whether for public web sites, private extranets, or custom applications, Andy uses his rich experience to provide results-driven solutions to our clients. He’s known for being a visionary and for coining the phrase, “conservative wow” in reference to StudioNorth’s ability to create high-impact projects for some of our more conventional audiences. If you want to bring your brand beyond “2.0″, Andy is your connection.

Want to track Andy a little closer? You can follow him on Twitter.