Pages

From Gaia Framework Wiki

Jump to: navigation, search

Contents

Introduction

Pages in Gaia are represented "physically" by templated Flash files which are created during the scaffolding process and/or Flash files you create yourself. Pages can contain Assets, as well as other pages. They are represented in the site.xml in page nodes.

At their core, Pages are simply MovieClipAssets (see Assets) that have managed transition functionality and built-in relationships with their assets, parents, and children.


Page Transitions

Pages in Gaia are set up to transition in and out. The transitions can be timeline based, code based or any combination thereof. It's entirely up to you.

There are four required methods for Pages in Gaia, and they follow standard timeline-based environment naming conventions.

  • transitionIn();
  • transitionOut();
  • transitionInComplete();
  • transitionOutComplete();

Pages receive these events from Gaia and Page files must have all of these methods defined. You must call the "complete" methods at the end of your transitions so Gaia knows that the page is finished transitioning in or out. Gaia automatically has these methods defined for you.

If your transition is timeline based, you can call these methods on the root timeline of the page. If they are code based, you just need to target the page's timeline, or the page document class associated with that timeline (AS2/AS3).

For instance, if you use something like TweenLite for your transitions, you can set the Gaia complete methods as the onComplete parameter of the object you pass to TweenLite. Gaia's scaffolded Actionscript Transition Templates use this code.

AS3 

 override public function transitionOut():void
 {
     TweenLite.to(this, .3, {alpha:0, onComplete:transitionOutComplete});
 }


AS2 

 public function transitionOut():Void
 {
     TweenLite.to(this, .3, {_alpha:0, onComplete:Delegate.create(this, transitionOutComplete)});
 }

In general, it is recommended that you do not override the complete methods and instead just call them. You can override the complete methods in AS3 without issue, but there is a Flash bug in AS2 if you override the complete methods when using timeline transition style templates.

When you call the complete methods, Gaia will attempt to destroy the page, so always call it last. In AS3, make sure you do proper cleanup on your page, stop and destroy any running timers, enter frame listeners, etc.


Page Properties

There are three properties that are set in the document class/root timeline of your page swfs: assets, page and copy.

Note: These three properties are not available until transitionIn() is called.

assets 

assets:Object

If a page has assets in the site.xml, they are stored in this object by their id. More information about how to access assets is found in the Assets section of the documentation.

page 

page:PageAsset

A reference to the PageAsset class of the page is available in this property. This gives you direct access to the properties that Gaia uses to define your page, such as a page's parent, children, branch or other properties. Example:

AS2 and AS3 

 var myBranch:String = page.branch;
 var myParentSrc:String = page.getParent().src;

More about the public page properties can be found in the Site XML section of the documentation.

copy 

copy:Object

If a page has SEO turned on in the site.xml and an XHTML page has been generated for this page, the p tag values will be available in the copy Object. Read the SEO documentation for more information. 

var TXT_Header:TextField;
TXT_Header.text = copy.someValue;
trace(copy.anotherValue);

onDeeplink

There is an optional page method for deeplink functionality that works with SWFAddress. 

onDeeplink(event:GaiaSWFAddressEvent)

When a deeplink event occurs from SWFAddress, the deeplink will be passed to your page swf via this method. The event has the deeplink property. Gaia handles this for you so you don't have to deal with adding and removing pages as listeners to the deeplink event manually. More information about deeplink events can be found in the Events and Hijacking section of the documentation.

The GaiaSWFAddressEvent has two properties, deeplink and branch. The deeplink property is the value beyond the valid branch, and the branch property is the vaild branch that the deeplink value is part of.

You override this method in your page class like this

AS3 

override public function onDeeplink(event:GaiaSWFAddressEvent):void
{
   // handle the event.deeplink
}

AS2 

public function onDeeplink(event:GaiaSWFAddressEvent):Void
{
   // handle the event.deeplink
}

If you have clips or classes inside your pages that need to respond to this event, you can simply have them listen to the page for the GaiaSWFAddressEvent.DEEPLINK event. You'll need to call super.onDeeplink(event) in your override if you want this functionality. Otherwise, you don't need to call the super method if you don't want to.


Technical Information

Within Gaia, Pages are instances of the PageAsset class, which inherits from MovieClipAsset. A Page swf is loaded into a dynamically generated MovieClip and a reference to that MovieClip is passed to its PageAsset instance. A reference to the PageAsset class and its "assets" property is set in the document class of that MovieClip. The document class of that MovieClip is generated during scaffolding and extends AbstractPage, which extends AbstractBase.

The three properties, assets, page and copy, as well as the onDeeplink event listener are found in the AbstractPage and AbstractBase classes the Pages inherit from. Both of these classes are in the com.gaiaframework.templates package.

AS3 Pages

AS3 pages use a document class, and do not require the above code. If you are using Timeline templates, it's similar to the above except the only method on the first frame is stop();. If you're using Actionscript templates, there is no code on the timeline. The scaffolding is a single line in the constructor of the page class. 

new Scaffold(this);

AS2 Pages

If you are using Timeline templates, on the timeline of each scaffolded page you will see an AS (Actionscript) layer, a LABELS layer, and a content layer. You will also see two frame labels, "in" and "out".

If you are using Actionscript templates, there is only one frame.

In the first frame of the AS layer, you will see the following code: 

 import Package.Page;
 Page.initDocumentClass(this);
 stop();
 scaffold();

The Package and Page will be named after the class package and page id. Inside the page class, the initDocumentClass(this) method simulates AS3 Document Class functionality.

Once you are ready to work, you can delete the "scaffold();" line and remove the scaffold function from the page class.

Page Classes

The AS2 and AS3 page classes extend AbstractPage which extends AbstractBase and implement the IPage and IBase interfaces, respectively.

AbstractPage contains the assets and page properties, as well as the onDeeplink function.

AbstractBase contains the four required transition methods. You can choose to override the transitionIn() and transitionOut() methods, which by default have gotoAndPlay() methods, or you can choose to listen to the events they dispatch.

The transitionInComplete() and transitionOutComplete() methods should not be modified, and if you override them for custom purposes, make sure you call the super class method in AbstractBase.


Removing Scaffolding From Pages

Image:scaffolding_example.jpg

Once you have scaffolded your site, removing the scaffolding is simple.

In AS3, delete this line in the Page class constructors: 

new Scaffold(this);

In AS2, delete this line on the first frame of the Page template files: 

scaffold();

Also, feel free to delete the scaffold() method in the AS2 Page Classes.

Once you are completely done removing that one line of code from all of your pages, you can then remove the scaffold.swf from the deploy folder, and the Scaffold.as class from the package you scaffolded your pages into. This is not required, but once you delete the scaffold code from your pages, these files are no longer used, so you might as well delete them.

You can also remove the super.transitionIn() and super.transitionOut() calls in both AS2 and AS3, if you like.

The preload.fla file has a clip in the library called PreloaderScaffold. It is assigned the class PreloaderScaffold.as in the package you scaffolded your pages into. If you like, you can delete the clip from the library and its associated class once you write your own preloader. A lot of people use the PreloaderScaffold as a starting point, though, so you're welcome to do that, as well.

*** Make sure you publish the Page files again after you remove the Scaffolding code***

Retrieved from "http://www.gaiaflashframework.com/wiki/index.php?title=Pages"