Packagecom.soma.view
Classpublic class Page
InheritancePage Inheritance flash.display.MovieClip
ImplementsIPage
SubclassesPageExternal

Author: Romuald Quantin - www.soundstep.com

Information:
Blog page - SomaUI
How does it work - Soma Protest
Project Host - Google Code
Documentation - Soma ASDOC
Class version: 2.0
Actionscript version: 3.0

Copyright:

The contents of this file are subject to the Mozilla Public License
Version 1.1 (the "License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at

http://www.mozilla.org/MPL/

Software distributed under the License is distributed on an "AS IS" basis,
WITHOUT WARRANTY OF ANY KIND, either express or implied.
See the License for the specific language governing rights and
limitations under the License.

The Original Code is Soma.
The Initial Developer of the Original Code is Romuald Quantin.
Initial Developer are Copyright (C) 2008-2009 Soundstep. All Rights Reserved.

Usage:
The Page view class must be extended to create your own page.

Create a new page

1. Create a page node in the XML Site Definition.

<page id="mypage_id" type="MyPage" urlfriendly="my-page">
    <title><![CDATA[My Page]]></title>
</page>
     
2. Create a class that is extending com.soma.view.Page and implementing com.soma.interfaces.IPage.
package com.project.pages {
    
    import com.soma.interfaces.IPage;
    import com.soma.view.Page;
    import com.soma.events.PageEvent;
    
    public class MyPage extends Page implements IPage {
    
        public function MyPage() {
            addEventListener(PageEvent.INITIALIZED, initialized, false, 0, true);
        }
    
        private function initialized(e:PageEvent = null):void {
            removeEventListener(PageEvent.INITIALIZED, initialized, false);
            // initialization complete, build page elements.
        }
    
        override public function transitionIn():void {
            // show my page and call: super.transitionIn
            Tweener.addTween(this, {time:1, _autoAlpha:1, onComplete:super.transitionIn});
        }
    
        override public function transitionInComplete():void {
            // end of the transition to show the page
            super.transitionInComplete();
        }
    
        override public function transitionOut():void {
            // hide my page and call: super.transitionOut
            Tweener.addTween(this, {time:1, _autoAlpha:0, onComplete:super.transitionOut});
        }
    
        override public function transitionOutComplete():void {
            // end of the transition to hide the page, the page is about to be removed
            // use a dispose function to destroy elements and listeners, then call super.transitionOutComplete
            dispose();
            super.transitionOutComplete();
        }
    }
}
     
3. Register the page class (in the config file seems to be the best place, or anywhere before Soma starts).
Soma.getInstance().registerClass(MyPage);
     
Variables

The page super class will initialize some variables before dispatching a PageEvent.INITIALIZED event, you can access them straight from your own page as you're going to extend this Page. Assets

A NodeParser instance is created by the page and it will look for a content node in your page node. The parser will try to instantiate and/or load any children of this content node (unless you add an attribute "parse" set to false).

If asset nodes have been found, the NodeParser will parse and instantiates them. The page will then dispatch a PageEvent.CONTENT_PARSED event. If you don't have any "external assets" (such as a picture or anything that requires loading), the assets are ready to use.

If the node parser has found external assets, it will load them. Your assets won't be ready when you will receive the PageEvent.CONTENT_PARSED event. When the parser will be completely finished (instantiating and loading), the page event will dispatched a PageEvent.CONTENT_COMPLETE.

To receive the information, add the following listeners:
addEventListener(addEventListener(PageEvent.CONTENT_PARSED, contentParsedHandler);
addEventListener(addEventListener(PageEvent.CONTENT_COMPLETE, contentCompleteHandler);
     
Show and Hide a page

As the PageManager can't know how you are going to show and hide your pages (and how long time it will take), it will give you the time to do that in 4 methods that must be overridden. You can show your page and/or your page elements in the overridden transitionIn method and call super.transitionIn when you are done.
override public function transitionIn():void {
    // show my page and call: super.transitionIn
    Tweener.addTween(this, {time:1, _autoAlpha:1, onComplete:super.transitionIn});
}

override public function transitionInComplete():void {
    // end of the transition to show the page
    super.transitionInComplete();
}
     
You can hide your page and/or your page elements in the overridden transitionOut method and call super.transitionOut when you are done. Call the super methods are important as it will make the PageManager continue its process.
override public function transitionOut():void {
    // hide my page and call: super.transitionOut
    Tweener.addTween(this, {time:1, _autoAlpha:0, onComplete:super.transitionOut});
}

override public function transitionOutComplete():void {
    // end of the transition to hide the page, the page is about to be removed
    // use a dispose function to destroy elements and listeners, then call super.transitionOutComplete
    dispose();
    super.transitionOutComplete();
}
     
Control

You can very easily control or alter a page flow with Soma, you can listen to the PageEvent.STARTED (in the Main class for example) that is dispatched by the PageManager before doing anything.
Soma.getInstance().addEventListener(PageEvent.STARTED, pageHandler);

private function pageHandler(event:PageEvent):void {
    // every time the PageManager is about to show (and remove) a page this handler will be called.
    var currentPage:Page = Soma.getInstance().page.currentPage;
    var nextPageID:String = event.id;
    // here I stop the PageManager to change the page:
    if (nextPageID == "PageIDIdontWantToSee") event.preventDefault();
}
     

See also

Soma
PageEvent
PageManager
ClassImport


Public Properties
 PropertyDefined by
  assets : Array
[read-only] Get an array containing the assets created by the NodeParser instance (all assets that are DisplayObject subclasses, you wont find XML in this array)
Page
  baseUI : BaseUI
BaseUI instance for layout purpose.
Page
  content : XML
content node (XML) of the page, it is use by the NodeParser instance.
Page
  depth : int
depth of the page (depth attribute in the page node).
Page
  hasExternalContent : Boolean
[read-only] Whether or external assets have been found (pictures for example, assets that have to be loaded).
Page
  id : String
id of page (attribute id of the page node).
Page
  loader : SomaLoader
SomaLoader instance used by the NodeParser instance to load external assets.
Page
  loaderContext : LoaderContext
LoaderContext instance of the SomaLoader instance of the page (null by default).
Page
  pageXML : XML
page node (XML) of this page.
Page
  parser : NodeParser
NodeParser instance that will be used to create and load the assets found in the content node.
Page
  parserTarget : DisplayObjectContainer
the target where the assets will be added to the display list (the page itself is the default but you can specify another container).
Page
  type : String
type of the page (type attribute in the page node).
Page
  willBeRemoved : Boolean
Whether or not the page is about to be removed by the PageManager.
Page
Public Methods
 MethodDefined by
  
Page()
Creates a Page instance (this class should always be extended).
Page
  
getAssetByID(id:String):DisplayObject
Get an asset created and/or loaded by the NodeParser instance using the id attribute of its XML node.
Page
  
info():String
Get a String describing the page.
Page
  
transitionIn():void
Method that should be overridden, beginning of the showing process.
Page
  
Method that should be overridden, end of the showing process.
Page
  
Method that should be overridden, beginning of the hiding process.
Page
  
Method that should be overridden, end of the hiding process.
Page
Property detail
assetsproperty
assets:Array  [read-only]

Get an array containing the assets created by the NodeParser instance (all assets that are DisplayObject subclasses, you wont find XML in this array)

Implementation
    public function get assets():Array
baseUIproperty 
baseUI:BaseUI  [read-write]

BaseUI instance for layout purpose.

Implementation
    public function get baseUI():BaseUI
    public function set baseUI(value:BaseUI):void
contentproperty 
content:XML  [read-write]

content node (XML) of the page, it is use by the NodeParser instance.

Implementation
    public function get content():XML
    public function set content(value:XML):void
depthproperty 
depth:int  [read-write]

depth of the page (depth attribute in the page node).

Implementation
    public function get depth():int
    public function set depth(value:int):void
hasExternalContentproperty 
hasExternalContent:Boolean  [read-only]

Whether or external assets have been found (pictures for example, assets that have to be loaded).

Implementation
    public function get hasExternalContent():Boolean
idproperty 
id:String  [read-write]

id of page (attribute id of the page node).

Implementation
    public function get id():String
    public function set id(value:String):void
loaderproperty 
loader:SomaLoader  [read-write]

SomaLoader instance used by the NodeParser instance to load external assets. Set by default to the global loader (Soma.getInstance().loader).

Implementation
    public function get loader():SomaLoader
    public function set loader(value:SomaLoader):void
loaderContextproperty 
loaderContext:LoaderContext  [read-write]

LoaderContext instance of the SomaLoader instance of the page (null by default).

Implementation
    public function get loaderContext():LoaderContext
    public function set loaderContext(value:LoaderContext):void
pageXMLproperty 
pageXML:XML  [read-write]

page node (XML) of this page.

Implementation
    public function get pageXML():XML
    public function set pageXML(value:XML):void
parserproperty 
parser:NodeParser  [read-write]

NodeParser instance that will be used to create and load the assets found in the content node.

Implementation
    public function get parser():NodeParser
    public function set parser(value:NodeParser):void
parserTargetproperty 
parserTarget:DisplayObjectContainer  [read-write]

the target where the assets will be added to the display list (the page itself is the default but you can specify another container).

Implementation
    public function get parserTarget():DisplayObjectContainer
    public function set parserTarget(value:DisplayObjectContainer):void
typeproperty 
type:String  [read-write]

type of the page (type attribute in the page node).

Implementation
    public function get type():String
    public function set type(value:String):void
willBeRemovedproperty 
willBeRemoved:Boolean  [read-write]

Whether or not the page is about to be removed by the PageManager.

Implementation
    public function get willBeRemoved():Boolean
    public function set willBeRemoved(value:Boolean):void
Constructor detail
Page()constructor
public function Page()

Creates a Page instance (this class should always be extended).

Method detail
getAssetByID()method
public function getAssetByID(id:String):DisplayObject

Get an asset created and/or loaded by the NodeParser instance using the id attribute of its XML node.

Parameters
id:String — Attribute id of the XML asset node.

Returns
DisplayObject — A DisplayObject.
info()method 
public function info():String

Get a String describing the page.

Returns
String — A String.
transitionIn()method 
public function transitionIn():void

Method that should be overridden, beginning of the showing process. Show your page elements here and call super.transitionIn when the page is displayed.

override public function transitionIn():void {
    // show my page and/or my page elements, and call: super.transitionIn
    Tweener.addTween(this, {time:1, _autoAlpha:1, onComplete:super.transitionIn});
}
      

transitionInComplete()method 
public function transitionInComplete():void

Method that should be overridden, end of the showing process. You must call super.transitionInComplete.

override public function transitionInComplete():void {
    // end of the transition to show the page, at this moment the page is fully displayed
    myMethodAferShowingThePage();
    super.transitionInComplete();
}
       

transitionOut()method 
public function transitionOut():void

Method that should be overridden, beginning of the hiding process. Hide your page elements here and call super.transitionOut when the page is hidden.

override public function transitionOut():void {
    // hide my page and/or my page elements, and call: super.transitionOut
    Tweener.addTween(this, {time:1, _autoAlpha:0, onComplete:super.transitionOut});
}
      

transitionOutComplete()method 
public function transitionOutComplete():void

Method that should be overridden, end of the hiding process. You must call super.transitionInComplete (to allow the PageManager to remove the page and continue its process if you are using pages with depths).

override public function transitionOutComplete():void {
    // end of the transition to hide the page, the page is about to be removed
    // use a dispose function to destroy elements and listeners, then call super.transitionOutComplete
    dispose();
    super.transitionOutComplete();
}