Site XML
From Gaia Framework Wiki
Contents |
Overview
The site.xml file is located in the deploy folder. It defines the structure of your site and is used by the Gaia Flash Framework during runtime. The site.xml consists of three nodes: site, page, and asset. The node asset is optional and is used to preload media with a page.
Dynamic Site XML Path
You can dynamically set the path to the site.xml using a FlashVar called siteXML. This makes localization easy. You can also use this to point to a site.xml generated on the fly with a script. The Gaia 3.0 panel will write this automatically for you when you set it in the panel.
var flashvars = {siteXML:"dir/site.xml"}
Site Node
<site title="Gaia Scaffold Site: %PAGE%">
The site node is the root node of the XML. All of the attributes are optional.
title
Put your site title here and you can include the token %PAGE% anywhere in your string which Gaia will swap out with the current page title. If you leave this attribute out, Gaia will not override the title of the HTML page.
history
If you set this to "false", Gaia will disable SWFAddress from adding items to the browser history. This is "true" by default.
preloader
This is the path to your preloader swf. If you do not define this, Gaia defaults to preload.swf.
preloaderDepth
This can be set to "middle" or "bottom". If you do not define this, Gaia uses "top" by default. More information can be found in the Preloader section of the documentation.
preloaderDomain (AS3 only)
You can set the ApplicationDomain of the preloader swf by including the preloaderDomain attribute. Acceptable values are "new" and "current". The default value is "null".
menu
Set this attribute to "true" if you want the Gaia navigation to appear in the right-click menu.
delimiter
This is used by Gaia for the context menu (if you aren't using the context menu you do not need to set this). By default, Gaia uses ": " but you can change this if you need to. For example, if your title="Site Title - %PAGE%" then your delimiter=" - ". If your title="%PAGE% | Site Title" then your delimiter=" | " and so on.
flow
By default, Gaia uses the "normal" flow. Set this to "preload" or "reverse" if you want Gaia to use those flows for all pages that do not have a flow attribute defined.
routing
If you set this to "false" then Gaia will turn off routing, which enables "pretty URLs" to pages and will use a page's "title" attribute in the address bar (title is used by default, you can override this with the "route" attribute as described below). Routing is used by other frameworks such as Ruby on Rails and is described on this web page.
Like normal branch deep links, routing takes advantage of deep links beyond the route, as well. Refer to the SEO documentation for more information.
indexFirst
When a Gaia site first loads, Gaia loads the first branch. If you set indexFirst="true", Gaia will load the index page first and then load the first branch. One use for this is if you want to use a lightweight preloader at first, and put a MovieClipAsset on the index page that is a more robust preloader and when transitionIn is called on index, you assign it as the new preloader.
assetPath
Use this attribute to set the folder paths for all assets of the site. All assets inside this site 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 attributes to go up to parent folders.
domain
You can set the Application Domain of all swfs in the site by including the domain attribute. Acceptable values are "new" and "current". The default value is "null". You can read more about ApplicationDomain here.
version
Set the version of the site to force a reload of all files when you change it. It's the equivalent of a one-time nocache. If the user has any files cached without that version, it will reload them.
Page Node
<page id="index" src="index.swf">
The page node has two required attributes, id and src, and the rest are optional.
Child pages load on top of parent pages (unless otherwise specified) and if a page has at least one child, it will load its first child as part of its branch by default (unless the defaultChild attribute is set, as outlined below).
There is a special page node id index, which is required as the first page node inside the site node. The page index loads before all other pages, and one good use for it is to place your background, as it loads in behind all other swfs. Also, because index never unloads, it's a good place to put global code and/or 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 id="assetID" src="asset.mp3">
Asset nodes go inside page nodes. Assets are preloaded with a page. Currently supported asset types are mp3, 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 "false" 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.
<page id="home" src="{@language}"/>
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".
<page id="home" src="{language}/home.swf"/>
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.
<asset id="myImage" src="images/{index.language}_myImage.jpg"/>
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.
<page id="foo" src="{index/nav/home.fooFileName}.swf"/>
