Leveraging Deeplinks and SWFAddress
From Gaia Framework Wiki
Contents |
Overview
Gaia comes with Rostislav Hristov's SWFAddress. Every page in the currently active branch is automatically set up to listen to GaiaSWFAddress for the onDeeplink event that occurs when a goto is called with a branch that goes beyond the scope of the site.xml.
The scope of the site.xml
In this sample site.xml, there is a single branch, "index/nav/home".
<site>
<page id="index" src="index.swf">
<page id="nav" src="nav.swf">
<page id="home" src="home.swf"/>
</page>
</page>
</site>
When you pass the following branch to goto()
Gaia.api.goto("index/nav/home/services");
all three pages would receive the onDeeplink event and the value of the deeplink would be "/services".
The scope of the site.xml ends at index/nav/home. That is the final valid branch. So, anything beyond that valid branch is outside the scope of the site.xml branch, and would be passed as the value of the deeplink.
Gaia.api.goto("index/nav/home/services/design");
Here, the value passed on the onDeeplink event would be "/services/design".
Calling goto() internally is not the only way to receive onDeeplink events. If the user types something manually into the address bar of the browser or has a branch bookmarked, that will trigger the onDeeplink event, as well.
You can use Gaia.api.goto() to navigate through your site using deeplinks because Gaia will not transition out any pages if they are part of the valid branch passed in the goto event. This allows you to have as many subsections as you want and all you have to do is use one method, Gaia.api.goto() to control showing them. It really makes development and debugging much easier.
How goto() works with SWFAddress
When you call goto(), Gaia internally calls SWFAddress.setValue, which updates the browser address bar, which then fires an event back to the SWFAddress class, which Gaia is listening to and then propagates to all active pages. What this means is, whether the goto came from inside Gaia or outside Gaia, it's actually handled identically. The event always comes from SWFAddress. Even if you're not running in a browser, SWFAddress still stores the value and fires off events accordingly.
How To Handle Deeplink Events
So now that you know how SWFAddress works with Gaia, and what is passed, how do you handle the onDeeplink event?
In the class com.gaiaframework.templates.AbstractPage, there is a method at the bottom of the class:
public function onDeeplink(event:GaiaSWFAddressEvent):void
{
dispatchEvent(event);
}
This method can be overriden in your page class, or you can have a nested MovieClip listen to the page for the event. Here is an example of overriding the event in AS3 (in AS2, you just leave off override and return :Void instead of :void).
override public function onDeeplink(event:GaiaSWFAddressEvent):void
{
trace(event.deeplink);
}
This will trace the value of the deeplink. Keep in mind that if only a valid branch is passed to goto(), such as "index/nav/home", this event still fires, but the value of deeplink will be an empty string "". This is very useful if your page has a default section, and then has subsections, and you can use the branch property to ensure the deeplink was meant for this page's branch. The event.branch property is the valid branch associated with the deeplink.
Example
How you handle the event will be specific to your particular setup. Here is an example.
In the HomePage, there are 3 different MovieClips for the subsections services, clients and contact. This is a simplified way to handle the onDeeplink event, displaying the subsection passed in the onDeeplink event.
public var MC_services:MovieClip;
public var MC_clients:MovieClip;
public var MC_contact:MovieClip;
override public function onDeeplink(event:GaiaSWFAddressEvent):void
{
MC_services.visible = MC_clients.visible = MC_contact.visible = false;
if (event.deeplink == "/services" || event.deeplink == "/clients" || event.deeplink == "/contact")
{
this["MC_" + event.deeplink.substr(1)].visible = true ;
}
}
This code simply toggles the visibility of the different clips, based on what the value of the deeplink is. It filters out any invalid values (the user could type something invalid into the address bar, for instance), and then uses the actual string that is passed, minus the leading slash, to set the proper section to be visible.
Handling Deeplinks Without Events
Sometimes, there will be a deeplink but your page won't be loaded and ready to receive it before the event fires. A great example of this is deeplinking directly into your site, or the first time a new branch transitions in. The best way to handle this is to call the onDeeplink method yourself, passing the current deeplink value, which you can get through Gaia's API.
var currentDeeplink:String = Gaia.api.getDeeplink(); onDeeplink(new GaiaSWFAddressEvent(GaiaSWFAddressEvent.DEEPLINK, false, false, currentDeeplink));
An easier way to accomplish this without having to create a new event is to have your onDeeplink event call another method that actually handles it.
override public function onDeeplink(event:GaiaSWFAddressEvent):void
{
myDeeplinkHandler(event.deeplink);
}
private function myDeeplinkHandler(deeplink:String):void
{
// do something with the deeplink
}
Then, you only have to call:
myDeeplinkHandler(Gaia.api.getDeeplink());
Leveraging Deeplink Events To Make Complex Behavior Easy
You can have multiple pages listening for the deeplink event, as well. For example, you could have the NavPage show a particular submenu when a certain deeplink occurs, as well as the HomePage. You could even have the IndexPage change the background in relation to specific deeplink events.
This means you don't need to worry about writing code to synchronize entirely different parts of your site when specific goto() calls are made with deeplinks. All you have to do is handle the onDeeplink event in all of your pages, and whenever they occur, no matter where they occur from, your site is guaranteed to handle them.
