(preload) (preload)

General information

Namespaces

site.xml (as well as most of PySSE's data files) usually include two namespaces: the standard XHTML namespace (http://www.w3.org/1999/xhtml) as well as PySSE's own namespace, http://www.ebenoit.info/data. This namespace will be referred to as ws: in this document. For example, the site configuration file may look somewhat like this:

<?xml version="1.0" encoding="UTF-8"?>
<ws:data
    xmlns="http://www.w3.org/1999/xhtml"
    xmlns:ws="http://www.ebenoit.info/data">

	...

</ws:data>

In addition, templates may use the PySSE extension functions through the http://www.ebenoit.info/ext namespace. This is however useless in the site.xml file.

General structure

The site configuration file usually begins with general configuration directives. It then declares the site's map. Finally, it configures the site for each available language.

Languages

By default, two languages may be supported: English (en) and French (fr). If you need to support additional languages, you will need to write string translations for them.

site.xml reference

General configuration directives

ws:breadcrumb

This tag configures the breadcrumb block's display. It uses the separator attribute to specify the string with which the elements of the breadcrumb should be separated.

<ws:breadcrumb separator="»" />

ws:data-paths

This tag configures the various paths (relative to the web site's root) that may be used in the pages of the site. There are 3 different types of paths: js for JavaScript files, css for cascading style sheets and img for images.

The paths themselves are configured through a sequence of ws:path-to tags located inside the ws:data-paths tag. Each of these tags has an attribute named type which specifies the type; the tag itself contains the path.

If there is no ws:path-to tag for a given type, the name of the type will be used as the relative path.

<ws:data-paths>
	<ws:path-to type="css">styles</ws:path-to>
	<ws:path-to type="js">scripts</ws:path-to>
	<ws:path-to type="img">images</ws:path-to>
</ws:data-paths>

ws:feeds

This tag configures the RSS feeds to display in the feeds block. It contains a sequence of ws:feed tags. These tags must have a from attribute, which contains the URL from which the feed is to be fetched. In addition, if the hide-links attribute is present, links to the feed's items will not be displayed, which is useful when displaying feeds from private sites through a script acting as proxy.

Note: at the time of this writing, only RSS 2 feeds are supported.

<ws:feeds>
	<ws:feed from="http://wordpress.org/development/feed/" />
</ws:feeds>

ws:page-data

If present, this tag contains a path, relative to the site data directory, under which page data is stored. If the tag is not present, the pages will be looked for from the root of the data directory.

<ws:page-data>pages</ws:page-data>

ws:side-bar

This tag defines the elements to display in the side bar. If the block is omitted, the side bar will not be generated.

The tag must contain a sequence of ws:block> tags with a "source" attribute which determines the type of block to display. The following sources are available:

<ws:side-bar>
	<ws:block source="menu" />
	<ws:block source="site-history" />
</ws:side-bar>

Site map

Each page on a PySSE web site has an unique identifier; this identifier must start with an alphabetic character, and may contain alphabetic or numeric characters as well as dashes. It may refer to another page as its parent, which will affect the menu and breadcrumb generators.

The site map, defined in the ws:sitemap tag, defines the various pages of the site and their relation to each other through a sequence of ws:page tags. The ws:sitemap tag may also have a home attribute, which specifies the site's home page's identifier.

Each ws:page tag must have an id attribute, defining the page's identifier. In addition, the parent attribute, if present, will contain the page's parent's identifier. Finally, it is also possible to specify an author for a page, if that author is different of the site's main author. This can be accomplished by using the author attribute.

Two other attributes may be used for ws:page ; these attributes only affect the menu generator. First, hidden, if present and containing "1", will prevent the menu generator from showing an entry for this page. The auto-menu attribute may contain the name of a HTML class; the menu generator will examine the page's data and, if it finds tags possessing both the specified class and an identifier, will create menu entries linking to these locations.

<ws:sitemap home="main">
	<ws:page               id="main" />
	<ws:page parent="main" id="sub-page-1" />
	<ws:page parent="main" id="sub-page-2" />
	<ws:page               id="auto-page" auto-menu="menu-class" />
	<ws:page               id="hidden-page" hidden="1" />
</ws:sitemap>

While ws:page tags are usually empty, they may contain metadata and inclusion tags.

Language-specific configuration

A site's language-specific data is defined by ws:contents tags at the root of the site's configuration file. These tags use the lang attribute to specify the language they represent. Each language must only be present once, but it is possible to configure as many languages as required.

<ws:contents lang="en">
	...
</ws:contents>
<ws:contents lang="fr">
	...
</ws:contents>

The tags listed below are used in the ws:contents blocks.

ws:history

This tag either contains the history of changes or indicates the file that contains this history (if it has a datafile attribute). See the description of the history file below for more details about the contents of either the tag or the external file.

<ws:history datafile="history/en.xml" />

ws:langname

This tag contains the complete name of the language. It is used to generate the language selector.

<ws:langname>English</ws:langname>

ws:pages

This tag contains a sequence of ws:page tags, which define language-specific parameters and contents for pages. These tags must have unique identifiers corresponding to the names defined in the site map as their id attribute. In addition, they must provide a title attribute which contains the title of the page in the current language.

ws:page tags also define the contents of a page, either directly inside the data or by specifying a datafile attribute, pointing to a file to be used as the source for the page's contents. The file name is relative to the directory defined by ws:page-data and must not include an extension (".xml" will always be appended). The possible contents of a page include standard XHTML, as well as PySSE HTML generation tags. External contents are described in the external pages section.

Finally, if the page is defined as an external page, the tags may contain metadata and inclusion tags.

<ws:pages>
	<ws:page id="main" title="Home" datafile="home" />
	<ws:page id="other-page" title="Other page">
		<p>This page is directly in the configuration file.</p>
	</ws:page>
</ws:pages>

ws:strings

This tag either contains the translations of the various strings used by PySSE's XSL code or indicates a file that contains string definitions (if it has a datafile attribute). See the description of the translations file below for more details about the contents of either the tag or the external file.

Note: if a translation is present in both the external file and the configuration file, the one in the configuration file will take precedence. This makes it easier to override translations provided by PySSE with site-specific strings.

<ws:strings datafile="strings/en.xml">
	<ws:string id="menu">Main menu</ws:strings>
</ws:strings>

ws:title

This tag contains the main title of the site in a given language.

<ws:title>My own personal site</ws:title>

Metadata and inclusion

The tags described in this section may be used in the main configuration, or in the ws:page tags from either the site map or the contents section.

ws:css

This tag causes a CSS file to be loaded by the generated HTML contents. The final list of files to load will be the combination of all ws:css tags that apply to the page in the current language. The files must be in the CSS directory (either css/ or the directory specified by the corresponding ws:path-to tag). The extension must not be given.

<ws:css>style</ws:css>

ws:image-preload

This tag allows images to be pre-loaded into a hidden layer on the pages. It is useful in combination with JavaScript. It must have two attributes: id (which will be translated into a HTML node identifier for the resulting img tag), and file. The file name is relative to the site's image directory, as configured by the ws:data-paths tag.

<ws:image-preload id="js-menu-open" file="menu/open.png" />
<ws:image-preload id="js-menu-closed" file="menu/closed.png" />

ws:meta

This tag allows additional HTML meta data to be added to a page. Each ws:meta tag has two attributes, name and content, which correspond to their HTML counterparts. If the same meta data is defined at different level (site, page, language+page), the most specific value will be used.

<ws:meta name="verify-v1" content="some-random-value-from-google-webmaster-tools" />

ws:script

This tag causes a JavaScript file to be loaded by the generated HTML contents. The final list of files to load will be the combination of all ws:script tags that apply to the page in the current language. The files must be in the JavaScript directory (either js/ or the directory specified by the corresponding ws:path-to tag). The extension must not be given.

<ws:script>jquery</ws:script>

HTML generation

The following tags may be used anywhere in the contents of pages.

ws:complete-history

This tag will generate a list that includes all of the site's history.

<ws:complete-history />

ws:image

This tag can be used to generate HTML img tags. Two attributes may be used to indicate the source of the image: either external (which should contain an absolute URL to the image) or relative which will contain a path relative to the site's image directory. The title attribute will be used for the image's alt attribute. In addition, the id, class and style attributes can be used - they will be copied directly to the HTML contents.

<ws:image relative="roaches.jpg"
	title="A picture of my pet cockroaches"
	style="border: 0" class="pic" />

ws:link-to

This tag can be used to generate links to either pages managed by PySSE or to files hosted on the site. If the page attribute is present and contains a page identifier, a link to this page will be made. If the relative attribute is present instead, a link relative to the site's root will be generated.

The link's title is automatically generated for page links. However, when using relative links or if it is required to override it, the title attribute may be used.

Finally, the id, class and style attributes can be used - they will be copied directly to the HTML contents.

a nice <ws:link-to page="other-page">page<ws:link-to> link <br/>
and also a <ws:link-to relative="file.tar.gz"
	title="Download the file!">file<ws:link-to>

External data files

Pages

Files that contain page data must use ws:ext-data as their top-level element. They may contain XHTML code as well as PySSE HTML generation tags.

<?xml version="1.0" encoding="UTF-8"?>
<ws:ext-page xmlns="http://www.w3.org/1999/xhtml"
             xmlns:ws="http://www.ebenoit.info/data">

	<h2>External page</h2>
	<p> This is an external page. </p>

</ws:ext-page>

Translations

Translation files have ws:strings as their top-level element; they contain a sequence of ws:string tags, each with an id attribute which identifies the string.

<?xml version="1.0" encoding="UTF-8"?>
<ws:strings xmlns="http://www.w3.org/1999/xhtml"
            xmlns:ws="http://www.ebenoit.info/data">

	<ws:string id="language">Language</ws:string>

</ws:strings>

History

History files must have ws:history as their root element. They contain a sequence of ws:entry tags. Each of these entries has a date attribute, containing the localised string for the entry's date. The tag's contents are XHTML as well as PySSE HTML generation tags.

<?xml version="1.0" encoding="UTF-8"?>
<ws:history xmlns="http://www.w3.org/1999/xhtml"
            xmlns:ws="http://www.ebenoit.info/data">

	<ws:entry date="9th of May, 2009">
		<strong>PySSE 0.2.0</strong>: complete rewrite.
	</ws:entry>

</ws:history>