biggerboat/navigator-as3

A tiny yet powerful library to deal with navigation and flow in your ActionScript projects

Navigator for ActionScript 3.0

This library was created to take away your pains when it comes to navigating your application between different views or application states. It provides ways to deal with (asynchronous) transitions between states without bugging you with the tedious parts. To sum up of the library's features:

• Total control over synchronous and asynchronous visual transitions
• Just-in-Time initalization of view components
• Instant deeplinking with SWFAddress
• Support for dynamic range elements and lists, like gallery items
• Nested states, move complete parts of you application and they still work
• Flow control through state validation, both synchronous and asynchronous
• Integration of popular frameworks (PureMVC, RobotLegs), but it's optional
• History management (courtesy of Laurent)
• And many more...

Check out the Wiki pages if you want to read some more or if you want to see some examples.

Forks & Ports

• The ever awesome Bigger Boat group ported the library to Javascript: https://github.com/biggerboat/navigator.js
• @lbineau has ported the library to Haxe: https://github.com/lbineau/HaxeNavigator

navigator-as3's Issues

Inconsistent outcome mapping singletons.

Hi,

I've hit a strange bug/inconsistency with calls to prepareValidation() with async validation and wanted to check what the proper functionality should be.

// Lets say i have 3 Singleton classes ( using Robotlegs ):

// ONE

public class SingletonOne extends Actor implements IHasStateValidationAsync,  IHasStateRedirection
{
    public function SingletonOne(){
        super();
    }

    public function prepareValidation(truncated:NavigationState, full:NavigationState, callOnPrepared:Function):void{
                // occasionally this is not called.. see below.
        trace( this + " prepare" );
        callOnPrepared();
    }

    public function validate(truncated:NavigationState, full:NavigationState):Boolean{
        return true;
    }

    public function redirect(truncated:NavigationState, full:NavigationState):NavigationState
    {
        return null;
    }
}

// And the other two extend the first for the sake of simplicity.
// TWO 
public class SingletonTwo extends SingletonOne
{

}

// THREE
public class SingletonThree extends SingletonOne
{

}

// Now map them like :

stateActorMap.mapSingleton( [ "/","/state1/","/state2/" ], SingletonThree );
stateActorMap.mapSingleton( ["/state1/"], SingletonOne );
stateActorMap.mapSingleton( ["/state2/"], SingletonTwo );

// And startup 
this.navigator.start( "/", "/state1/" );

What prepareValidation() methods should i expect to be called here? I'd have thought that both the prepareValidation() function of
SingletonOne and SingletonThree should be called, except what is strange is that SingletonThree is called only, BUT occasionally SingletonOne is called as well.

This is causing me a slight headache - i'm not sure if its something strange happening with my machine. I have tested in FP 10.3 and was also testing in FP11 as well and got the same result.

I would assume that if you map two Singletons to validate on the same state then both would have to prepare and return true to validate the state?

Cheers,

Jamie

ContextMenu and AS3 Mobile / AIR

If you have an actionscript mobile project, and would like to use the DebugConsole, you need to comment out
line 130 in DebugConsole.as (AS3 mobile / AIR has no support for the ContextMenu class, which is only logical if you think about it :> )

StateController map traces injector warning

When using a stateController, an error will show up in your trace output:

Warning: Injector already has a rule for type "com.epologee.navigator::NavigationState", named "".
If you have overwritten this mapping intentionally you can use "injector.unmap()" prior to your replacement mapping in order to avoid seeing this message.
Warning: Injector already has a rule for type "com.epologee.navigator::NavigationState", named "truncated".
If you have overwritten this mapping intentionally you can use "injector.unmap()" prior to your replacement mapping in order to avoid seeing this message.

The code runs as expected, but something is obviously incorrect. As the error indicates, it seems like NavigationState hasn't been unmapped.

Opening site with IHasStateSwap instance

