2. Getting Started - Glidias/Kilogaiajax GitHub Wiki

Step 1: Setting up your development environment

Okay, first things first, it's recommended you have a development environment that supports running PHP scripts. Reason being, I'm using a server-side solution (ie. a PHP script/library called xml2json) to help generate out the actual JSON output for your Site XML model. The thing is: Why use JSON? Well, at the time when I created this framework, I didn't know it was possible for Jquery to parse XML directly. However, I feel a server-side solution is still better because the generated JSON output is smaller, and JSON is easier/faster to process with client-side javascript. The only thing is: JSON isn't very easy to write manually with a text-editor, especially for non-programmers.

So, set up a local server on your hard-drive like WAMP or something to be able to run PHP scripts under the folder.

You need the have the following folders and files to get started developing:

/scripts PHP scripts for generated JSON output
/js/site.js The core framework code for Kilogaiajax framework.
/js/libs All dependencies which Kilogaiajax framework requires.
/xml/site.xml The Site XML
index.html Your landing page. Can be index.php, default.php, etc. depending on your server environment.

Note: For the js files under the lib folder, you can safely use a more updated version of JQuery. However, please stick to the current version of swfaddress and history.js, as some code modifications were done to these 2 files which differs from the original.

Step 2: Prepare your basic global HTML template

This is a basic HTML template outline that you intend to use for all HTML pages on your site. These consist obviously with your HTML header and body tag. Your body tag may consist of commonly shared stuff like some global navigation bar and site logo. Here's a bare-bones example showing the required dependencies:

<!DOCTYPE HTML>
<html>
<head>
<title>Kilogaiajax Example Site</title>
<script src="js/libs/jquery-1.8.0.min.js"></script>
<script src="js/libs/swfaddress.js"></script>
<script src="js/libs/history.js"></script>
<script src="js/site.js"></script>
</head>
<body>		
	<div id="contentWrapper">
		<!-- any page-specific content divs must exist under contentWrapper -->
		<div></div>
	</div>
	<!-- global preloader below is optional  -->
	<div id="preloader">
                  
	</div>
</body>
</html>

The key here is the "contentWrapper" div. Any children under the contentWrapper will be treated as page-specific content, and will transition in/out accordingly as a page transition. By default , the transition method being used is a Jquery fade animation that must finish before continuing.

By default, Kilogaiajax's default preloader behaviour involves setting the CSS visibility of the preloader div on and off. If you exclude the preloader div, the site can still run as per normal.

For frontend scripters:

It's possible to define your own custom page transitions (across the entire site or for a specific page) if you need to. This is covered in a later step.
It's possible to hook into the preloader events to perform additional preloader functionality. This is covered in a later step. Currently, I don't have any method to support overwriting the default CSS visibility preloader behaviour, though I intend to provide support for overwriting this behaviour in the roadmap.

For backend developers:

Ajax-loaded content (ie. loaded through KiloGaiajax with a ?ajax=1 flag ie. not the initial browser loaded page) need not necessarily include the <!DOCTYPE HTML> header. If you do not have that HTML header, than it is assumed there is no head/body/contentWrapper tag, and all content is treated as ajax-loaded page-specific content. Your server could optimize the output of HTML content in the case of reading ?ajax=1 flag, and simply generating the inner html content under contentWrapper without the extra html boilerplate. An example of such a file output can be found in here .

Step 3: Prepare your Site XML

A basic Site XML consist of all explicitly declared pages and assets that exist in your website. This file exists under xml/site.xml by default. A github example can be found here.

Here's an example:

<?xml version="1.0" encoding="utf-8" ?>
<site title="Kilogaiajax Example Site: %PAGE%">
	<page>
		<page id="page1" src="index.html" title="Page1">
			<!-- any page-specific asset nodes go here -->
		</page>
		<page id="page2" src="pg2.html" title="Page2">
			<!-- any page-specific asset nodes go here -->
		</page>
		<page id="page-container">
			 <page id="page3" src="page3.html" title="Page3"></page>
		</page>
	</page>
</site>

The <site> node has a "title" attribute that sets the title of the website dynamically (via Javascript) based on the current page being loaded. The %PAGE% tag is automatically replaced by the currently viewed page's "title" attribute when transiting into different pages. Traditionally, it is best practice to ensure the <title> values for all outputted html pages matches the format as presented in the Site XML.

The first page child node that exist within a parent page node basically acts as a 'landing page' (ie. a page that is visited first by default under that branch location). This is mainly relevant For HTML4 browsers that uses purely routing hashbangs paths (eg. #/page-container/page3) to navigate a site rather than setting the Address bar URL to page3.html in this case.

Your page src urls need not necessarily match the page structure hierarchy, but should link to the actual HTML contents.

For this Site XML, the Homepage is at "page1", using index.html for the source content, since it's the first declared valid page node.

The empty dummy root page node under the site node is mandatory. This acts like an "imaginary" page node referring to the "entire site". You can place assets under this node (like in the github example) to dynamically preload global assets for your entire site, prior to transitioning into the first-requested page. (which may not be the Homepage, since the user's browser might remotely request a different URL or hashbang deeplink).

Step 4: Create your HTML pages and their contents

Okay, this is pretty self-explanatory. You can, obviously, use some form of templating strategy though depending on your development environment. (copy and paste, some software or PHP, CMS, etc.)

Step 5: Ajaxify your HTML anchor links!

To allow seamless transitions to occur when clicking on SEO-friendly anchor links (eg.<a href="page3.html"></a>) tags, simply add a class called "gaiaHrefLink" to the anchor tag like <a href="page3.html" class="gaiaHrefLink"><a>.

You can also allow transitioning to a remote branch location as found in the Site XML, using a class called "gaiaRelLink" instead. eg. <a href="#/page-container/page3" class="gaiaRelLink"><a>. In some cases, you might need to use this if you can't identify a page uniquely with the "src" attribute (particularly, if the "src" attribute value is shared across different pages).

In this case, both links lead to the same page. Except the first one is the SEO-crawlable.

Any dynamically loaded content (including the current document template HTML) can use these class markers for all anchor tags to uniquely identify ajax links.

(Any steps from here onwards is mainly for frontend scripters)

Step 6: Script any global functionality across your entire site. (if required)

You can refer to the example file at https://github.com/Glidias/Kilogaiajax/blob/master/js/main.js for some examples on global functionality.

Step 7: Script page-specific functionality.

You can refer to the following links as a guide:

If you're using individual page javascript files. https://github.com/Glidias/Kilogaiajax/wiki/%5B-How-to:-%5D-Set-up-page-specific-Javascript-files
If you intend to use a single compiled javascript file. https://github.com/Glidias/Kilogaiajax/wiki/%5B-How-to:-%5D-Page-class-routing