The Xanjax HowTo

This resource is incomplete. The Xanjax Project is currently looking for individuals who have used Xanjax and who may be able to provide voluntary help in improving the documentation. If you think you can help, please email the project with the words "Contributor Application" in the subject line, stating clearly how you think you can contribute. Thanks.


Getting Started

How To Get Started For The Impatient - Quickly!

  • Download the Xanjax Working Sitekit.
  • Unzip the Sitekit into a web server or hosting site directory.
  • Point your browser at the http://address/[root-directory/] of the Xanjax Sitekit.
  • Follow the Sitekit exercises if you need to.
  • Edit/Add/Remove main menu items and content pages to create your own basic Xanjax XHR website.
Note: Using JSON 'contexts' to add sub-menus or link lists to your Sitekit will help you appreciate some of the less obvious benefits of Xanjax.
How To Assess Required Skill Levels

If you can create XHTML 1.0 Strict conforming web pages with conforming CSS, you already know enough to get started with Xanjax. If you don't, and you're serious about web design, you have some catching up to do anyway. Why not get started right away at XHTML 1.0 - W3C and CSS - W3C. If you shy away from CSS layout, always using tables, I'm afraid you've got a very rude shock coming your way - the world has moved on! Xanjax will work with table based content, but you will probably feel very lost.

JavaScript knowledge, although very helpful, is not necessarily required to use Xanjax for a basic web site.

Xanjax can be useful at all levels of expertise and/or design requirements. Although some of the following HOWTO's are aimed at the more technical designer, newcomers to web design should benefit by improving their awareness of what's possible. Hopefully all readers will be encouraged to explore new ways of doing things and be motivated to create better web design; whether or not they eventually use Xanjax to that end. The learning curve for Xanjax should not be too steep, because there is a working site-kit which you can download to help you get started.

A person With basic XHTML and CSS skills should, without too much trouble, be able to create an XHR/AJAX enabled website based on the Xanjax framework, with a main menu and some XHTML content pages. With average XHTML, CSS and JavaScript skills, you should be able to launch a website which includes client side CMS features that assist in creation and management of supplementary contextual content such as sub-menus, teasers, or link lists. If in addition you have server side scripting or CMS skills, you should be able to merge Xanjax client side design with server side CMS, PHP or other server side solutions to achieve a very flexible, scalable, total solution that won't cost you the earth to host.

If, in addition to the above, you're very competent with JavaScript you'll find Xanjax very easy to use and easy to modify to your own requirements. If you do find Xanjax easy to use and modify, you're competent in an open source server side language such as PHP or Perl, and you would like to contribute to the design effort of Xanjax, please contact me.

How To Think "Xanjax"

For effective use of Xanjax, a Web Designer will need to think outside the box! Xanjax opens up powerful new techniques and possibilities, client side, that previously required server side programming.

Among the most powerful of these is the ability to create and exploit content associations or contexts. Just as a single CSS statement can change the colour, size, or other attribute, of all elements of class "heading" for example, similarly, a single Xanjax "context" statement can associate supplementary content like sub-menus, advertisements, or link lists, with classes of main content pages, and insert this sub-content into the main content at any DOM location.

In this website for example, you may notice that the Sponsors and Resources link lists (to the upper right) appear on howto and faq pages whereas most other pages display Sponsors and Downloads links. Nothing radical about that, but without server side techniques these links would traditionally need to be embedded into each individual content page. Xanjax however, much like server side Content Management Systems or CMS, permits these associations or contexts to be templated within a single file. In Xanjax this file is called root.ctx, it's in JSON format, and does not require databases or server side support of any kind.

Why is this so useful? Well, not only do we get the ability to add, edit or delete a Sponsors link in just one place for all associated content pages (as in server side CMS), for example, we also get faster initial download, superior caching because contexts are cached separately from content, and, because no server side processing is required, there is a significant reduction in server load and NO delay in server response. Put another way, Xanjax gives you this CMS feature without requiring server side software; more responsively, and on lower performance lower cost web servers.

Additionally, because NO reference to the contextual content is used or needed within the content pages themselves, it becomes practical for junior web designers, or even your technically inclined customers, to be delegated content page creation and updates - without fear of them stuffing up your nicely engineered site design and presentation, or your advertising revenue!

