File Format Description

This page describes the input format. The tutorial describes the most important features in detail while this file describes all features in short form. If you know XML/XSL and the problems of maintaining a website you can start here ;-)

We write elements in XML as <element> and attributes of elements as [attribute]. If not otherwise stated an attribute is mandatory. Elements contain only other elements described here, no text or further elements are processed (unless they conflict with defined elements they won't produce problems but if you want to extend the format in a general way it might be better if you check with us so we don't do the same work or have two solutions for one problem or produce conflicts). And the file format is still in work.

The website file consists of two main parts:

• a <structure> part defining the sections and elements of the website
• a <layout> part which defines how the structure should be processed

Here are the descriptions of the elements and attributes:

<website>

(root element)

The root element has the following attributes:

• [sourceDir] - the directory where the sources can be found. This can be relative to the directory where the website is placed -- in the example it is the "content" subdirectory.
• [targetDir] - the directory where the results are placed. This can be relative to the directory where the website is placed -- you have to set it to something useful before you can compile the example yourself.
• [baseURL] - the URL which is used for the site. All links generated will be absolute links, using this URL as beginning. If you want to use a local version you can use a "file://" URL.
• [version] - the version of the format. Currently we will use the version number of the oldest program that supports all features used for this, but this might change later when the format gets more stable.

<structure>

(in <website>)

This part of the website file defines the input and output files, but not how they will be processed. The processing part is separated to make the management of the site easier. For example you can use different <structure>s with the same <layout>. Or you use different <layout>s with the same <structure> to test layouts or create different versions of your site for different browsers -- from DHTML to WML.

A <structure> has no attributes.

<section>

(in <structure>, <section> or <directory>)

A <section> can be used for two purposes: using/creating subdirectories and/or for splitting the navigation in separate parts. The attributes are:

• [name] - a name for the section which can be used when creating the navigation with XSL
• [sourceDir] (optional) - a subdirectory used for the input files. This directory is always relative to the directory of the next higher section -- you can't use absolute paths here.
• [targetDir] (optional) - a subdirectory used for the output files. This directory is always relative to the directory of the next higher section -- you can't use absolute paths here.
• [type] (optional) - the type can be used to define how the section should be processed, e.g. which images should be created for it.
• [id] (optional) - the id is not used by XWeb but it can be useful to find a specific section in the navigation tree later -- is it is used it has to be unique across all ids of sections.

The <structure> has typically one section, each section can have multiple subsections. XWeb can handle deeply nested structures but your stylesheets will get more complicated ;-)

<directory>

(in <structure>, <section> or <directory>)

Works the same as a section but has no name and is not used for navigation.

<entry>

(in <structure>, <section> or <directory>)

This is the element defining a page. It defines the name, input and output for a single page in the website. Attributes are:

• [name] - a name for the page which is used when creating the navigation with XSL and is also used to create file names for buttons etc.
• [title] (optional) - the title can be used for creating banners etc. See the [render] attribute on <imageStyle>.
• [sourceFile] - the file name of the input file. This is always relative to the directory of the next higher section -- you can't use absolute paths here although you could use relative paths (not recommonded).
• [targetFile] - the file name of the output file. This is always relative to the directory of the next higher section -- you can't use absolute paths here although you could use relative paths (not recommonded).
• [type] - the type of an entry is very important this it defines how the source file should be processed to get the target file. The type is an XML conformant string which is used later to define the generation process.
• [id] (optional) - the id is not used by XWeb but it can be useful to find a specific page in the navigation tree later -- is it is used it has to be unique across all ids of entries, homepages and files.

<homepage>

(in <structure>, <section>)

