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.
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.
By default, two languages may be supported: English (en) and French (fr). If you need to support additional languages, you will need to write translations for them.
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="»" />
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>
This tag configures the feeds to display in the feeds block. It contains a sequence of ws:feed tags, using the following attributes:
Note: before 0.2.6, only RSS 2 feeds were supported.
<ws:feeds> <ws:feed from="http://wordpress.org/development/feed/" id="wpdev" /> </ws:feeds>
NEW IN 0.2.4
This tag enables and configures internal link debugging capabilities. In order to activate internal link debugging, the tag must have the enable attribute set to 1. Two other attributes may be used:
WARNING: enabling internal link debugging may cause quite a bit of overhead. Do not enable it on production sites.
<ws:link-debug enable="1" no-page="bad-page"
no-anchor="bad-anchor" />
NEW IN 0.2.4
This tag allows the menu's maximal depth to be configured. It must have a depth attribute, which will contains an integer value (which should be greater than 0). If this tag is not present, or if its value is invalid, the menu's maximal depth will default to 2.
<ws:menu depth="3" />
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>
NEW IN 0.2.5: this tag may now be used in page groups and in language-specific sections of the configuration.
This tag defines the elements to display in the side bar. By default, it configures the general aspect of the side bar; however, adding the page attribute and setting it to a page identifier allows page-specific side bar configurations to be created.
NEW IN 0.2.5: side bar configurations may also be associated with page groups. The side bar configuration is looked up in this order:
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:
NOTE: before PySSE 0.2.6, the feeds box had the rss-feeds identifier.
<ws:side-bar> <ws:block source="menu" /> </ws:side-bar> <ws:side-bar page="main"> <ws:block source="menu" /> <ws:block source="site-history" /> </ws:side-bar>
NEW IN 0.2.3
This tag defines a language-agnostic title for the web site. It is overriden by language-specific site titles if they exist.
<ws:title>MySite</ws:title>
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.
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.
NEW IN 0.2.5
Page groups allow sets of pages to be manipulated. They are defined at the root of the configuration, but may be used in the language-specific sections as well.
A page group is characterised by its identifier, which must be unique. The pages that belong to a group are determined by two sets of rules:
Both type of rules can use either exact page identifiers or regular expressions on the page's identifiers. Inclusion rules are mandatory, exclusion rules may be omitted.
A page group is defined using the ws:group tag, using the id attribute to define its identifier. The inclusion and exclusion rule sets are defined by the ws:include and ws:exclude tags, respectively. In each rule set tag, the ws:match tag is defines the rules themselves; this tag may use either the exact attribute to match exact page names, or the re attribute to match page identifiers using a regular expression.
<ws:group id="pysse-sub-pages"> <ws:include> <ws:match re="^pysse-" /> </ws:include> <ws:exclude> <ws:match exact="pysse-home" /> </ws:exclude> </ws:group>
In addition to the group's definition, the ws:group tag may contain any number of metadata and inclusion tags; it may also contain a ws:page-data tag which will indicate the base path for the pages in the group.
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.
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" />
This tag contains the complete name of the language. It is used to generate the language selector.
<ws:langname>English</ws:langname>
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>
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>
This tag contains the main title of the site in a given language.
NEW IN 0.2.3: if this tag is not present, PySSE will try to use the language-agnostic alternative.
<ws:title>My own personal site</ws:title>
The tags described in this section may be used in the main configuration, in the language-specific section, or in the ws:page tags from either the site map or the contents section.
This tag determines the name of the author of a page.
<ws:author>Emmanuel Benoît</ws:author>
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>
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 an id attribute which will be translated into a HTML node identifier for the resulting img tag. It contains the name of the image file to pre-load relative to the site's image directory, as configured by the ws:data-paths tag.
<ws:image-preload id="js-menu-open">menu/open.png</ws:image-preload> <ws:image-preload id="js-menu-closed">menu/closed.png</ws:image-preload>
NEW IN 0.2.5
This tag defines keywords to be used in the eponymous XHTML meta tag. Keywords from all levels of the configuration will be merged to generate a page's keywords.
<ws:keyword>PySSE</ws:keyword>
NEW IN 0.2.5
This tag allows the page to have an alternative, longer title which will be used both in the links' title and in the HTML header. This alternative title can be defined in three different ways:
The type of title is specified through the mode attribute, which must be either replace, prefix or suffix.
Note 1: replacement is only supported inside ws:page tags (either from the site map or from the language-specific section).
Note 2: if the mode is not specified, it will default to replace inside page tags and to prefix anywhere else.
<ws:group id="pysse-sub-pages"> ... <ws:long-title mode="prefix">PySSE: </ws:long-title> </ws:group>
This tag allows additional HTML meta data to be added to a page. Each ws:meta tag has a name attribute, and some content. If the same meta data is defined at different level (site, language, page, language+page), the most specific value will be used.
<ws:meta name="verify-v1">some-random-value-from-google-webmaster-tools</ws:meta>
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>
The following tags may be used anywhere in the contents of pages.
This tag will generate a list that includes all of the site's history.
<ws:complete-history />
NEW IN 0.2.6
This tag causes PySSE to generate a page from the feeds that have been configured in the main configuration section through ws:feeds. It can be used either alone, in which case all of the feeds are displayed, or using an id attribute that matches the identifier of a feed definition, in which case only this feed is displayed.
<ws:feed id="wpdev" />
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" />
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.
NEW IN 0.2.4: when using ws:link-to to create internal links, it is possible to link directly to a part of the page by using the anchor attribute.
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 a link to a <ws:link-to page="other-page" anchor="there">section</ws:link-to> of that page.<br/> And finally a <ws:link-to relative="file.tar.gz" title="Download the file!">file</ws:link-to>
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>
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 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>