Português:API

TRADUÇÃO EM ANDAMENTO

Introdução
A API do Gaia facilita a utilização do framework. Uma das grandes forças do Gaia Framework é a forma como você estrutura seu site.xml e como você manipula seus eventos.



Como usar a API do Gaia
Este é o método recomendado para usar a API do Gaia em AS2 e AS3:

import com.gaiaframework.api.Gaia; Gaia.api.methodName;

O Gaia implementa a interface IGaia, localizada no package com.gaiaframework.api.

Em AS2, você também pode usar a forma obsoleta (deprecated):

_global.Gaia.methodName;



Métodos da API do Gaia
Veja uma descrição de todos os métodos disponíveis na API do Gaia.



goto
goto(branch:String, [flow:String]):Void goto é o método primário que você irá usar no Gaia. Ele requer pelo menos um argumento ,que é a string do branch em que você quer navegar.

AS3 e AS2 Gaia.api.goto("index/nav/people/friends"); Gaia.api.goto("index/nav/about", Gaia.PRELOAD);

'''apenas AS2 only _global.Gaia.goto("index/nav/people");

O Gaia determina o branch válido mais próximo ao que você passou. Por exemplo, "index" vai fazer o Gaia ir ao primeiro branch válido sob o index. Além disso, se você passar um branch que não existe, ele irá checar todo o caminho até encontrar um branch válido, e então irá até o final da ramificação - este pode acabar sendo o branch do index.

Por exemplo, se o branch válido é "index/nav/people/friends" e você passa "index/nav/people/free", ele irá buscar o mais próximo de "index/nav/people", e como people tem uma página filha, o branch irá terminar em "index/nav/people/friends".

Se você navega além do último child de um branch no site.xml, como "index/nav/people/friends/john", o Gaia guarda "/john" e você pode acessar diretamente através da API, pelo método getDeeplink.

O Gaia envia um evento deeplink quando houver um branch além do branch válido, para o qual você pode adicionar um listener através da API.

As Páginas são configuradas automaticamente para "ouvir" este evento através do método onDeeplink. Veja a seção Pages da documentação para mais informações.

Para atualizar a barra de endereços do navegador com um deep link que vai além do último child do branch, chame goto com o branch da página junto ao seu deep link. Por exemplo:

Gaia.api.goto("index/nav/people/friends/john"); Se o Gaia já estiver na página válida "index/nav/people/friends", ele irá simplesmente atualizar a barra de endereços com seu deep link customizado. Deep links não precisam ser separados por barras (/). Você encontra mais informações sobre este tópico na seção SEO da documentação.

O segundo argumento, opcional, é para sobrepor o flow do evento goto. Use flow constants para fazer isso: Gaia.NORMAL, Gaia.PRELOAD, e Gaia.REVERSE. O Gaia usará esse argumento, ignorando o tipo de page flow, bem como o flow padrão do site. Este item é usado principalmente para testes apenas durante o desenvolvimento. Se você define um flow, e então usa o navegador para voltar e avançar a navegação, o flow não será utilizado novamente - nesse caso o SWFAddress é que estará chamando o goto, e não a função original. Para a produção, você deve definir o flow da página através do site.xml ou então no momento da execução.

Classe Pages
O Gaia gera uma classe chamada Pages quando faz o scaffold do site. Esta classe está localizada dentro do package que você especifica ao fazer o processo de scaffold. Dentro da classe Pages existem variáveis estáticas públicas, nomeadas depois dos títulos (rotas) de suas páginas, e seus branches associados são os valores.

Usar a classe Pages é o método preferencial de chamar goto.

AS3 e AS2 Gaia.api.goto(Pages.HOME); // vai para "index/nav/home" Gaia.api.goto(Pages.FRIENDS); // vai para "index/nav/people/friends"

Usando essa classe com goto, mudar a arquitetura do site.xml não vai causar nenhum efeito em suas chamadas goto ao longo do seu site. Isso também torna mais fácil a utilização de goto.





getPage
getPage(branch:String):PageAsset Retorna a instância do PageAsset para a página. Você passa um branch e retorna o PageAsset da página final daquele branch. Se a extremidade do branch que você passou não tem um id de página válido, o Flash irá retornar undefined (AS2) ou null (AS3).

O PageAsset possui uma propriedade chamada children, que é um objeto que contém propriedades que casam com os ids dessas páginas, e os valores dessas propriedades estão nos próprios PageAssets. PageAssets tem consciência de quem é seu parent, e as páginas também armazenam seu branch como uma propriedade pública.

Se você precisa ter como alvo a timeline de uma página para propriedades customizadas, funções ou MovieClips, use a propriedade "content" do PageAsset.

AS3 Gaia.api.getPage("index/nav/home").content.myProp = value; Gaia.api.getPage("index/nav/home").content.myFunc; Gaia.api.getPage("index/nav/home").content.MC_Movieclip.x = 10;

AS2 Gaia.api.getPage("index/nav/home").content.myProp = value; Gaia.api.getPage("index/nav/home").content.myFunc; Gaia.api.getPage("index/nav/home").content.MC_Movieclip._x = 10;

Mais informações sobre propriedades de página podem ser encontradas nas seções PageAsset, Pages e Site XML da documentação.



getDepthContainer
getDepthContainer(depth:String):Sprite // AS3 getDepthContainer(depth:String):MovieClip // AS2

Retorna o Sprite ou MovieClip container de depth. Passe uma das constantes de depth ao usar este método.

var top:Sprite = getDepthContainer(Gaia.TOP); // AS3 var middle:MovieClip == getDepthContainer(Gaia.MIDDLE); // AS2



getSiteTitle
getSiteTitle:String Retorna o valor do atributo title (título) do site node com o token %PAGE% ainda contido nele.



setSiteTitle
setSiteTitle(value:String):void Define o título do site. Você pode incluir o token %PAGE% se quiser.



setDelimiter
setDelimiter(value:String):void Define o delimitador para o site, se você usar setSiteTitle com um delimitador diferente. Você precisa chamar refreshContextMenu para ter esta mudança refletida no Menu de contexto (botão direito do mouse).



getValidBranch
getValidBranch(branch:String):String Retorna o branch válido para qualquer branch que você passar.



getSiteTree
getSiteTree:PageAsset Retorna a instância de PageAsset da página index.



getMenuArray
getMenuArray :Array Retorna um array de todas as páginas do site.xml com menu="true" e que possuem título. As páginas são retornadas em ordem de cima para baixo.



getSiteXML
getSiteXML:XML Retorna o site.xml inteiramente



getCurrentBranch
getCurrentBranch:String Retorna o atual branch válido.



getDeeplink
getDeeplink:String Retorna o deep link da classe GaiaSWFAddress que vai além da esfera do site.xml. Quando você tem uma página que precisa saber o deeplink quando abre pela primeira vez, use getDeeplink pois isso não será aberto quando o evento disparar.



getPreloader
getPreloader:IMovieClip Retorna o MovieClipAsset (IMovieClip em AS3) do preloader por targeting direto. Você também pode chamar métodos customizados dentro do swf de seu preloader, reposicionar o clipe do preloader, etc.

<br style="clear:both" />

setPreloader
setPreloader(asset:MovieClipAsset):Void Sobrepõe o MovieClipAsset do preloader com uma referência a um MovieClipAsset já carregado. Se você quiser reverter ao preloader padrão, chame este método sem passar valor algum.

<br style="clear:both" />

getDefaultFlow
getDefaultFlow:String Retorna o padrão de flow atual para qualquer página que não tenha um flow definido (retorna "normal", "preload", "reverse" ou "cross").

<br style="clear:both" />

setDefaultFlow
setDefaultFlow(flow:String):Void Permite que você defina o flow padrão para qualquer página que não tenha um flow definido. Use uma das constantes de flow: Gaia.NORMAL, Gaia.PRELOAD, Gaia.REVERSE ou Gaia.CROSS.

<br style="clear:both" />

getAssetPreloader
getAssetPreloader:IMovieClip Retorna o preloader de assets MovieClipAsset (IMovieClip em AS3) para targeting direto. Você pode chamar métodos personalizados dentro do swf de seu preloader de assets, reposicionar o clip do preloader, etc.

<br style="clear:both" />

setAssetPreloader
setAssetPreloader(asset:MovieClipAsset):Void Permite que você sobreponha o MovieClipAsset AssetPreloader para usar o MovieClipAsset que você passar (o preloader atual do site é utilizado por padrão). Se você quiser reverter para o preloader padrão do site, chame este método sem nenhum parâmetro.

<br style="clear:both" />

getContextMenu
getContextMenu:ContextMenu (AS3 only) Retorna o Menu de contexto anexo a GaiaMain pelo Gaia, tornando mais fácil a modificação de items personalizados no menu de contexto, como adicionar itens customizados ao menu, que não sejam páginas do Gaia.

<br style="clear:both" />

refreshContextMenu
refreshContextMenu:void Se você mudar o título das páginas ou o título do site, chame este método para atualizar o menu de contexto e mostrar os novos valores.

<br style="clear:both" />

addAssets
Gaia.api.addAssets(nodes:XMLList, page:IPageAsset):void // AS3 Gaia.api.addAssets(nodes:Array, page:PageAsset):Void // AS2 Este médoto é utilizado para adicionar assets dinamicamente externalizados a uma página, no momento da execução. Mais informações sobre como usar este método podem ser encontradas na documentação sobre Assets.

<br style="clear:both" />

getWidth
getWidth:int Retorna a largura original do stage quando o site está definido para 100% de altura ou largura. Útil para centralização e outros códigos de posicionamento.

<br style="clear:both" />

getHeight
getHeight :int Retorna a altura original do stage quando o site está definido para 100% de altura ou largura. Útil para centralização e outros códigos de posicionamento.

<br style="clear:both" />

getSitePosition
getSitePosition :Object Retorna a posição atual para x,y position da Site View como um objeto com propriedades x e y. Isto é util quando se estiver usando códigos de centralização.

<br style="clear:both" />

setLoadTimeout
setLoadTimeout(value:int):void

Quando um branch está carregando, cada arquivo deve mostrar progresso no carregamento dentro de um certo tempo, antes que o Gaia tente recarregar o arquivo. Este método permite que você ajuste por quanto tempo o Gaia espera para que um arquivo mostre progresso.

<br style="clear:both" />

setGlobalVolume
setGlobalVolume(value:Number, duration:Number = 0; onComplete:Function = null):void

Este método é utilizado para definir o volume global do site inteiro. Se você passa um argumento opcional de duração, isso irá causar um fade do volume até o valor definido em segundos. Se você passa a função opcional onComplete, a função será chamada quando o fade terminar.

<br style="clear:both" />

getGlobalVolume
getGlobalVolume:Number Retorna o volume global atual.

<br style="clear:both" />

Métodos de Proxy para o SWFAddress
Informações mais detalhadas sobre estes métodos podem ser encontradas em http://www.asual.com/swfaddress/docs/en/

<br style="clear:both" />

back
back:Void Carrega a URL anterior na lista do histórico.

<br style="clear:both" />

forward
forward:Void Carrega a próxima URL do histórico.

<br style="clear:both" />

getTitle
getTitle:String Retorna o título atual da janela do navegador.

<br style="clear:both" />

setTitle
setTitle(title:String):Void

Permite a você definir o título do navegador. A string que você passar será o título inteiro, então se você deseja adicionar algo ou alterar o título atual, você deve utilizar getTitle ou getSiteTitle, modificá-lo e então passar isso para setTitle.

<br style="clear:both" />

href
href(url:String, target:String):Void Devido ao erro do AS2 quando se junta ExternalInterface e getURL, este método é um substituto para getURL.

<br style="clear:both" />

popup
popup(url:String, name:String, options:String, handler:String):Void Abre uma janela popup.

<br style="clear:both" />

setHistory
setHistory(b:Boolean):Void

Liga e desliga o tracking do histórico, passando true ou false. Isso está ligado por padrão, a não ser que você defina history="false" no site.xml.

<br style="clear:both" />

getHistory
getHistory:Boolean Retorna o status atual do tracking do histórico.

<br style="clear:both" />

setTracker
setTracker(s:String):Void Define uma função para tracking de page views. O valor padrão é 'urchinTracker'.

<br style="clear:both" />

getTracker
getTracker:String Retorna a função tracker.

<br style="clear:both" />

getBaseURL
getBaseURL:String Retorna a URL base do website. Basicamente, é tudo que vem antes do símbolo # que o SWFAddress usa para o deeplinking.

<br style="clear:both" />

Constantes de Depth e Flow
A API do Gaia tem algumas constantes para profundidades (depths) e fluxos (flows). Use isso quando estiver buscando/definindo depths e flows durante a execução.

Constantes de Depth
Gaia.TOP Gaia.MIDDLE Gaia.BOTTOM Gaia.PRELOADER

Constantes de Flow
Gaia.NORMAL Gaia.PRELOAD Gaia.REVERSE Gaia.CROSS

Constantes de Domínio
Gaia.DOMAIN_CURRENT Gaia.DOMAIN_NULL Gaia.DOMAIN_NEW