Telling XWeb what to do

Setting up a project

XWeb uses a central makefile which contains all information needed to compile the website. This file is typically called website.xweb and is stored at the toplevel of the directory structure used for creating the site. A typical approach is to have a directory for a site and then put the makefile plus the following directories in it:

content

Here we store all input files which contain the content of the site, i.e. all XHTML or XML input for XWeb.

layout

In here we put all XSLT stylesheets used for rendering the pages plus maybe additional files needed for this, like a header or footer definition.

output

This is the place where we tell XWeb to put the results. The directory will be created automatically if needed.

All these directories are optional, you will see later in this manual where they are set. For the rest of the manual we will assume that this structure is used, so the first step in creating your own XWeb site should be creating this directory structure for your site. We will refer to this directory as your project directory.

The next step is to create a new file called website.xweb in your project directory and to open it in your favored XML editor. If you don't have a favored XML editor, use a normal text editor. You can find an XML schema for this file in the XWeb distribution in the specs directory, if you have a validating XML editor this might be quite useful, just base the new file on this schema. The manual will not assume that you use an XML editor, so using a normal text editor should be fine.

Writing the makefile

Any XML file has to start with this line:

  <?xml version="1.0" encoding="UTF-8"?>

The version has to be 1.0, the encoding can differ with the language you use, but UTF-8 is usually a good try since it is a superset of ASCII. If you want to use other Unicode encodings change this line to give the correct encoding, another typical encoding for western languages is "ISO-8859-1" for the Latin1 character set.

The XWeb part of the file starts with an element called >website< and giving three basic positions: the directory where to find the input, the one where to put the output and the target location for the site. The directories can be either relative to the position of the file or they can be absolute directories somewhere in your file system. The target location is needed to create the links in the navigation, which will be always absolute links. Here is a typical website declaration:

  <website baseURL="http://my.domain.org" sourceDir="content" targetDir="output">

The only thing you have to change is the baseURL attribute, which should point to the location where the site will be when it is uploaded. If you don't have the webspace yet it doesn't matter, you can change it later and we will use the preview mode in this manual where the links will be generated to point to the local files. The other two attributes match the project structure discussed above, you can change them if you want to use another structure.

Defining the structure

The first part in the makefile defines the structure of the website. This part has two purposes: it gives XWeb the information which files to process and it is used to generate the navigation. To serve these two purposes all elements in this <structure> part have two groups of attributes: some for defining how the navigation should look like and some for defining how they are processed.

Here is an example for a structure definition:

  <structure>
    <section name="My Project" sourceDir="projectDescription" targetDir="project">
      <entry name="Welcome" sourceFile="welcome.xhtml" 
                        targetFile="../index.html" type="xhtml"/>
      <entry name="Features" sourceFile="features.xhtml"
                        targetFile="features.html" type="xhtml"/>
      <entry name="Download" sourceFile="download.xhtml" 
                        targetFile="download.html" type="xhtml"/>
    </section>
    <section name="People" sourceDir="people" targetDir="people">
      <entry name="Myself" sourceFile="me.xhtml" 
                        targetFile="me.html" type="xhtml"/>
      <entry name="My Friend" sourceFile="jimmy.xhtml" 
                        targetFile="jimmy.html" type="xhtml"/>
    </section>
  </structure>

Here we define two sections, one that describes a project and the other the people involved. For each section we give some subdirectories in the input and output directories, e.g. XWeb will search the first files in the subdirectory " projectDescription" below the subdirectory "content" in your project directory and put them in a directory with the name "project" in the "output" directory. Often these two names will be the same as for the second section and you can leave the attribute value empty or skip the attribute if you don't want to use subdirectories for a section.