The homepage of the toplevel section is typically the homepage of the site (also it doesn't have to be this way). Homepages of subsections can be used to create pages that are shown when someone clicks on the name of the section. XWeb handles a homepage like an entry (and it has the same attributes) but the XSL for the navigation can treat homepages differently.

A section should have at most one homepage -- although XWeb doesn't check this yet.

<file>

(in <structure>, <section> or <directory>)

A file is like an entry, but without name and it doesn't create a navigation entry. This can be used for files that should be processed but shouldn't appear in the website navigation.

<layout>

(in <website>)

This part of the website file defines how the website should be processed. It has no attributes.

<documentStyle>

(in <layout>)

This is one of the most important aspects of the file: here we tell XWeb how a page on the website should be processed, i.e. how a source file should be turned into an output file.

You can use multiple layouts, they have to use different [outputDir] attributes which denote the target directory for the whole generated site with this layout. If you use the multi-layout feature you probably want to add an <index> element above the structure which will be processed as a file (with the same attributes) but above all layout directories.

A <documentStyle> has exactly one of these childs: <xsl>, <copy> or <programCall> plus a free number of <image> elements -- from zero to whatever your system can handle.

The only attribute [type] is used to identify the pages that should use this processing information. For each [type] you gave for the pages (<entry>, <homepage> and <file>) you have to give exactly one <documentStyle> definition with the same [type] attribute but multiple pages can share a type.

The four base types are:

• <xsl> - the sourceFile will be processed using the internal XSL processor (Saxon). Possible attributes are [stylesheet] to define an XSL stylesheet which should be used (if not given the XML files have to have an internal stylesheet PI) and [navigationElement]. If the latter is given, XWeb will put a copy of the structure with some additional information into the first element with the given name (see the process documentation). Each <xsl> element can have <parameter> childs to define parameters for the stylesheet, see below for details.
  If an <xsl> element contains another <xsl> element, an XSLT chain will be set up, its stylesheet will be applied to the output of the inner <xsl> element. This nesting can be done multiple times.
• <copy> - the file is just copied from the source to the target position.
• <programCall> - an external program is called. An example of usage would be calling pdflatex to create PDF files out of TeX documents. The command is given as [command] attribute, %s and %t represent the source and targer files respectively.
• <svg> - the file is processed as SVG file. The extension of the target file defines the output format, valid values are ".jpg" or ".jpeg" for JPG format or ".png" for PNG format.

The most common version is of course the XSL processing but sometimes it might be useful to copy or create other files, e.g. for downloads.

If one or more <image>s are given for this document style, the corresponding images will be created. The <image> elements have an attribute [type] which is used to refer to an <imageStyle> with the same [type].

<imageGroup> can be used to get an additional abstraction level, e.g. to group all buttons and other images that are created for all pages regardless of type. The attribute [name] is used to identify the group.

parameter

(in <xsl>)

The two mandatory attributes [name] and [value] define a parameter for the stylesheet that can be used with <xsl:param>. Multiple parameters are allowed per stylesheet.

<sectionStyle>

(in <layout>)

A section style has a similar function for a section as a document style for a document: it defines how a section should be processed. Currently only the <image> element is supported to create buttons and banners for sections.

<imageStyle>

(in <layout>)

An <imageStyle> defines how an image should be rendered using the ImageRenderer class or by processing SVG code. It has either a list of attributes and elements which map to the options in the ImageRenderer class or it contains SVG code that is rendered using Batik.

Attributes are:

• [width], [height] - the size of the image
• [fileNamePattern] - this pattern is used to generate a file name for the images. It has to contain a percent symbol followed by a lowercase n ("%n") to indicate a place where the name of the page will be put. The name will be consist out of Latin characters, digits and underscores. Everything else will be mapped to an underscore. If a name clash should occur the last file will overwrite the others (sorry no evasive maneuvring yet). The file name pattern also defines the type of images created, e.g. if you use the pattern "button_%n.png" you will get PNG images.
• [type] - the identifier used to refer to this kind of images.
• [render] (optional) - if this is set to "title" XWeb will check if an entry has a [title] attribute and if yes, it will use the title for rendering this image instead. This is useful for creating banners with more text than the buttons use.

The Simple Renderer

If you use the simple renderer you have only limited features but since one of them is adding an image file into the background it might be enough for your needs. If you take this approach you can add the following elements into an <imageStyle>.

<background>

(in <image>)

This defines the background of the image. Attributes are:

• [color] (optional) - if given, the background will be filled with the color first. The color has to be given in the typical HTML format: a hash, then 6 hexadecimal digits, pairwise for the red, green and blue aspect. E.g. a medium blue will be given as "#000080". Color names are not supported.
• [imageURL] (optional) - if given, the image refered will be used as background. This will happen after the color was filled -- if the input image has an alpha channel or doesn't fill the full ouput image you can e.g. create buttons with different colors by putting the same image on top of different fillings.
• [imageMode] (optional) - has to be one of the values "origin", "centered" or "scaled". "centered" is the default and puts the input image in the middle of the output image. "origin" put the input in the top left corner of the output while "scaled" scales the input image to match the output size. "centered" and "origin" might result in cropping.

You can give background without [color] or [imageURL] but it will be ignored as will be an [imageMode] without [imageURL].

<text>

(in <image>)

The only attribute [color] defines the color of the text that should be rendered onto the background. It uses the HTML format as described for the <background> tag.

All further information on the text is split into the child elements of <text>.

<position>

(in <text>)

Defines the position of the text in the image. Attributes are:

• [hAlign] (optional) - the horizontal alignment is one of "left", "center" and "right". It defaults to "center".
• [vAlign] (optional) - the vertical alignment is one of "top", "center" and "bottom". It defaults to "center".
• [offsetX] (optional) - this value is added to the horizontal position of the text after the position for the correct alignment was calculated. Useful e.g. if your background image is not centered.
• [offsetY] (optional) - this value is added to the vertical position of the text after the position for the correct alignment was calculated. Useful e.g. if your background image is not centered.

<font>

(in <text>)

Defines the font to use. Available fonts are system dependend but since XWeb renders images you can use any font available on the system where the website is created. Attributes are:

• [name] (optional) - the name of a font available in the rendering system.
• [size] (optional) - the size in points, defaults to 24 (TODO: 14 should be much better as default (or drop default))
• [bold] (optional) - if set to "true" the bold attribute will be set.
• [italic] (optional) - if set to "true" the italic attribute will be set.

If the element or the name attribute are not given, no text will be rendered. This is useful if you want to use special images for e.g. a homepage since the image URL will be available in the navigation information in the same manner as the other images with rendered text.

<shadow>

(in <text>)

Has the attributes [color], [offsetX] and [offsetY] to render the same text with a small offset in a different color below the final text to produce shadow effects. Offset is measured from final text position.

SVG Rendering

Instead of using the features above you can put SVG into the <imageStyle>. The only element allowed when going this way is an <svg> that contains the SVG elements and attributes as it would be used in a standalone SVG file. The [width] and [height] attributes can only be given if they are not used on <imageStyle> -- we recommend using them on the <imageStyle> (maybe this will be enforced later).

An additional attribute [xwebid] allows you to put the page or section name into your SVG code. If this attribute is given, XWeb will scan the SVG code for a <text> element with an [id] attribute matching this [xwebid]. If this is found the text in this element will be replaced with the name of the current page or section. This way the name can be placed in any text position in the SVG picture, allowing a huge number of effects to be used.

<imageGroup>

(in <structure>)

An <imageGroup> contains a number of <image> elements. It is used to group images to a logical unit that can be refered in a document or section type definition. The [name] attribute is used as identifier.