Português:Eventos e Hijacking

TRANSLATION PENDING

Introdução
O funcionamento dos eventos e do Hijacking do Gaia são uma de suas mais poderosas e ágeis ferramentas, além de um conceito fundamental no qual ele é baseado.

O Gaia tem dez eventos no total. São nove eventos de flow, sendo possível fazer o hijacking de oito deles. "Hijackable event" quer dizer que você pode criar um listener que vai pausar o Gaia framework até que você diga a ele que você está pronto. Isso permite a você executar códigos assíncronos ou animações na timeline, enquanto o framework espera. Muito poderoso.

Você pode associar qualquer quantidade de listeners e/ou hijackers para um único evento. Se você criar múltiplos hijackers, o framework irá esperar até que todos hijackers sejam completados antes de continuar rodando.



Argumentos do método Flow Event
Cada um dos nove métodos de flow event precisa de três argumentos. Um é obrigatório e os outros dois, opcionais, são definidos como "false" por padrão. O método retorna uma função se você define o segundo argumento como true, e de outra forma irá retornar null.

target
target:Function Uma função que é listener. Em AS2, você deve usar um Delegate, e não uma referência direta à função.

hijack
hijack:Boolean Faz com que o framework espere, até que você diga a ele para continuar, chamando uma nova função que é retornada por essa.

onlyOnce
onlyOnce:Boolean Apenas ouve o evento uma vez e então automaticamente remove o target do listener.

Exemplo:

AS2 var myListener:Function = Delegate.create(this, onBeforeTransitionOut); var releaseGaia:Function = Gaia.api.beforeTransitionOut(myListener, true); function onBeforeTransitionOut(event:GaiaEvent):Void {    releaseGaia; }

AS3 var releaseGaia:Function = Gaia.api.beforeTransitionOut(onBeforeTransitionOut, true); function onBeforeTransitionOut(event:GaiaEvent):void {    releaseGaia; }

Você pode, opcionalmente, passar "true" no método de release do Gaia, se você quiser que o hijacker remova a si mesmo posteriormente. Isso livra você de ter que remover manualmente um hijacker que não é um onlyOnce mas que precisa ser removido sob certas circunstâncias (como se existir dentro de um MovieClip ou uma Página que irá descarregar).

Exemplo:

AS3 var releaseGaia:Function = Gaia.api.beforeTransitionOut(onBeforeTransitionOut, true); function onBeforeTransitionOut(event:GaiaEvent):void {    releaseGaia(true); }



GaiaEvent
O evento GaiaEvent é passado em todos os eventos que contém as seguintes properties:

validBranch
validBranch:String O branch válido do goto - um branch válido é um branch que existe no site.xml

fullBranch
fullBranch:String fullBranch é um branch válido com a adição de qualquer deep link fora do escopo do valid branch

external
external:Boolean Se a página é externa, isso será verdadeiro (true). Apenas beforeGoto deve sempre ser true.

src
src:String O src da página que está carregando, externa ou interna

flow
flow:String Se houver um override do flow no evento goto, ele é passado aqui



Eventos do Gaia Flow
Estes são os nove eventos do Gaia para os quais você pode ter listeners ou hijack.

beforeGoto
beforeGoto(target:Function, hijack:Boolean = false, onlyOnce:Boolean = false):Function Este evento dispara antes que o evento goto seja enviado ao framework. beforeGoto ocorre a qualquer momento em que o goto seja chamado, tanto faz se o branch é externo ou se é o branch atual. (que o Gaia ignora - veja a seção Como o Gaia Funciona da documentação).

afterGoto
afterGoto(target:Function, hijack:Boolean = false, onlyOnce:Boolean = false):Function Este evento dispara depois que o goto acontece e antes do início do flow. afterGoto, e os eventos que seguem, ocorrem apenas quando o goto é uma página interna diferente da página atual.

beforeTransitionOut
beforeTransitionOut(target:Function, hijack:Boolean = false, onlyOnce:Boolean = false):Function Este evento dispara antes de iniciar transition out.

