Português:XML do site

TRANSLATION PENDING

Visão Geral
O arquivo site.xml está localizado na pasta de publicação dos arquivos (deploy). Ele define a estrutura do seu site e é usado pelo Gaia Flash Framework durante a execução. O site.xml consiste em três nodes: site, page e asset. O asset node é opcional, sendo usado para pré-carregamento de arquivos de mídia junto com uma página.



Path Dinâmico do Site XML
Você pode configurar dinamicamente o caminho do site.xml usando uma FlashVar chamada siteXML. Isso facilita sua localização. Você também pode apontar para um site.xml gerado on-the-fly com um script. O painel do Gaia 3.0 irá escrevê-lo automaticamente para você quando você definir isso no painel.

var flashvars = {siteXML:"dir/site.xml"}



Site Node


O site node é o node raiz do XML. Todos os atributos são opcionais.

title
Coloque aqui o título de seu site. Você pode incluir o token %PAGE% em qualquer lugar do string, que o Gaia irá trocar pelo título da página atual. Se você deixar de fora esse atributo, o Gaia não irá substituir o título da página HTML.

history
Se você atribuir "false", o Gaia fará com que o SWFAddress deixe de adicionar itens ao histórico do navegador. O valor padrão é "true".

preloader
Este é o path para o swf do seu preloader. Se você não atribuir como preloader nenhum swf, o Gaia utilizará como padrão o preload.swf.

preloaderDepth
Pode ser definido como "middle" ou "bottom". Se você não definir o depth, o Gaia utilizará "top" como padrão. Você pode encontrar mais informações na seção Preloader da documentação.

preloaderDomain (somente AS3)
Você pode definir o ApplicationDomain do swf do preloader incluindo o atributo preloaderDomain. Os valores permitidos são "new" e "current". O valor padrão é "null".

menu
Defina este atributo como "true" se você quer que a navegação do Gaia apareça no menu do botão direito do mouse.

delimitador
É usado pelo Gaia para o menu do botão direito (se você não está usando o menu de contexto, você não precisa configurar o delimitador). Por padrão, o Gaia usa ":" mas você pode mudar caso precise. Por exemplo, se o seu título é title="Site Title - %PAGE%", então seu delimitador é delimiter=" - ". Se o seu título é "%PAGE% | Site Title", en tão seu delimitador é " | " e por aí vai.

flow
Por padrão, o Gaia usa o flow "normal". Defina como "preload" ou "reverse" se você quiser que o Gaia use estes flows para todas as páginas que não tem um atributo flow definido.

routing
Se você define o routing como "false", o Gaia irá desligar o roteamento, que habilita URLs "amigáveis" para as páginas e utilizará o atributo "title" da página na barra de endereços (title é usado por padrão, você pode sobrepor esse valor com o atributo "route", como descrito abaixo). Routing é usado por outros frameworks como Ruby on Rails e está descrito nesta página.

Como os deep links de branches normais, o roteamento aproveita os deep links além do route, também. Consulte a documentação sobre SEO para mais informações.

indexFirst
Quando um site do Gaia carrega pela primeira vez, o Gaia irá carregar o primeiro branch. Se você define indexFirst="true", o Gaia irá carregar a página index primeiro, e então carregar o branch. Um possível uso é no caso de você usar um preloader mais leve no início, e então utilizar um MovieClipAsset na página index que seja um preloader mais robusto, e quando transitionIn for chamada no index, você designa esse movieClip como novo preloader.

assetPath
Use este atributo para definir os caminhos de pasta para todos os assets do site. Todos os assets dentro desse site irão carregar baseados nessa pasta, e então você pode organizar seus assets sem inchar seu site.xml. Certifique-se de que seu assetPath termina em uma barra (/)! Você pode usar ../ no node do asset 'src attributes' para acessar pastas anteriores (parent folders).

domain
Você pode definir o Application Domain de todos os swfs no site incluindo o atributo domain. Os valores permitidos são "new" e "current". O valor padrão é "null". Você pode ler mais sobre ApplicationDomain aqui (em inglês).

version
Define a versão do site para forçar o carregamento de todos os arquivos quando você modificá-lo. É o equivalente de um one-time nocache. Se o usuário tiver qualquer arquivo armazenado que não seja daquela versão, ele será recarregado.



Page Node


O page node tem dois atributos necessários, id e src. O restante é opcional.

Páginas filhas (Child pages) carregam no topo das parent pages (a não ser que outra maneira seja especificada) e se uma página tem pelo menos um child, irá carregar o primeiro filho como parte de seu branch, por padrão (a não ser que o atributo defaultChild seja definido, como destacado abaixo).

Há um id de page node especial, index, que é exigido como primeiro page node dentro do site node. A página index carrega antes de todas as outras páginas, e uma boa forma de utilizar isso é colocando seu background, que irá carregar por trás de todos os swfs. Além disso, como index nunca descarrega, é um bom lugar para colocar códigos globais e/ou assets.

