-
Notifications
You must be signed in to change notification settings - Fork 27
Site xml
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.
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 title="Gaia Scaffold Site: %PAGE%">
The site node is the root node of the XML. All of the attributes are optional.
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.
If you set this to "false", Gaia will disable SWFAddress from adding items to the browser history. This is "true" by default.
This is the path to your preloader swf. If you do not define this, Gaia defaults to preload.swf.
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.
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".
Set this attribute to "true" if you want the Gaia navigation to appear in the right-click menu.
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.
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.
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.
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.
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.
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.
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 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.
Each page needs a unique id. The id attribute must be alphanumeric (no hyphens), and must start with a letter, not a number!
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.
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.
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.
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.
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.
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.
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.
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".
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.
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.
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.
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.
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.
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.
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.
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 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.
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!
The src of the asset. The extension of the asset file determines how Gaia handles them, unless you override the type (see below).
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)
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.
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)
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.
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.
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.
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.
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.
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.
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.
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.
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}"/>
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"/>
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"/>
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"/>