afterTransitionOut
afterTransitionOut(target:Function, hijack:Boolean = false, onlyOnce:Boolean = false):Function Este evento dispara quando transition out tiver terminado.

beforePreload
beforePreload(target:Function, hijack:Boolean = false, onlyOnce:Boolean = false):Function Este evento dispara antes que o preloading de um novo branch comece.

afterPreload
afterPreload(target:Function, hijack:Boolean = false, onlyOnce:Boolean = false):Function Este evento dispara depois que o preloading de um novo branch termina.

beforeTransitionIn
beforeTransitionIn(target:Function, hijack:Boolean = false, onlyOnce:Boolean = false):Function Este evento dispara antes de iniciar transition in.

afterTransitionIn
afterTransitionIn(target:Function, hijack:Boolean = false, onlyOnce:Boolean = false):Function Este evento dispara quando transition in tiver terminado.

afterComplete
afterComplete(target:Function, onlyOnce:Boolean = false):Function Este evento dispara depois do flow estar completo. Passar true para o hijack não tem efeito nenhum, pois a API força o false. Isso aconteceu porque o evento afterComplete dispara no final do flow, então o hijacking poderia ficar sem destino.



Métodos de Remoção
Cada um destes eventos de hijack tem um método remove, para o caso de você querer remover o listener manualmente. São eles: removeBeforeGoto(target:Function) removeAfterGoto(target:Function) removeBeforeTransitionOut(target:Function) removeAfterTransitionOut(target:Function) removeBeforePreload(target:Function) removeAfterPreload(target:Function) removeBeforeTransitionIn(target:Function) removeAfterTransitionIn(target:Function) removeAfterComplete(target:Function)



Evento Deeplink
Existe um evento para deeplinks e ele aceita um único argumento.

addDeeplinkListener(target:Function):Void removeDeeplinkListener(target:Function):Void O evento do deeplink ocorre sempre que a classe SWFAddress atualiza, seja pelo navegador ou por um evento goto. O evento passa qualquer deep link além do escopo do branch atual no objeto do evento, como uma propriedade chamada "deeplink".

Por exemplo, se você tem um branch da página "index/home/photos" e deseja ter um deep link e bookmark para uma foto específica - como "index/home/photos/4" - o evento do deeplink irá passar "/4". Neste exemplo, o usuário poderia digitar diferentes números na barra de endereços, e seu código poderia ter que lidar com valores inválidos de deeplink.

Na maioria das vezes, você nunca terá que usar o método addDeeplinkListener, já que as páginas são configuradas automaticamente para receber eventos onDeeplink. Informações mais detalhadas sobre SWFAddress e deep linking podem ser encontradas na documentação de SEO.



Nota Importante sobre Hijacking de Eventos
O hijacking de Eventos pode bloquear seu site se você não tomar cuidado (eu mesmo já fiz isso).

Tenha certeza de que, se você adicionar um hijacker, que isso seja feito apenas uma vez por uma função de retorno (callback). Por exemplo, se você tem um frame com Actionscript e irá navegar indo e voltando daquele frame, certifique-se de que você escreveu seu código de hijacking similar a isso:

function init {    if (!inited) {        inited = true; releaseGaia = Gaia.api.beforeTransitionOut(Delegate.create(this, doSomething), true, true); } } init;

Isso garante que o hijacker seja adicionado apenas uma única vez. Enquanto o gaia previne que o mesmo listener seja adicionado novamente, no exemplo acima, um Delegate é criado a cada vez. É aí que você precisa ser cuidadoso. Esta dica irá ajudá-lo a evitar comportamentos estranhos e a economizar tempo quando isso acontecer. Isso acontece até comigo, o autor, então provavelmente poderá acontecer com você também. Apenas tenha cuidado. O Hijacking de Eventos é extremamente poderoso, e grandes poderes trazem grandes responsabilidades :)