In Xanjax, "Content Pages" contain only main content, and they are just normal XHTML 1.0 compliant pages. CSS and JavaScript are applied to main content pages in traditional fashion, either inline, or using header tags. "Context Files" contain only supplementary contextual content and associations, and are in JSON format. Finally, a Xanjax index page and it's associated JavaScript and CSS files, is a control wrapper which, among other things, activates and processes navigation, contexts, communication, and storage.

Thus, with Xanjax we can effectively separate Content, Contextual Content, Appearance, Behaviour, and Control.

Of course, separation into these layers cannot be perfect, either practically or theoretically (as endless blog arguments on the subject will surely testify), but Xanjax offers possiblities way beyond traditional client side solutions in this regard. At last, a web designer can largely decide the degree of conceptual separation useful to their own site development and maintenance requirements, using a fully client side solution. Server scripting or databases may still be used if required, but for many sites server side solutions will now not be necessary.

Now, compare the above Xanjax design layers with the much touted "Content and Presentation Layers."

Xanjax facilitates further separation of "Contextual Content" from "Content." Contextual content items include supplementary content such as advertisements, teasers, link lists, logos, videos or visual decorations that apply to more than one page of main content. In other words, content that is supplementary and has multiple contexts. By making this logical separation, contextual content can be created and managed independently in a single location for an entire set of relevant content pages.

"Presentation," which can be thought of as a combination of appearance and behaviour, is dealt with by Xanjax more or less conventionally. However, the separation of "Contextual Content" from "Content" facilitates separation of the respective content presentation layers too. When using contexts, designers can treat "Presentation of Contextual Content" as a separate layer if they wish.

"Control" is a novel client side layer provided by Xanjax, traditionally found only in server side CMS. It is this control layer that facilitates the client side templating needed for client side CMS, in addition to providing navigation, communication, and temporary storage. It's not necessary for the designer to understand how this works; observation of a few Xanjax "rules," and knowledge of the Xanjax/JSON syntax used in the .ctx templating files is all that's needed to successfully use Xanjax to create and manage contextual content and navigation.

So how does Xanjax achieve all this?

An entire Xanjax website is presented as a single, persistent, but dynamically updateable page. Yes, your entire website content is delivered as a single dynamically updateable index page! That might seem quite radical at first, but the idea is actually quite a natural progression to next level AJAX techniques. Xanjax javascript functions initiate XHTML, XML or JSON content download, via XMLHttpRequest, in response to user input events. They then exploit Document Object Model (DOM) and JavaScript Object techniques to insert the downloaded content into the original index page, in the correct context, directly replacing, deleting or adding to original content.

CSS and JavaScript are effective "sitewide" and "globally" when referenced by the Xanjax index page, whereas when referenced by individual content pages, the effect is "contextual" and "global" - that is, the global scope lasts only for the duration of the calling content page. Browser caching ensures, however, that there is no load delay for subsequent calls to the same CSS or JavaScript by other content pages. This is novel; there is no "sitewide" persistence of any JavaScript or CSS in conventional web design. Remember it, as it can lead to unexpected benefits and unexpected problems!

Contextual JSON, CSS and JavaScript files are used to provide contextual supplementary content, contextual visual alterations, or contextual animations or actions, respectively. Content association "Contexts" are added to a file called root.ctx, which is in JSON format. Contextual CSS and JavaScript can be referenced or embedded in XHTML main content pages in the standard way in header tags, or inline. CSS and JavaScript for 'Contexts' on the other hand can be embedded in root.ctx, or referenced in index or content pages as required.

The original index page must be persistent for Xanjax to work. Content on the other hand, is dynamically added, deleted, replaced, updated or changed as required. While the Xanjax control structure itself can be expanded dynamically to perform additional functions, obviously a minimum structure must always persist to support navigation, content requests, and content embedding.

Xanjax comes prebuilt as a basic framework for building straightforward website designs much like the one you're reading this on now. New users can get started simply by uncompressing the downloadable Xanjax Sitekit into their own Apache (or other webserver) directory and working through the included examples. Familiar Xanjax users will only need to install the Xanjax base framework before building their new Xanjax based website.

See 'How To Create' below to get started with the Xanjax site-kit.

