4. API methods - Glidias/Kilogaiajax GitHub Wiki

The Kilogaiajax API can be accessed globally using the Gaiajax.api object. This object contains the following methods:

Navigation methods

The sample code in this section is related to the Site XML context example as found here in Getting Started section.

goto(path:String) Remotely navigate to a particular valid page branch or/and/may produce a deeplink given a path.

   Gaiajax.api.goto("page-container/page3"); // navigates to "page-container/page3"
  
   Gaiajax.api.goto("page-container/page3/blah14/abc"); // will still navigate to page-container/page3, but provide a deeplink of "/blah14/abc"
   // HTML5 browers will display address as: page3.html#/blah14/abc
   // HTML4 browers will display address as: #/page-container/page3/blah14/abc

getValidBranch(path:String):String Returns a valid page branch given a path.

   Gaiajax.api.getValidBranch("page-container/page3/blah14/abc") // returns "page-container/page3"

getValidBranches(path:String):Array Returns similar to as above, but in array format split by "/" delimiter.

getDeeplink():String Returns any current deeplink accordingly (ie. non-valid/non-page node branch paths), with trailing slash in relation to currently viewed valid page branch.

    // Assuming current browser address bar shows "page3.html#/blah14/abc" (for HTML5 browsers)
    // or shows "index.html#/page-container/page3/blah14/abc"  (for HTML4 browsers)
     Gaiajax.api.getDeeplink() // returns "/blah14/abc"

setDeeplink(deeplink:String) Sets the deeplink in relation to current page branch location.
getValue():String Returns full hash value, similar to "SWFAddress.getValue()" or "window.location.hash", but taking into consideration any possible fragment identifier ("!") being set, which "window.location.hash" lacks. A fragment identifier can be set using javascript with SWFAddress.fragId = "!";. Normally, this is only done if you wish to set up your server to provide HTML snapshot for HTML4 browser links. Normally, I don't bother with this anymore since most site sharing/anchor links should use the regular URLs, not hashbang ones.
getCurrentBranch():String Returns current valid branch of the site being viewed.

Page-related methods

The basic page node class instance in the site model is called KeyValue. It consist of the following public properties. Please follow the recommended read/write rules to avoid any complications.

title - (String) Based off Site XML (read/write)
src - (String) Based off Site XML (read/write)
id - (String) Based off Site XML (read-only)
json - (Object) The JSON/Javascript-Object representation of the XML page node. (read-only, but can read/write within Object)
pageAssets - (Array) Array of JSON/Javascript-Object representation of all XML asset nodes under the page node. (read-only, but can read/write within Array)
path - (String) The cached branch route path leading to this page (read-only)
getPage(branchPath:String):KeyValue Using a valid branch path, returns a valid KeyValue page, from which you can retrieve page properties. Returns null if page isn't not found.
getPageBySrc(src:String):KeyValue Returns a valid KeyValue page using the src attribute value as the key. Returns null if not found.
getCurrentPage():KeyValue Gets current KeyValue page based on current valid branch being viewed.
getTargetPage():KeyValue Gets the currently targeted (ie. intended) KeyValue page to be navigated to, regardless of application state.
getCurrentContent():JQuery Gets the currently viewed page contents in JQuery.

On-demand page related methods

Refer to this page for more information.

setOnDemandPage(src:String, branchPath:String, id:String, assetBranchPath:String, title:String) Dynamically adds a KeyValue page into the Site Model (ie. the parsed Site XML) on-the-fly.
setOnDemandHandler(handler:Function) Sets up a function to to resolve gaiaHrefLink URLs, in the event no matching "src" key page is found in the Site Model.

Asset-related methods

getPageAsset(assetIdOrSrc:String) Retrieves an Asset class instance (if available) under the currently viewed page branch, based off asset's "id" attribute value in it's asset XML nodes. If no "id" is found, than you need to retrieve asset using it's "src" attribute value.

All Asset class instances a id and src public property values as parsed in the Site XML. Please use these properties for read-only (reference) purposes only. Currently, these are the available Asset classes:

JSONAsset - contains public getData():Object method to retrieves parsed JSON object.
ImageAsset

Navigation link methods

Refer to this section in Step5: Getting Started for information on how to automatically hook up ajax-links for existing page HTML content.