id (required)
Each page needs a unique id. The id attribute must be alphanumeric (no hyphens), and must start with a letter, not a number!

src (required)
The path to the swf for this page (or the url for external pages). If you provide a folder path for your pages, Gaia will generate the folder path for both the swfs and the .fla files when scaffolding. If src does not end in swf the framework assumes it's external and will open the link in a browser window (see window attribute below). If the src begins with javascript:, Gaia will call the javascript method and any arguments you pass it. Note: Do not put spaces between the arguments in javascript functions.

title
This is the title of the page as it will appear in the browser title bar. Only the last children of a branch will have their title appear. However, the preloader has access to the page information when it's loading, so if you choose to display the title of the page loading you can give all pages a title.

menu
Set this to true if this page should appear in the right-click context menu. The context menu uses the title attribute for the page, and if it's missing it will not be added to the right-click menu, so make sure you define the title attribute if you set menu="true".

Note, some page titles may not show up in the Context Menu because certain words are reserved by Flash for the Context Menu. A complete list of reserved words can be found here.

depth
Most of the time, you should leave this attribute out and let Gaia manage the z-ordering for you. However, if you have specific needs, you can set this to one of the optional values middle, top or bottom. By setting it to top it will load this page above all other pages, including pages already loaded into top. By setting it to bottom it will load this page below all other pages (but above the index if the index is in bottom, which is its default depth). If you set it to nested (AS3 only), the page will load into its parent page's content. Any assets that belong to a page whose depth="nested" will, by default, load inside of that page, as well.

flow
Leave this attribute out if you want Gaia to use the default site flow (see site node). Set this to normal, preload or reverse if you want this page to use those flows when transitioning to this page when it is the root of the changing branch. Note: The index page always uses normal.

route
If you don't want the page's title to be its "pretty URL", or if your page title contains a special character which cannot be displayed in the address bar (such as non-Latin characters), set the value of this attribute for the page's url in the address bar. Routes must be unique and can only be applied to terminal pages (pages that have no children). Example routes include: "photos", "contact_information", and "2006/07/04/july-4th-photo-gallery". Refer to the SEO documentation for more information.

landing
If you want to override Gaia's default behavior of loading the default child of a page branch, set landing="true" and Gaia will stop on this page if you tell it to goto this page.

window
If the page is external (src attribute is not a swf or a javascript method), you can define the target window it will open up in. The default is "_self". If you want it to open in a new window, use "_blank".

assetPath
Use this attribute to set the folder paths for all assets of that page. All assets inside this page will load from this folder path so you can organize your assets without bloating your site.xml. Make sure your assetPath ends in a forward slash! You can use ../ in the asset node src attribute to go up to parent folders. This trumps the site node assetPath for the page that it is set on.

