Understanding the View Stack and View Management
The View Stack is managed by PKUI.CORE in framework/ui-core.js. It consists of an array of views that are pushed and popped via PKUI.CORE.pushView and PKUI.CORE.popView along with several other methods.
The view on on the top of the stack is considered to be the currentView and is the view that will be popped should PKUI.CORE.popView be called. currentView is generally the only visible view on phone-sized devices, while there may be several visible views for tablet-sized devices.
The above image is an example of how the view stack would appear during different states of the application.
- Prior to the application showing its first view, the view stack is empty. No attempts to push or pop views should be made while the stack is empty. When the app begins, PKUI.CORE.showView is called with the first view, and this view is made visible and placed onto the view stack.
- At this point, there's one view on the stack. Since this app is a game, pressing a "start" button should begin the game by pushing the game view onto the stack. This is illustrated by the transition from #2 to #3. This is accomplished via PKUI.CORE.pushView.
- While the game is in progress, the view stack looks like #3. Once the game ends, an end-of-game view is displayed to show the score. This is illustrated in the transition from #3 to #4.
- As the player looks at their score, the view stack looks like #4. The transition from #4 to #5 is accomplished by tapping the "back" button (either physical or soft). This is done by calling PKUI.CORE.popView.
- In #5, the view stack indicates that the game is in progress once again. But if the user taps the "back" button again, we transition to #6 (again, via a popView).
- Should there be only one view on the stack, the physical back button should exit the app. For iOS, there is no physical back button, and so this does not apply. "Home" would be the best analogy, however the app is not exited.
Every view should follow this lifecycle:
- initializeView - Should be called immediately after the view is loaded into the DOM and its scripts are executed. Often executed after PKUTIL.loadHTML is completed.
- viewWillAppear - Called prior to the appearance of the view on the screen by most of the view management methods. If you're going to do any processing at this point, it is best to keep it light or schedule it to occur at a later date. Any processing might glitch the appearance animation.
- viewDidAppear - Called immediately after the appearance of the view on the screen.
- viewWillHide - Called just prior to the disappearance of the view from the screen. Be careful not to do a lot of processing at this point or you'll disturb the disappearance animation.
- ViewDidHide - Called just after the view is entirely off the screen.
- backButtonPressed - Called in response to the physical back button being pressed on Android or Windows Phone devices.
There are three methods of managing views: full-screen, column, and manual. The view management mode is controlled by the PKUI.CORE.viewHandlingMethod property.
- full-screen: All views fill the screen. When a view is pushed or popped a horizontal pan animation is performed from the view that is hiding to the view that is showing. The direction of the pan depends on if the view is being pushed or popped. (Note: some platforms do not perform any animation.) This method is the default.
- column: Each view takes up a portion of the screen horizontally, while filling the screen vertically. Each view can specify how wide it should be. If a view is pushed, the view is added to the right of all the visible views. If a view is popped, it is removed from the right. The rightmost view is generally assumed to the current view, but all views are interactive.
- manual: Not explicitly part of the framework, but it is possible to manage the views manually. This is often the case with tablet-sized apps where more than one view may be on the screen at once or where a view may act as a subview of another view. This gets significantly more difficult to handle automatically, which is why the framework doesn't currently have this built in.
Note: it isn't possible to change the management method once a view is displayed on the screen. (Well, it is -- but the results are undefined.)
All views are attached to a specific DOM element. In full-screen apps, this is often a root element. The framework treats all DIVs classed with container as elements that views can be attached to and then be contained within, so it is typical to see an index.html that looks like this:
<body>
<div id="rootContainer" class="container">
</div>
</body>
As views are loaded into the DOM via PKUTIL.loadHTML, the attachTo property of the options object is set to rootContainer -- this forces the view to be attached to the container with the ID of rootContainer.
For the manual management method, there are often several containers defined, including modal view containers, popovers, and more. While views can certainly be moved around in the DOM from one parent to another, it is easiest to specify where they should live when they are loaded (assuming they don't change their ownership).