A few rules/guidelines/observations for Xanjax based web design:

  • content pages MUST validate to XHTML 1.0 Strict & MUST use file extension .xml
  • you MUST symbolically link to content pages as .html for SEO & Accessibility
    Note: This is not required for your Xanjax based site to work, only to enable SEO/Accessibility
  • content pages are inserted into DIV id "contentbox" by default
  • contextual content can be added, replaced, or removed at any DOM location
  • object tags don't embed in XHTML content but must be built with JavaScript (because of IE bug)
  • content in a div becomes part of the DOM tree of the persistent Xanjax page
  • content in an object is isolated from the DOM of the persistent Xanjax page
  • object content can be any valid object content
  • query references: Xanjax dynamically replaces "?" with "~"
  • anchor references: Xanjax dynamically replaces "#" with "!"
  • author your content using standard symbols in query and anchor references
    Note: Xanjax reserves "~" & "!" for queries/anchors - they are prohibited in URL's unless you change the defaults.
How To Prepare To Use Xanjax

Xanjax relies on XMLHttpRequest which MUST make requests to a web server. It cannot work directly with a file system due to browser security restrictions. You must have a functional webserver such as Apache to serve your files else Xanjax (or any other XHR solution) will *not* work. Some pages of the Xanjax Sitekit use PHP. If you want those pages to render, you will also need PHP 5.0 or later running on your server. If you're not interested in PHP, just remove those page references from the menu in the Xanjax index.html page of the site-kit (or simply don't click them).

The working skeleton website you can download is called Xanjax Sitekit. Get this going with your web server and test that it all works before attempting to create your own Xanjax based site - then use Xanjax Sitekit as a reference for times that things don't work the way you expect. Xanjax Sitekit is fully tested with Apache Web Server 2.2 and PHP 5.0 on Linux. If none of the index page loads there may be file permission issues preventing your webserver accessing files; OR, your server configuration might need attention. If the index page loads but with messages about CSS or Javascript, one or both are probably disabled in your browser; possibly due to you or someone else having set extreme browser security levels, OR, files have been corrupted in download or have permission issues.

Finally, Xanjax is built on W3C Web Standards. A mindset of adopting at least the same standards to ensure cross browser compatibility and avoid wierd problems will pay off. If your code isn't at least W3C compliant DOM Level 1/2 and CSS Level 1/2 and XHTML 1.0 Strict - then update it. ALL your initial design and testing should be done with a standards compliant browser like Firefox, Opera or Safari. Even if you prefer IE for personal use, it is a well known fact that IE, even version 7.0, does not sufficiently comply with W3C standards to be used as a design tool. (Added note: IE8, even in standards mode, still has some DOM, and XHTML Entity issues) Where a W3C method is not supported by IE, find another W3C method that is (this takes time but I have found it can always be done, and the added care taken often results in better code). Xanjax itself was designed like this; as a result it contains very little browser specific code making it easy to maintain and update. Even where browser specific code has been used, it still complies with web standards, only branching to avoid poor performance, unsupported features, or odd behaviour in non-compliant browsers.

Remember, Xanjax must receive valid XHTML 1.0 Strict served as XML for main content pages, and files should have the extension .xml or, if served by PHP, .php. When serving with PHP it's necessary to use as the first PHP statement "header('Content-Type: text/xml');" to ensure the file is served as text/xml.

Contextual content is templated in root.ctx, which is in JSON syntax. It's not necessary to understand how Xanjax creates and uses contexts until you want to use this feature.

CSS and JavaScript are used as normal EXCEPT that there are two levels - sitewide/global goes in the head of index.html whereas page-duration/global goes in the head of each contentpage.xml. Normally, it's not necessary to mess with Javascript or CSS loaded at index page level - in fact it should be avoided unless you *really* understand how Xanjax works - instead, reference it in the head of your content pages.

How To Create A Basic Xanjax Website

This basic tutorial assumes you already have Xanjax Sitekit *working* - if not, see "How To Prepare To Use Xanjax" above.

To get started, you just need to author a few valid XHTML pages exactly as you would for a standard website (just start with 2 or 3). If you use CSS to style the content, or JavaScript for special effects, just reference these files in the normal way in the head of the document, or inline/in-tag. IMPORTANT: Don't add references to CSS or JavaScript in the index.html page until you *really* understand how Xanjax works. It's not necessary or desirable anyway unless you're doing something quite esoteric. (When you want to change the overall layout though, you may need to edit the file xanjax.css - see CSS Note below)

Name your valid XHTML pages as you please, except that they MUST have an .xml extension to work in Xanjax. If you want SEO and progressive enhancement, see paragraph after the next; don't bother with this in the beginning.