defaultChild
Most of the time, this is used only for debugging (for instance, if you're testing a specific page in the site) or is set at runtime directly on the page (for instance, if you want to skip an intro). This attribute allows you to target a specific child of a page that is not the first child of that page. Set it to the id of the child page you want to load by default.

bytes
The bytes attribute is used for accurate preloading. You can set this manually, but it's better to let the Gaia Panel's Update File Bytes In XML feature handle it for you.

seo
The seo attribute is used with Gaia's SEO Scaffolding. Setting seo="true" will generate an XHTML page named after the page id (e.g. "home.html"). You can also set seo to a custom file name. Page nodes with an seo attribute must have a title attribute, as well, or will not have XHTML pages generated for them.

seoBytes
Like the bytes attributes, the seoBytes attribute is used for accurate preloading. You can set this manually, but it's better to let the Gaia Panel's Update File Bytes In XML feature handle it for you.

domain (AS3 Only)
You can set the Application Domain of a page swf by including the domain attribute. Acceptable values are "new" and "current". The default value is "null". You can change this property on ISprite at runtime, as well, by setting the property domain to one of the domain constants.

fonts (AS3 Only)
You can set a comma delimited list of Font class names available in the page swf. Do not put spaces between Font names in the list. For use with Gaia's Runtime Font Loading.

package
You can set a custom class package for your page class by adding the package node before scaffolding (you should remove the package attribute once you scaffold the page). The page package is appended to the class package in the panel. For example, if the class package in the panel is "com.project" and the package attribute is "pages.nav" then the class for the page will go inside "com.project.pages.nav".



Asset Node


Asset nodes go inside page nodes. Assets are preloaded with a page. Currently supported asset types are mp3, wav, flv, xml, swf, jpg, png, and gif. AS3 also supports AAC (m4a) files as of Flash Player 9.0.115. The asset node has two required attributes, id and src, and six optional ones, title, depth, type, preload, progress and streaming.

id (required)
Assets need unique ids per page and the ids cannot be a reserved property or function name of MovieClip objects. The id attribute must be alphanumeric (no hyphens or underscores), and must start with a letter, not a number!

src (required)
The src of the asset. The extension of the asset file determines how Gaia handles them, unless you override the type (see below).

title
This is used by the preloader and is also available to you if you need it (for instance if you wanted to show an image and its name you could store that in its title)

depth
By default, Gaia loads assets in the same depth container as the page they belong to. If you need to load a page's asset into a different depth than the page, you can set that here. The valid values are "top", "middle", "bottom", "preloader", and "nested" (AS3 only). The "preloader" depth is used to load an asset into the preloader clip depth. This should be reserved for overriding the first preloader with a new swf. Make sure you do not set preload="false" on these clips. They must be fully loaded to be assigned as a new preloader. The "nested" depth means the asset will load inside the page content clip.

type
Set this if you want to override the default Gaia behavior of using the extension to determine the asset type. This is useful in cases where you are loading XML via a PHP script, loading mp3s from Akamai, or any situation where the extension does not define the asset's type.

The valid types are
 * netstream
 * sound
 * xml
 * movieclip
 * stylesheet
 * soundclip (as2 only)
 * bitmap (as3 only)
 * sprite (as3 only - for BitmapSpriteAssets)
 * json (as3 only)
 * bytearray (as3 only)

You must set the type to "soundclip" if you are loading a SoundClipAsset swf.

preload
If you set this to "false", the asset will not preload with the page, and instead will be ready to load-on-demand. It is "true" by default.

progress
If preload is set to "true" and the asset is not an flv, mp3 or wav, setting progress="true" will make the preloader display the loading progress of the on-demand asset.

streaming (AS2 Only)
For SoundAssets only, if streaming is set to "true", the mp3 or wav will stream instead of play as an event. This is useful for on-demand SoundAssets that you don't want to wait to finish loading before playing.

bytes
The bytes attribute is used for more accurate preloading. You can set this manually, but it's better to use the Gaia Panel's Update File Bytes In XML feature. If your asset is dynamically loaded, like a php call for XML, if you know the approximate size, you can enter it here. You can also put in a fake larger number of bytes and Gaia will self-correct once the asset is finished loading. However, it's best to be as close as you can.

domain (AS3 Only)
You can set the Application Domain of a swf asset by including the domain attribute. Acceptable values are "current" and "new". The default value is "null". You can change this property on ISprite at runtime, as well, by setting the property domain to one of the domain constants.

fonts (AS3 Only)
You can set a comma delimited list of Font class names available in the asset swf. Do not put spaces between Font names in the list. For use with Gaia's Runtime Font Loading.

assets
If your asset is an xml asset and contains dynamic externalized assets, set assets="true" and the Gaia Panel will set the file bytes size when updating file bytes.



Binding Expressions
Gaia supports binding expressions, similar to MXML, in the src, seo and assetPath attributes. This feature is primarily for localization, but you can use it for other purposes. A binding expression is {surrounded} by braces.

You use a binding expression to resolve a variable at runtime in Actionscript. You can bind the variable to a FlashVar, a public var in your Main.as class, or a public property in a page's document class (the page must be loaded to access it). You can change the property it binds to at runtime, and it will use the current value.

The binding expression can appear anywhere in the string. The seo attribute only supports binding expressions that resolve to Main or FlashVars, not page variables because it needs to resolve during the parsing of the site.xml, which means no pages are loaded.

Do NOT use binding expressions in any of your attributes until after you're done scaffolding and updating file bytes in XML!

The Gaia panel will not scaffold a page, or set the bytes if there is a binding expression in the src. Binding expressions are intended for when you're already done with the scaffolding and ready to localize your site.



FlashVars Example
To access FlashVars with your binding expressions, use the @ symbol (just like E4X). This will look for the FlashVar called language, which you set in the HTML. 



Main Class Example
This example shows how to access a public var language in your Main.as class and src will resolve to whatever that is set to at the time. In this case, it might be language = "en". 



Index Page Example
This example looks in the IndexPage class for a public property language. Notice the branch (index) is separated from the property "language" with a period. Index must be loaded for this to work. 



Branch Page Example
This example looks in the HomePage class for a public String property named fooFileName. Notice the branch to the page is separated from the property "fooFileName" by a period. Keep in mind that pages must end in .swf in the site.xml or they will be considered external. 

<br style="clear:both" />

Site XML Examples

 * Mojo Cosmetics
 * Rescue Me
 * Damages
 * It's Always Sunny In Philadelphia
 * Nip/Tuck
 * Rolling Rock
 * 180
 * Tiberium
 * Royal Salute
 * Grain Design Agency
 * mY Generation
 * Bluecadet Interactive