I have an issue with the IHasStateSwap, when I navigate to a page using the IHasStateSwap interface everything works great, but when i open the site on a IHasStateSwap the page doesn't get an swapIn. I use the robotlegs branch. I haven't noticed this in the master branch. So maybe this is introduced in the new commits?

Flex 4 Context problem

Hello,

When I enter the context as mxml
<local:FlexNavigatorTestContext contextView="{this}" />
in the Declarations tag I get
1136: Incorrect number of arguments. Expected 1.

What am I doing wrong?

navigator does not respond to browser address bar change

I have tested on both firefox4 and ie9, and both have the same issue

• change states in swf -> address changes too (ok)
• change address in browser and press enter (swf no response)
• press back or forward button of the browser (browser address changes but the swf does not respond)
• swf does respond to address change by hitting browser's reload button though

i have modied the simple example accompanied in the downloaded source by simply changing Navigator to SWFAddressNavigator class in which case, the problem exists too (in my projects as well)

the following is my modified simple example, I am using swfobject 2.2 and swfaddress 2.4, please let me know there are something that I am missing to make it work both ways, thank you!

http://220.135.6.82/simple

zipped modified simple example

http://220.135.6.82/simple.zip

Ordering of views in RobotLegs integration is inreliable

I know, this must be a hard one, but the depth order of elements a navigator-RobotLegs project is definitely still buggy. Is this a known issue?

segment planning for set-top device controlled with remote

We're looking for any input/ideas on a way to map out the segments within a set-top hardware device we're developing.

The unique aspect of this set up is that the only user input is via a remote control: up, down, left, right, enter. If you're on the main menu screen, up and down will cycle through different menu items. Once one item is 'highlighted', a corresponding right/left menu appears. 'Highlighted' meaning, the up/down arrows 'select' the menu item, the user does not have to hit the enter key on this menu. Some items within other menus across the UI may display corresponding menus when they're highlighted as described above, or may only display corresponding menus when the user has highlighted an item and then presses enter on the remote.

Also, all menus throughout the application are either left/right controlled, up/down controlled, or a grid type menu where up/down/left/right/enter are used to cycle through the items.