bindHrefLinks(query:JQuery) Manually bind click events on the following JQuery list of DOM anchor tags to act like a "gaiaHrefLink". Use unbindHrefLink(query:JQuery) to unbind click events.
bindRelLinks(query:JQuery) Manually bind click events on the following JQuery list of DOM anchor tags to act like a "gaiaRelLink". Use unbindHrefLink(query:JQuery) to unbind click events.

Normally, you need to use the above manual methods if certain HTML content are dynamically generated on-the-fly with Javascript.

Transition-related methods

Site/global-specific (permanent)

setDefaultTransitionIn(method:Function) Sets a default transition-in method in the format of function(callback,content) for the entire site. By default, a JQuery fade animation is used for the content. "callback" refers to the method to call for notifying that the transition is 'completed' (in order to flow to next phase).
setDefaultTransitionOut(method:Function) Same as above but for transition-out instead.
getDefaultTransitionIn():Function Gets the default transition-in method currently set for the entire site.
getDefaultTransitionOut():Function Gets the default transition-out method currently set for the entire site.

Page-specific (transient)

setGaiaTransitionIn(method:Function) Sets the currently visited page's transition in method in the format of function(callback,content), overwriting the default transitionIn method for the entire site. This is automatically unset once a page transitions out. This is normally done after preloading has finished (or when a page-specific JS finishes loading), using this method to set a specific page's transition behavior. You can still retrieve back the default method (and use it), like Gaiajax.api.getDefaultTransitionIn()(callback,content).
setGaiaTransitionOut(method:Function) Same as above but for transition out method instead.
setGaiaTransitionInComplete(method:Function) Sets a notification method to call when transitioning in a page has "completed" in the format of function(content).
setGaiaTransitionOutComplete(method:Function) Sets a notification method to call when transitioning out a page has "completed" in the format of function(content).

Misc methods

setTitle(title:String) Sets the HTML document title directly. Proxy for window.document.title.
getTitle():String Gets the HTML document title. Proxy for window.document.title.
setPageTitle(title:String) Sets the page title remotely, using the format as defined in the site node in Site XML.
getRoot():Object Returns the JSON/Javascript-Object representation of the <site> node in the Site XML.
getSrcURL(url:String):String Gets standardized URL relative to site root url location (ie. the expected URL value you'd expect from your Site XML's page node's src attributes). Site root url can be set using something like Gaiajax.api.setRootURL("http://localhost/mysite/"). Eg. Using getSrcURL("http://localhost/mysite/section2/about.html") returns section2/about.html.

Configuration methods

setContentWrapper(elementId:String) Sets the content wrapper to a different DOM element using document.getElementById(elementId). The element id is "contentWrapper" by default.
enforceHTML4() Enforces legacy HTML4 url address changes always, using hashbang paths only.
setRouting(value:Boolean) This doesn't do much for now unless you're using automated Google Analytics page-tracking for your Site XML model. Setting this to "true" will use each page's branch path to identify the page instead of the page's "src" attribute for tracking pages. Normally, if your site contains multiple pages sharing the same src attribute, you may want to set this to "true" in order to differentiate pages uniquely by their page branch route instead of it's src attribute.
setQueryStringAbsolute(value:Boolean) Defaulted to false. Setting this to true will globally make all pages' nodes' src urls with query-strings refer to unique src URLs in their own right, irregardless of any page node's lack/inclusion of query="1" attribute setting.

Setting the Base URL if needed

getRootURL():String setRootURL(url:String) You should set this to allow ajax calls to pages to work in sync with base href. THis is often done for sites whose urls may not exist on the root site location with file extension. (eg. folder-based paths).
<script src="js/site.js"></script> <script type="text/javascript"> Gaiajax.api.setRootURL("http://localhost/mysite/"); </script>

I've yet to consider automating this process by reading the <base> tag directly. But for now, you must manually declare set the root url accordingly. This will allow AJAX calls to pages to start from the base URL prefix, rather than from the current URL in the address bar. If you have PHP, the following approach to get the base URL should work:

<head>
   <?php
   $baseurlprefix = substr($_SERVER['PHP_SELF'], 0, strrpos($_SERVER['PHP_SELF'], '/')); 
   if ($baseurlprefix != "/") $baseurlprefix .= "/"; 
    ?>
  
    <base href="http://<?php echo($_SERVER['HTTP_HOST'].$baseurlprefix) ?>">

    <!-- ..... -->
    <script type="text/javascript">
        	Gaiajax.api.setRootURL("http://<?php echo($_SERVER['HTTP_HOST'].$baseurlprefix) ?>");
    </script>
 </head>