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:
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:
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?
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:
- On each page, provide a synopsis. E.g. the azalea page might look like this:
<xml>
<include src="settings/generic.xml"/>
<synopsis name="Azalea" description="A rich, yellow flower with a bloomy smell" keywords="azalea"/>
<title>
Flower Power: The Azalea</title>
- Then on the flowers/index.xml page, use the locallink tag like this:
<content>
<h2>
An overview of our flowers</h2>
</content>
- There's no step three. Generate the site and Corbon will look for all files in the directory, and provide links to them containing their name and description.
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.
- directory: This tag shows a listing of underlying subdirectories. For each one, it sees if the directory contains an "index.xml", and if it does, it uses the synopsis of that page to display a link.
- nextpage and
prevpage:
These show the next and previous page. The files are ordered alphabetically,
so if you use the
<nextpage>
tag in "azalea.xml", it will link to "orchid.xml". This is usefull for step-by-step guides: prefix each file with a number, e.g. "01_welcome.xml", "02_about.xml", ... . - seealso: Uses the keywords on this page to find pages containing the same keywords and links to them.
- uplink: Provide a link to the parent page. If used on "azalea.xml", it will link to the "index.xml" file in the flowers directory. If used on that page, it will link to the "index.xml" file in the root directory of the site.
- filelist: Provide a listing of files in the current directory for download. Use it in a directory full of images or sound files, and Corbon will generate links to them containing their size.
- keywordindex: This tag is probably used only one time on the site to provide links to all pages on the site, ordered by their keywords. It works like a book index. It's also useful on your custom "file-not-found" page, providing a sitemap for users that mistyped an URL.
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.