xidebar Web Site Generator
This web site is generated with xidebar. This is a very simple
tool which I built to take some of the drudgery out of
maintaining a consistent site. In particular, in order
to make web sites useful sources of information, I
need to be able to update them quickly.
The basic xidebar premise is as follows:
- HTML is easy.
- Most sites are the same format.
- Maintaining navigation links and consistent content across
any site is a pain in the arse.
If you don't agree with that, this tool isn't for you.
The xidebar solution is very simple and is based on my
xidebar::htmlgen module. It works as follows:
Note (16/03/2005) this has nothing to do with the Python
HTMLgen module which I wasn't aware of until today. I'll
need to rename this module I suppose. =(
template.html : the basis for all pages in the site.
htmlgen.xml : the entire site content.
- directories containing files referenced from the HTML
content, such as images, style sheets, and so on.
xidebar.pl : perl program which generates the site.
So, basically you set up a template.html
which has the general look of the site. You define the
content in htmlgen.xml in terms of page
definitions with content. All HTML content is defined
in CDATA sections so that straight HTML is used for
content definition. Then, executing
xidebar.pl produces the web site in the
output directory.
Advantages
An immediate advantage of this approach is that site
re-designs are trivial - simply altering template.html
re-designs the whole site. The standard 'modern' way
to do this with style sheets, but once you take CSS
beyond simple look and style, I find this
astonishingly fiddly. So, I do layout in HTML (easy)
and style in CSS (easy) and use xidebar to update the
whole site.
Another great advantage is that adding a page definition in
htmlgen.xml results in a complete site with the new page
incorporated in the navigation sidebar.
This means that adding a new pages is easy and
maintaining consistent site look and content is easy.
Job done! Well, obviously there's room for improvement
- in particular the XML could do with a GUI editor for
less technically confident people to use.
Quick usage guide
First get the code.
This contains a sample setup (this site minus big
graphics and presentations etc) which you can use right
away. You'll need perl installed - this is free and
available here.
At the moment you need to keep all the files under one
directory (I will fix this one day). So, unzip into
the directory where you want to do your work. Now, run
xidebar.pl and voila! You have a web site under
output/.
- To alter the content of the generated web site, work
on
htmlgen.xml.
- To alter the appearance of the generated web site,
work on
template.html.
After running xidebar.pl, you have a new site
generated under output/. That's it
really.
New Documentation 20060503
Here's some more complete documentation, hopefully of
use to support use of this tool.
Xidebar by allan@eh42.com
Xidebar is a website generator which takes as input a template html page with a
few placeholders, which are simply replaced to produce web pages. The name comes
from XML and Sidebar, the 2 central elements of xidebar. The whole site is
written as one big XML document (optionally you can split out sections but
that's rarely used to date) and the pages are linked with a sidebar customised
per page.
NOTE: To get started just edit the htmlgen.xml file. To alter the appearance,
edit template.html and css/newspaper.css, and obviously the little images that
decorate the site.
To take my site, eh42.com, as a simple example, we have a Home page and 2 main
sections: 'Bicycle Stuff' and 'Computer Stuff'. This requires a sidebar with 3
items and many sub-items. You can see that on the site. To define the sidebar in
XML, we use the following XML, which should be self-explanatory.
There are only 3 elements: <sidebar_menu>, which is the top-level element
defining the sidebar; <item>, which is a visible link, and
<submenu>, which declares a submenu containing further <item>
elements. A <submenu> must be inside an <item>.
<sidebar_menu>
<item tag="index"/>
<item tag="computerstuff">
<submenu always_visible="false" sort="NAME">
<item tag="query_hack"/>
<item tag="mp3_chunk"/>
<item tag="doughnut"/>
<item tag="xidebar"/>
</submenu>
</item>
<item tag="bicyclestuff">
<submenu always_visible="false">
<item tag="mybikes">
<submenu always_visible="false">
<item tag="redbike"/>
<item tag="bluebike"/>
<item tag="commencale"/>
<item tag="greenbike"/>
<item tag="whitebike"/>
<item tag="gail"/>
<item tag="cat"/>
</submenu>
</item>
<item tag="servicingthumbies"/> <!-- -->
<item tag="stupidbike"/>
<item tag="sleepless"/>
</submenu>
</item>
<item tag="perfectblossom"/>
<item tag="sitemap"/>
</sidebar_menu>
The tag attributes are defined in <page> definitions. Here's one. The tag
is used for the page name, with default suffix .html (so this produces
'index.html'). The <name> is used for the sidebar link (so 'Home' links to
'index.html') and the <title> is used for the page title. The
<content> is defined as CDATA so that it is completely un-interpreted by
the XML parser and is dumped verbatim into the page content.
<page tag="index">
<name>Home</name>
<title>&sitetitle;</title>
<content>
<![CDATA[
<h2>
Welcome to Allan Kelly's site
</h2>
<p class='first'>
This is Allan Kelly's web site. This is where I'll put my
work, and record some other things I get up to - like cycling.
I write utility software that generally does useful little things -
you can use anything you find here freely. Please let me know
if you find it useful.
</p>
]]>
</content>
</page>
So, that's that. There are other parts, but to get started just edit the
htmlgen.xml file. To alter the appearance, edit template.html and
css/xidebar.css.
There are other elements in htmlgen.xml, namely <build_targets>,
<html_resources>, <placeholders>. Also there are some niche features
like <placeholder type="gallery"> for auto-generating photo-galleries,
<page><suffix>php</suffix></page> for changing the
suffix of generated pages so you can for example embed PHP or whatever in your
pages, and the ability to include other xml files with <content
include="anotherfile.xml"/>.
XML Schema
The schema is pretty self-evident from the XML, but
here it is anyway.
|
|
|
