Getting started with Corbon: a tutorial

These pages describe a use-case for Corbon. Throughout this tutorial, we will create a fictuous company, called Flower Power, that needs a web-site to present itself. We will show some of the common problems inherent in the creation of websites, and how Corbon solves them.

Flower Power: Bringing a Touch of Color

Flower Power sells flowsers. Not online just yet, but it would like a catalog of its flowers. Also, it would like some general information. The one and only employee of Flower Power drew his own site map:

Hand-drawn site map

The bulk of the data will be in the "flowers" directory. The other three pages contain regular data.

Beginning a site

First things first: in Corbon, the file structure is very important. It is as much part of the data of your site as the files themselves, so building a file structure that makes sense is the first thing you should do.

A general idea in Corbon is that you shouldn't create too much directories. For example, since the roadmap page is just one page, you can put it under the root directory. All flowers belong together, so they should be under the "flowers" directory.

A directory structure for Flower Power might look like this:

Hand-drawn directory structure

Note that each directory should contain an "index.xml" file. This is the root file of that directory. When linking to http://www.flowerpower.com/flowers/, your webserver will serve up this file. (By then, it'll be called index.html). You can create the files and directories already. Our root directory is called "source": this is the standard name for XML sources in Corbon, altough it could be named anything you want.

Content of the .XML files

In designing Corbon, we wanted the source XML files to be as minimal as possible, while providing a lot of flexbility. This is how a minimal XML file might look like:

<xml>
	<include src="settings/generic.xml"/>
	<synopsis name="Home" description="Home Page of Flower Power"/>
	<title>Flower Power: Welcome!</title>
	
	<content>
	<h1>Welcome to Flower Power!<h1>
	<p>Flower Power has every flower you want.<p>
	</content>
</xml>

We'll go over the file line-by-line:

<xml>

Starts the Corbon XML page.

<include src="settings/generic.xml"/>

The <include> is used in almost any page. An include file generally contains common options and HTML code for every page in the site. (such as headers, footers, stylesheets,...) We'll discuss the content of such a settings file later on.

<synopsis  name="Home" description="Home Page of Flower Power"/>

Contains some extra information about this page, such as its name, description and some keywords. Corbon can use this information to generate a list of all files in a directory.

<title>Flower Power: Welcome!</title>

The title maps to the standard XHTML <title> tag. Corbon makes sure that the title will appear inside of the <head> tag, as required by XHTML.

<content>

Start of the content of the page. Corbon will translate this to a <div id="content"> tag, that can then be styled using CSS.

<h1>Welcome to Flower Power!<h1>
<p>Flower Power has every flower you want.<p>

You can use any XHTML tag you want in Corbon. These are copied over in the resulting XHTML. However, Corbon does something strange with links (such as <img src=""> and <img>a href=""</img>). More on that later.

<content>
</xml>

End the content and close the page. Additional footers can be set using an optional <footer> tag, or by defining them in an included file.

Settings files

We'll have to dissapoint you: there is no such thing as a settings file. Corbon doesn't need to set any arcane options, and everything you can do in an included file, you can do in a regular file.

Having said that, some tags just make more sense in a file that is included than on a regular page. Because you include a certain file on every page, you can use this included file to specify things such as a common header and footer, the stylesheet used, etc.

Now that you know that there are no settings files, let's go over one. We put all settings files in a directory called "settings", but you can put them wherever you like. Here's what our settings/generic.xml looks like:

<xml>
	<synopsis generate="0" />
	<link href="default.css" rel="stylesheet" type="text/css" />
	
	<div id="header">
	<img src="g/logo.png" alt="The Flower Power Logo" />
	</div>
	
	<div id="nav">
	<ul>
		<li><a href="index.html">Home</a></li>
		<li><a href="about.html">About Us</a></li>
		<li><a href="flowers/index.html">Flowers</a></li>
		<li><a href="roadmap.html">Roadmap</a></li>
		<li><a href="contact.html">Contact Us</a></li>
	</ul>
	</div>	

	<footer>
		<p class="footer">© 2003 Flower Power. All Rights Reserved.</p>
	</footer>
</xml>

Yet again, we're going for minimal here. The <link> tag will be put in the header of every file that includes this one. The header and nav divs are contained in the body of those files. The synopsis here defines that this page, being a settings file, should not be generated.

The footer tag requires some attention. Normally, you include a page at the top of another one, meaning that all content of the included page appear before the basic content. This makes it ideal for defining headers and navigational elements. By using the <footer>, you can also make content appear after all other content. You can use any tag inside of the footer tag, both XHTML tags as well as special Corbon tags.

Relative linking

One very important issue that we're bringing up early is that of relative linking. Every link in Corbon, whether it's for another page or an image, uses a relative link that starts from the root. So it doesn't matter what directory you start from, you always must link from the root.

Let's give an example: let's say you have a file in the directory projects and you're pointing to an image in the projects/images folder. The code for this is:

<img src="projects/images/image.png" alt="An Image" />

So you can't reference to the image by only using the "images" folder, you have to use the full path starting from the root. Note that this also goes for links to other pages using the <a href=""> tag.

This is very important for include files to work: because included files can reference elements from anywhere in the site, they must be able to do so from anywhere in the site using the same link.

How to build the site

So now you have a directory full of XML pages. How do you make a site out of this? Well, Corbon works best with a build script. This is a fancy name for a file containing two lines of text. Here's what the build script for the documentation looks like:

<from corbon import buildSite
buildSite('docsource', 'documentation')>

Because this is python source code, you should save your build script with the extension ".py". Then, assuming you've installed Corbon, you can run the script by typing

python build.py

on the command line. In this example, Corbon would take the sources from the "docsource" directory and create a directory "documentation" (if it doesn't exist already) with all .HTML files, overwriting the existing ones.

So, that's it. That's all you need to know to make a basic Corbon site that generates a XHTML-compliant, CSS-styled site. However, that's also the very least that you can do with Corbon. There's More™.

Directory Mangement

Note that we're still trying to put a flower catalog online. One of the general problems of such catalogs, and one that Corbon tries to solve, is keeping all cross-references up-to-date. Because we might regularly add or remove a certain flower from our catalog, keeping our links updated makes sure our visitors never see the dreaded 404 error.

Take the flowers directory, for example. Wouldn't it be nice if we could just give a listing of all flower pages in that directory, like so?

Azalea: A rich, yellow flower with a bloomy smell
Orchid: A gentle flower known for its beautifull blossom
Rose: The mother of all romantic flowers
Sunflower: A large yellow flower, like Van Gogh used to love

Well, you can generate such a listing by using one tag: the <locallink> tag. Here's how it works:

That's the <locallink> tag. For more information, read the reference documentation on <locallink>.

Now that you've seen one tag, you can understand them all. We'll give a quick overview of other tags in Corbon, with links to the reference documentation containing help and examples.

Corbon options

Corbon has some build settings that can be changed on a site-by-site basis. They're things that we believe you, as a user, should be able to have control over. Read the build settings reference to find out what they are.