ATK Sessions

From ATK Wiki

SessionVariables

Contents
1 atklevel
2 SESSION_*
3 atkstackid
4 atkprevlevel

atklevel
atklevel determines how 'deep' you are in an application's stack. If you go from the menu to the admin screen of node A, then you start at
level 0. When you go to edit a record from there, you are at level 1. All 'back' methods (cancel buttons, saving the record etc.) take you
back to what was at level 0.

Take a look at the 'stack trace' below each screen (the one that tells the user in what screen he is). Each is at a different level, starting from
0, ending with the level you are currently at.

SESSION_*
Remember those SESSION_* constants that you can pass to href/session_url etc? These control the level.

If you have a link with SESSION_NESTED, the level is increased by 1, meaning that the screen you go to is one level deeper than the
current. This means that the user can return to the previous screen using back-methods.

The concept is best explained with a drawing that indicates the actions and the session levels involved:
IF you have a link with SESSION_BACK, the link acts as a back-link and will return to the screen that was one level lower, regardless of
what else you pass in the url. You use this when manually constructing back buttons.

SESSION_DEFAULT retains the current stack level. This means that the current atklevel remains the same, and the user just refreshes the
current screen. This is what happens when you search or sort in a recordlist for example. Because the level is retained, even if you sorted
or searched a thousans times, going 'back' will lead you to the screen that was directly before the screen you are currently in.

SESSION_REPLACE is almost the same as SESSION_DEFAULT in terms of session stack, but with the difference that the current screen
is replaced by another screen completely. This is what happens with NF_EDITAFTERADD for example; the current add screen is
replaced with an edit screen. If we wouldn't use SESSION_REPLACE here, then the cancel button of the edit screen would go back to the
add screen, where as now it goes back to where you came from when you started the 'add' action.

SESSION_NEW resets the current session stack. Any screen that is loaded when SESSION_NEW is used in the link, starts at level 0.
(back links in such a screen do not go back to anywhere as level 0 is the bottom level). This is what the menu's use to start fresh screens
when you open an item from a menu.

atkstackid
In PHP, you only have a single session per user. However, if that user has opened 2 windows with the same application, we want each
window to have its own session. Many frameworks are not compatible with multiple windows and the app will start behaving erratically
when you open links in different windows. ATK however uses 'stacks' to keep track of each window. Each window running a screen from
the application is using its own stack, and is identified by a stackid. The stackid is passed around in the url.

atkprevlevel
The atkprevlevel is short for the 'previous level'. This is used internally by the session manager to keep track of urls opened in a new
window. PHP cannot determine whether a page request is from the same window or from a new window. ATK can however, by analysing
the stack level and the previous stack level.
Consider this Example: You are in the admin screen (level 0) and open an edit link in a new window. The edit screen will get level 1 as
new level, and 'level 0' is passed as the 'prevlevel'.

Now go to the admin window, and open another edit link in a new window. This edit screen will get level 1 as well. The 'previous level'
however is already 1 (the other window moved it to 1). ATK decides that this can only be the case if there are multiple windows involved,
and at that point, forks the stack (you can see this happening in the debugoutput). From that moment on, we have 2 stacks, each with their
own stackid and their own levels.

The fun thing is that the entire application session stack is forked. In each of the 2 edit windows that you have opened, you can click
'cancel', and both windows will take you to the admin page, and they will now work independently and they don't mess up eachothers
stack data (both remember the page they were on, the last known search criteria etc.)

Retrieved from "http://atk-framework.com/wiki/ATK_Sessions"

This page was last modified on 14 July 2010, at 17:21.