IMPORTANT: before you go further, validate each content page you authored using the W3C XHTML validation service. Don't just rely on your authoring program for valid XHTML output. Xanjax will *always* reject invalid XHTML. Be Warned!

Optional at the beginning. To ensure search engines will find and correctly index your content, you MUST link to each .xml file with a file system link (not web page link) of the same name but with a .html extension. This also ensures primary progressive enhancement - even text only browsers or mobile phones will be able to read your content. (Windows Server Users Note: Windows might not give you a way to create file system links to files; just make a copy with an extension of .html - this of course is inefficient, so Linux and Mac users will prefer to use symbolic links as suggested.)

Finally, edit or add links to the menu of the index.html page provided with Xanjax-Sitekit so that they point to your content pages. They MUST point to an .html file, *NOT* an .xml file (this works even if the .html file does not exist yet because Xanjax knows to look for the .xml version). Xanjax magic takes care of the rest. WARNING: If your favorite authoring software is one of those that interferes with the original HTML (there are many that do), you will need to use a plain text editor for this step. Changing the index page in any way except for the menu entries will probably crash Xanjax; until you *really* know what you're doing, leave everything else well alone.

CSS Note: If you want to create a different layout to the template provided, you can edit xanjax.css and iebugfix.css as required, so long as you don't alter anything in "html, body {}" or in "#xanjaxbody {}." In all places you must not change existing selector names, however you can change most properties. All changes such as colours, fonts and so on not affecting main menu or overall layout should be made in your own css file referenced in your authored pages as would normally be done. Use relative CSS units for layout such as percent or em so that any layout you create will fit proportionally into the main layout - avoid fixed units such as pixels, inches or centimetres.

JavaScript is supported in the head or body of your XHTML content page as normal.

In General: If you *really* have to do something which would screw up Xanjax, load it into an object instead of a div. Don't mess with this in the beginning, and only use objects as a last resort anyway, or for content they're really designed for such as Flash; most content can and should be inserted into a div which is far more flexible and will not break Xanjax browser navigation (if called as a normal XHTML content page this happens automatically).

How To Create Sub-Content Using "Contexts"

The first time you try to use contexts, use the Xanjax Sitekit. To get that going, see either the "quick start for the impatient howto," above, or for more understanding, the "prepare to use Xanjax howto."

Xanjax Contexts are very easy to use, but your first attempts may be enfuriating experiences due to syntax mistakes. If you haven't yet successfully added or changed menu items and content in Xanjax, go and do that first. Also, your mileage will vary unless you have solid XHTML/DOM/JSON knowledge. You will need to understand how Xanjax uses CSS if you want to insert contexts into a containing element other than the default and have them layout usefully. Once you have figured out Xanjax enough to create your own layout things will be much easier, so if you have trouble with contexts layout, go back and play with normal content and layout again.

The file root.ctx is the template Xanjax uses by default to insert contextual content into the browser. The sitekit version of root.ctx contains documentation on Xanjax Contexts keywords and structure, and it's necessary to read this before you begin. If you've never used JSON before, json.org is essential reading.

Once you've digested all the above information first try editing an existing context in root.ctx before attempting to write a new one from scratch. Correct JSON syntax is absolutely essential, and to help diagnose syntax problems you need a browser that provides detailed javascript error messages, and will keep the error console open. Don't waste your time with IE; even version 8 is just not up to the task. Tip: A missed delimiting comma will often be misinterpreted by error consoles as an orphaned enclosing curly brace.

Contexts of course are not limited to link-lists; in fact they can define any valid XHTML tags with any valid enclosed content including nested tags - but start with something simple that you can already see working. When you have some success with changing what's already there enough to create your own link list, try inserting the list into a different location, such as append:"menulist" which will add it to the main menu list. Tip: you won't be able to enclose your lists inside "auxpanel and "inpanel" if you're inserting them into "menulist" unless you also alter the CSS definitions for these elements. Tip: it's better to create contexts with your own tag ID's just as soon as you "get" how to do things, so that there are no interactions with existing Xanjax CSS definitions.

There's a Mini-Workshop in the downloadable Xanjax Sitekit, that should help you get going with Contexts.

When you have initial success, there's plenty more you can do. You could try creating a basic banner advertisement for example, or using two or more contexts simultaneously. Note that you can include a script tag containing Javascript into a Context, to create an animation for example. It's all possible. Once you get the idea, you're only limited by your imagination. When you come up with something really novel, please post us a link in the Xanjax Blog.