Saxite manual
Table of Contents
Saxite is an open-source, XSLT & XML based site framework that is compatible with AxKit.
You've already installed AxKit and have a basic understanding of what it does and how it works.
You know your way around a unix system and can handle basic apache configuration. (Note, someday I hope that won't be required as much.)
You know and understand XML.
You know and love XSLT (OK, not really required, but it's a plus :-)
one xml file per page, the filesystem is the database (for content), the site map builds itself, don't reinvent the wheel (e.g. use apache config for redirects, rewriting, etc., use javascript for async/interactive, use CSS for display, use XHTML for content), everything XSLT, everything static cached, leave log-in features for later, use namespaces where needed, separate saxite and user XSLT as clearly / cleanly as possible, simple but flexible, no need to "compile" the site ever, pipeline definition is embedded into the document (again, it builds itself),
You can install the shared files anywhere you like, as long as they can be accessed by apache. Just copy the files to the location you want, there is no additional installation step for the shared files.
Next create a link from your www root directory to the shared directory.
Let's say you installed the shared folder in
SHARED-DIR and your www directory is
/home/www/mysite. Then do this:
%cd /home/www/mysite%ln -s SHARED-DIR shared
Next if you want to use Docbook XML files,
you need to install Docbook-XSL on your system,
so that it can be accessed in this
(SHARED-DIR/xsl)
directory as the docbook directory.
Most systems have a docbook package which you can use.
Install that, and then create a symbolic link to it in the
SHARED-DIR/xsl directory like this:
%sudo apt-get install docbook-xsl%ln -s /installed/docbook/directory SHARED-DIR/xsl/docbook
(replace /installed/docbook/directory with e.g.
/usr/share/xml/docbook/stylesheet/nwalsh (on debian) or
/sw/share/xml/xsl/docbook-xsl (OS X/fink)
or whatever it got installed into.)
The idea is that after you're done, you can do this:
%more SHARED-DIR/xsl/docbook/xhtml/docbook.xsl
In your www site directory you should copy one of the example sites and customize it to your needs. These files have to be in the right places:
-
mysite/.htaccess— essential for making AxKit work properly -
mysite/dir.xml— this must be present and haveid="root" -
mysite/xsl/site.xsl— builds your HTML from the sax:pages
Because of a flaw in the current version of AxKit,
saxinclude doesn't notice when the included file has been changed.
So you have to "touch" (set as modified) the including file.
SHARED-DIR/bin/touchall
is a shell script that will help you do that.
Saxite operates on a principle that content, structure and style should be separate as much as possible. And it does pretty well towards that end. The content is formatted in XML, with as little structural and styling information as possible. You can write your content in any XML-based content language you like provided there's a module available to convert it to a sax:page & XHTML. Formats like DocBook XML go to great lengths to define just semantic information.
Structure comes into play in the XSLT transformation process. XSLT is the XSL Transformation language, or rather, the XML Stylesheet Language Transformations. Basically it's a language for transforming XML into XML, but what it's really good at is rearranging the content data into a new shape that you want. So, with XSLT you can easily move around content blocks, copy them, build tables of contents, process includes, and so on and so forth. You build the structure of your page at this stage in the pipeline
The final stage is styling for look and feel which is done with CSS. CSS is a pretty easy language to learn and there's plenty of information around about how to use it. The example is completely styled with CSS (no table layouts).
As a postscript, JavaScript is coming into play now as a way to create asynchronous interactivity on web platforms. While Saxite currently doesn't include any JS, it would / will fit right into the pipeline scheme as well. In fact, it might be an ideal way to make Saxite more interactive without sacrificing too much server-side performance and scalability.
Each page you make needs to be processed by some XSLT stylesheets before it can be delivered as HTML to the user. The technique that Saxite uses is xml-stylesheet directives that go at the top of the XML file, just after the XML declaration. It should look something like this.
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="/shared/xsl/sax.xsl"?>
<?xml-stylesheet type="text/xsl" href="/xsl/site.xsl"?>
This will cause AxKit to create a 3-stage pipeline. The first stage is just the source XML. The next stage is processed by sax.xsl, which converts the sax-page format into XHTML. The final stage is site.xsl, which adds your website structure and converts the XHTML into regular HTML.
Of course, if your original content is in another format, such as DocBook, you should add another stage(s) first, which would convert the original format into the sax-page dialect. In the case of DocBook you actually need two initial stages.
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="/shared/xsl/docbook.xsl" ?>
<?xml-stylesheet type="text/xsl" href="/shared/xsl/docbook2page.xsl" ?>
<?xml-stylesheet type="text/xsl" href="/shared/xsl/sax.xsl"?>
<?xml-stylesheet type="text/xsl" href="/xsl/site.xsl"?>
Although you can start off from the example site, you should customize
the look and feel to suit your needs.
You can customize for new content types by writing XSLT to transform
them into sax:pages.
You can customize the overall structure / layout of the site
by modifying the site.xsl XSLT stylesheet.
And, you can modify the look and feel and structure
using CSS (Cascading Style Sheets).
Normally it should not be necessary to modify sax.xsl and the other sax-whatever.xsl files.
Since we're assuming you already know how to write XSLT, you should have a look at site.xsl since this is where most of your modifications should go. By catching the incoming sax:page in the root template, you can then control the order in which components appear on the screen, such as the site's menu, submenus, sidebars and the main content.
Change anything in site.xsl to obtain the effects you want. Since it's the last stage in the pipeline, you can do anything here without messing up the internal mechanics of Saxite.
Saxite allows you to build sort of branching XSLT pipelines. So, you write XML files in any of the supported formats (currently XHTML, Docbook XML, and the locally-defined SaxBlog and Alexandra forms) as your content, and then process them through a series of XSLT stylesheets that are provided until they come out the end as fully built HTML pages with the look and feel of your site.
In addition you can add into any of your content sax:includes, which allows you to create branching pipelines, or like XSLT processing trees. This allows you to re-use your content and XSLT code very efficiently in multiple contexts.
Since it's based on AxKit, you get the benefit of really good caching and scalability. AxKit automatically caches all of the pages into a static cache when they are built/rebuilt, which means that your site can easily handle bursts of traffic.
Saxite is designed to be totally modular, so that you can add, remove features easily. For example, if you can extract just the weblog XSLT and integrate it into another XSLT toolchain. You can also add XSLT as long as they output saxite-compatible XML (i.e. with a sax:page root).
Saxite includes a "navi" system which provides two important features for users to navigate around the site: breadcrumbs and sub-menus.
The breadcrumbs are hierarchical (they follow the structure of the site, not the user's navigation path) and are constructed automatically from data that you write into the index.html pages in each subdirectory of your site.
Sub-menus are also generated from menus that you write into your
index.html files.
The submenus are formed from sax:menu
sections which can either be part of the meta-data for a page,
or part of the content.
Either way, they are used to automatically insert a "section menu"
on each page where Saxite can determine that there should be one.
(It's done by searching up through the parent directories until
it finds a submenu or hits the root).
The purpose of a Saxite page (a sax:page) is to contain all of the key content and metadata that you need for a single web page, including an "index" page that is the default for a given directory. So, it has to contain the HTML head and body data, and any metadata about the directory, such as the submenu that should be used in that directory, etc.
In addition, a Saxite page allows you to do some things that are useful for a website but that HTML doesn't have built-in, such as: inserting data loaded from another page, site, or whatever; and inserting menus for subsections of the site. Saxite provides a powerful "include" mechanism which is extensible, so that you can insert content for example from flickr, or from another weblog, in a very short/simple bit of markup.
The advantage of a customized markup for defining menus is that it allows Saxite to automatically build up a complete view of the site's layout and automatically insert a navigation system. Also, it allows you to use XSLT and CSS to give your navigation system a consistent look and feel.
Stylesheet declarations controls what XSLT filters each page, and in what order. They should be just below the xml declaration.
A regular sax:page has two declarations
(shown here with the xml declaration as well):
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="/shared/xsl/sax.xsl"?>
<?xml-stylesheet type="text/xsl" href="/xsl/site.xsl"?>
<sax:page> .... </sax:page>
AxKit has other ways to define what stylesheets filter each page, but this is the best way.
The namespace to use for elements of the saxite dialect is
http://simonwoodside.com/simon-axkit.
By convention the prefix is sax.
XHTML elements should use no namespace. Inside sax:head and sax:body you can intersperse XHTML with appropriate saxite elements (such as sax:include) as much as you want.
Every document must be in a sax:page format at least at two
stages in the pipeline, just before it hits sax.xsl and just after.
sax.xsl will then convert it from an
"unprocessed" sax:page into a "processed" sax:page.
The processed page is then handed off to your site.xsl
which must output XHTML.
The sax:dir section is optional. This is a meta-data section where you provide information that's used to build the breadcrumbs and the submenus for the page and for pages in the child directories.
sax:title is the title that is used in the breadcrumbs.
Usually it should be shorter than the full page title might be.
sax:path (optional) provides the full path to this page as you
want it to be used in the breadcrumb links.
If you leave it out the breadcrumb listing for this page will not be clickable.
sax:menu (optional) if you provide a sax:menu here,
it will be used as the submenu for this page and for child pages
as well if they don't define their own sax:menus.
NB: you can define the sax:menu in the content instead, and it will
act as both meta-data and content.
If you define it in the content, don't put it here.
The sax:head section is optional. It can contain one or more sax:title elements which are used to build the HTML title and possible h1 or whatever on the page. It can also contain any number of normal XHTML head elements, e.g. meta tags, special CSS includes, etc., which are copied into the HTML head in the output.
There must be a sax:body. It contains any kind of XHTML that's valid inside an HTML body element. It can also contain a number of other special saxite tags ... listed below.
The sax:include element is used to perform a server side include. You put in the URL and URL query parameters for some web-addressable content, and it will insert it inline into the page, in the place where the sax:include was. Most commonly you will use it to include content that's generated by Saxite, e.g., to include a list of the latest posts from the weblog. But you can also use it to include other content from other sites as well. The included content MUST be XML.
You can do recursive sax:includes, so that content that you sax:include can also have a sax:include in it, and they will all be fully expanded before they are delivered to the user.
sax:url contains the URL to load the content from.
It must be either a relative URL (just a path),
in which case it's loaded from the same server,
or a fully URL, with http:// and everything.
sax:query (optional) contains the URL parameters
for the include.
This can be useful when the URL you are calling has an API
that's manipulated using URL parameters. It's pretty common.
Saxite includes are extensible by adding special "classes" to the /shared/xsl/saxinc directory. Each one has it's own slightly different API, although they all use sax:url or sax:query or both.
For example a saxinc is included called feed.xsl
which allows you to include a feed such as RSS from some site.
In order to use it, you would use sax:include with
class="feed"
and Saxite will automatically process that include
with the special feed code.
You should only have one of these in any given page body.
The sax:menu is a standard way of creating a menu of options on a page, such as a list of sub-pages that you can go to. It creates a menu which is dual-purpose. First, it appears on the page in the content as UI, and second, it's re-used for the navi system for submenus and so on.
sax:item - put in any number of these.
The allowed children are img
and a, which are both the XHTML tags
of the same name and should be used like them.
You can leave out the img if you like, but the anchor/link
is required.
Also, there is an attribute shortname
on the sax:item, which is required if you want the menu item
to appear in the navi system.
You can also use documents in other dialects in Saxite sites.
In general, you should create a new XSLT stylesheet that processes
your own dialect first, and then produces XHTML wrapped in a
sax:page wrapper.
Here's an example.
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="/my/style/sheet.xsl" ?>
<?xml-stylesheet type="text/xsl" href="/shared/xsl/sax.xsl"?>
<?xml-stylesheet type="text/xsl" href="/xsl/site.xsl"?>
<mydialectroot>
<foo>
bar
</foo>
</mydialectroot>
XHTML is built-in to sax:page. You don't need to do anything to use XHTML (just wrap it in a sax:page/sax:body).
DocBook XML is also included. You can use DocBook by using two extra stylesheet declarations. The first one is just the regular docbook (to xhtml) stylesheet. The second one wraps that in a sax:page. Here's an example:
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="/shared/xsl/docbook.xsl" ?>
<?xml-stylesheet type="text/xsl" href="/shared/xsl/docbook2page.xsl" ?>
<?xml-stylesheet type="text/xsl" href="/shared/xsl/sax.xsl"?>
<?xml-stylesheet type="text/xsl" href="/xsl/site.xsl"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.docbook.org/xml/4.4/docbookx.dtd">
<book>
<bookinfo>
etc...