The best metaphor I can think of to explain how our segment urls will need to work is; imagine if this was a mouse-driven application. If you moused over a menu, and a submenu were to appear (with it's first item highlighted, ) the url would need to change per that mouse over gesture. If you were then to mouse over the other items within the sub menu, the url would also change for those actions. It's not as linear as click-here to go to sub level page, click on this next button to go to tertiary level page.

The entire idea being, of course, that we can start the application within any url that we'd like.

Any input would be greatly appreciated.

Bug when listening to NavigatorEvent.STATE_CHANGED

I have an Robotlegs application with menu items, these menuitems have a mediator (with the regular mediatorMap.mapView().

This mediator listens to the event NavigatorEvent.STATE_CHANGED this all works good. There is however a problem, when the menu gets added in the root, NavigationState("/") the getCurrentState() = null (in the onRegister of the mediator...)

Remove redirect

Hi,
How can I remove a redirect previously registered ?
It seems that it is not possible

Thanks

Event not fired

The NavigatorEvent.STATE_CHANGED event is never dispatched. This is caused by the check in the notifyStateChange method. See http://grabs.studiosugarfree.com/NcDy.png

IHasToBeRemovedWhenTransisionedOut

Hi Eric-Paul,

First I want to tell you that the Navigator-as3 is something I am using for every project I have done for about a year. It really takes the pain out of navigation in every AS3 projects.

But something is bothering me. The issue I want to report has to do with the integration with Robotlegs and PureMVC. Although I never thought about it when I used PureMVC. But that's more because I had a different approach back then.

One of the coolest things in Robotlegs is, when you add something on the stage the needed mediator gets created just in time so you can manipulate the view before the user sees it. So when the user gets redirected to a NavigationState which needs a certain view you add it and the mediator gets created... Right?

Right now I am creating views which are doing pretty heavy stuff (they are displaying big sets of CPU intensive graphics). I want to show these data in different views/States i.e.:

• /lists/flower-view
• /lists/row-view
• /lists/thumb-view
• /lists/another-awesome-view

All these view mediators respond to contextEvents (that's where my DataUpdate Event comes from). And because the view and mediator never get removed they keep on responding to Events sent to them.

And that's my problem. My opinion is if you addChild the clip in the dungons of the Navigator we should be able to undo this. I tried to remove the view from the mediator but that resulted in lots of Errors!

My suggestion is the following; why not add another interface to say you want the view to be removed when possible..

So here I introduce my new friend:

IHasToBeRemovedWhenTransisionedOut

I hope you can fullfill my request.

Thanks,
Jankees

DISCONTINUING DEVELOPMENT

Dear Navigator-enthusiast,

I had a great time working on this library, getting feedback from all around the world about its many use cases. Being featured in the RobotLegs book by Joel Hooks and Stray (Lindsey Fallow) sure was a great honor, and it lead to a big spike in activity.

Unfortunately for some time already I have started doing projects for other technologies, mostly iOS, and I have gotten distanced from the Flash platform. As a consequence, continued development on this library has stalled and I'm not planning on putting any time in it anymore, not even if RobotLegs 2 ships in the near future.

If there's anyone who wants to continue development on this library, feel free to fork (there are quite a few already), I'll be happy to reference a link to your repository here.

Regards,
Eric-Paul Lecluse
Author of Navigator AS3

Have choice of container

Hi,

When using robotlegs with navigator, we don't have choice of the container where the views are added.
It could be a limitation, cause in many case we have some views that are not in states of the app, like a footer, a header, a background or a loader view.
These views are always visible and don't need to be dependant of the navigator for being displayed.
So for the correct orderingof the layer depth it could be nice to be able to tell to navigator : "put the views in this container" (a middle container for example).
So i've forked my repo on my computer and add this functionnality, very simple but usefull. (just add a getter setter in IViewStateMap and add a new elseif statement in addToContainer method).
What do you think about ?

tks.

Path not showing correctly in DebugStatusDisplay

Paths registered with wildcards are not correctly displayed in the DebugStatusDisplay. They are logged correctly though. For example, I have the path /room/0/1/0/0/ and the Display just shows /room/.
See http://grab.by/7rIX

TrazzleConnector cause an security sandbox violation error

Hi,

I'm testing the simple navigator example and i've found a security sandbox violation error.

After some tests, it's due to the use of the TrazzleConnector.

If i comment out the line 34 in BaseExample.as, the error is no more displayed.

I'm on Windows Vista, so i can't have the trazzle debugger.

thanks for sharing this good work man !

some urls are casesensitive

Hi Epologee,

I have a question, i am building a player for youtube video's. I wanted the youtube ID's to be in the url:

i.e. #/player/1H4qpvYovDk

But navigator lowercases everyting so you can't do this... Is there a workaround for this problem?

Thanks
Jankees

IHasStateValidation multiple validate calls

I was wondering why the Navigator calls the validate function multiple times.
For example when I open a page on: "/video/a/b/c/d/e/d/f/",
it calls the validate method multiple times in the following order:

[trace] validate
[trace] truncated: /b/c/d/e/d/f/
[trace] full: /video/a/b/c/d/e/d/f/
[trace] validate
[trace] truncated: /d/f/
[trace] full: /video/a/b/c/d/e/d/f/
[trace] validate
[trace] truncated: /a/b/c/d/e/d/f/
[trace] full: /video/a/b/c/d/e/d/f/
[trace] validate
[trace] truncated: /c/d/e/d/f/
[trace] full: /video/a/b/c/d/e/d/f/
[trace] validate
[trace] truncated: /d/e/d/f/
[trace] full: /video/a/b/c/d/e/d/f/
[trace] validate
[trace] truncated: /f/
[trace] full: /video/a/b/c/d/e/d/f/
[trace] validate
[trace] truncated: /e/d/f/
[trace] full: /video/a/b/c/d/e/d/f/

I would like to reduce the StateValidation to a single function call to save resources.

I might also want to say that /video/a/b/ is valid while /video/a/ is invalid.

Remove the Trazzles, logmeisters and what not.

Clean up the source, all this stuff renders it unusable

when requesting ("a/b") transition a then b in sequence

hi, i was wondering what is the best way to implement this
when path "a/b" is requested, wait till "a" completed transition in then start "b"transition in"
at the moment i am using a timer in "b" which loops until it finds "a" has completed loading and signals a variable called "isready"
but the timer stuff kinda messed up navigation when requesting paths quickly between one and others
i believe there there some better practices utilizing this framework, I have tried async validation, but still can't manage to do the above.. any tips would be really thankful :)

Provide state with transitionIn?

Wouldn't it be useful to get the inFull state provided in the TransitionIn function? Especially in the RobotLegs variation I often need to check navigator.getCurrentState for elements that exist in multiple states. Adding IHasStateValidation and IHasStateUpdate seems such a big workaround.

Integration libraries should not be part of the main library

It prevents us from importing the full source-code as a submodule; we'd need to link every library navigator integrates to in order to build a swc of the full source. Isn't it better to create individual integration libraries for each integration point?

Navigator needs a logo!

I took the liberty to set a style: http://grab.by/7zVq

Keeping a view persistent through all but a couple states?

First time working with Navigator and I love it!

We're trying to figure out if there is a solution to the following scenario without building something on our own. We have a view (a main menu for lack of a better description) that is visible on most all states. There are a couple states where this view needs to disappear though. Is there a way to 'reverse map' a view to a state? For example, if the state changes to "/whatever/" that view will transition out, but for any other states, the view will remain visible?

We're trying to avoid placing a conditional within this view/mediator that checks the state every time it changes, then if full == "/whatever/" transition out. Thanks for any tips!

navigator initialization improvement in RobotLegs

Hi Eric-Paul,

First of all, I love the Navigator AS3!

Right now you'll still need to do write this line of code in the constructor of your Context to use SWFAddress:
injector.mapSingletonOf(Navigator, SWFAddressNavigator);

I understand the need of it, but I'm wondering if there is space for some improvement. Are there more types of navigator besides SWFAdressNavigator? If not maybe just provide a boolean value in the constructor for using SWFAdress instead.

A side problem with the current approach is that when the navigator (@see get function in for example NavigatorSignalContext) isn't requested yet and you're using an injection somewhere in RL, this throws directly an error because the Navigator isn't mapped yet.

I think it would be a good solution that you can start off your project without (having to) define a subset of Navigator (like SWFAddressNavigor)..

Cheers,
Patrick

Backwards navigation breaks by invalid state/path

When I type in a - not registered - state into the address-bar, the navigator resets it to the last valid state.
If I now want to navigate to a previous page, it will jump to the invalid state and redirect me again so that I get stuck in a loop.

I am not sure if you can do something about this regarding SWFAddress, browser-behaviour and might not even be a bug.

Why is issue #3 closed? :-)

It was still marinating...

How to change the transition flow

Hi,

Just a question, is there a feature in navigator that allows to change the classical transition flow : transitionOut then transitionIn ?
I mean, if i want to perform a transitionIn before a transitionOut or if i want to have both transition in the same time.

thks.

Stop using the in-prefix for function arguments

Can I get any support on this? :-) I think the in-prefix for function arguments is not only very uncommon, it also is a very easy source of confusion when passing parameters like inVisible, inValid and inCorrect.
So if prefixes are needed, can we use a standardized notation? Like aVisible (where a stands for argument or if you really prefer it, pVisible where p stands for parameter).
It's time to leave the habits of master stephan behind :-)

Mapping a state to a command will automatically validate all substates as valid

When I map the root state, it will automatically validate all substates, while the expected behavior would be that it only validates states that have been mapped (to either views or commands).

Add the following line to your context:
stateControllerMap.mapCommand("/", SomeCommand);

then navigate to /test/ or /this/is/a/test/state/that/has/never/been/mapped/ both will be valid states.