A page in the output is represented by an <entry> element. Each of these entries points to an input file given by the sourceFile attribute and will create the file given by the targetFile attribute, e.g. the first <entry> tells XWeb to look for the file content\projectFiles\welcome.xhtml in your project directory and to create the output file as output\project\../index.html, which is resolved to output\index.html. Using the two dots to go up one directory is not nice, but the easiest way to put all output in subdirectories exept for the starting page. Since XWeb uses absolute links in the navigation this will always work and the mixture of slashes and backslashes will be interpreted correctly, too.

The other two attributes define how the file is handled. The name tells XWeb how to call the entry in the navigation while the type is used later in the layout section to define how the output file is created, we will see this below. Sections can have a type, too -- this is useful if you want XWeb to render images for a section as it will be shown in the section on images in this manual.

There are some attributes and elements not used in this example: both sections and entries can have a title which can be used to render banners etc., a typical example is the "Curriculum Vitae" which looks nice in a banner but not that nice as a button in the navigation. Here you can set the name to "CV" while using the long version as title. If the title is not given, the name will always be used as alternative. Additionally you can attach an id to each of them -- if you do so the ids have to be unique across sections and entries (but a section and an entry can have the same id) and they can be used to refer to entries, e.g. for internal links.

Sections and entries have their invisible counterparts in the <directory> and <file> elements. They do basically the same but do not appear in the navigation. Therefore they don't have a name or title attribute, all other attributes are the same.

XWeb allows putting entries directly into the <structure> element and nesting sections into other sections, but the stylesheet we will use expects exactly this depth, so we will not use this feature. Read the section on advanced XWeb technique for more information on writing your own stylesheets to find out more on writing stylesheets for other structures.

How should it look like?

The way the output will look like is determined by the second major part in the makefile: the layout section. The layout section defines how to process the files and which images to create for the navigation and how they should be created. Most of the aspects of creating a layout will be discussed in the other sections of the manual, we will just start with the most simple not trivial example to get a start.

For creating the website we will use the generic XSLT stylesheet from the XWeb distribution, which can be found in the templates directory in the distribution. Copy the file generic.xslt into the layout directory of your project and add the following lines to your makefile:

  <layout>
    <documentStyle type="xhtml">
      <xsl stylesheet="layout/generic.xsl" navigationElement="html">
      </xsl>
    </documentStyle>
  </layout>

This tells XWeb that for each entry and file with the type "xhtml" the stylesheet we just copied should be used. The location of the stylesheet is again relative to the position of the makefile and matches the structure discussed at the beginning -- change it if you should not use this structure. The second attribute navigationElement on the <xsl> element tells XWeb to add the information about the structure into the XML file before applying the stylesheet. If this attribute is missing, the stylesheet will not be able to create the navigation.

You can give multiple layouts in one makefile, e.g. to create versions for different browsers and files can not only be processed with XSLT but also by copying them, by rendering them from SVG into bitmap files or by calling other programs via command line. And you can create images for buttons, banners and whatever you want -- all this will be discussed in the following sections, in this simple example we will just finish the makefile with the final line:

  </website>

Then save it. Now create the two directories projectDescription and people in the content directory and add the XHTML files given in the makefile. If you want to use HTML editors which don't support XHTML output you can run Tidy to turn your files into XHTML.

Now you are ready to create your first XWeb site. Change into your project directory and run the script for the website processor in preview mode like this:

wp -preview website.xweb

If you didn't add the bin directory for XWeb into your path, you have to add the path to the script in front of this command. The "-preview" option tells XWeb not to use the baseURL given on the <website> element, but to use local links instead. Once you want to publish the results you have to run XWeb again without this option.

Finished! Check the output directory if you can find your site there. Once you got your first results you can start adding or removing sections and entries in the makefile. Whenever you run XWeb again the navigation on all pages will be updated to reflect the new structure. You can use any XHTML documents as entries, although it is best to not use too much layout in the input files since we will add layout for the whole site in the next section of the manual. The input files for this manual don't contain any layout information at all, the whole look is added with CSS and the parameters of the generic stylesheet.