Ground Rules
Here's a few ground rules and bits of important information
- Everything needs to be valid XML, tags must be closed and properly nested
- You need to escape '&'s as '&'
- The parsing engine is pretty naive, so you have a lot of power. For example, it will even let you completely redefine <div> tags.
- If you're using SWS dynamically without mod_rewrite (don't imagine why you wouldn't just use static mode at that point), you need to fully qualify any would be relative links to include "/?p=" (automatically rewriting these links is a yet-to-be-implemented feature).
Document Structure
template.sws must contain a root <site> node. A root node must contain a template attribute pointing to an HTML template. The <site> node must contain at least one page. Variables can be "defined by default" by declaring them in the <site> node. Pages are not strictly required to contain anything, but can contain variable definitions and a <subpages> tag in which sub pages are defined and potentially default variables for the sub pages are defined. Thus the node types are as follows:
<site>
Attributes:
template = The HTML template to parse
filepath (optional - static compilation) = The root directory on the filesystem to compile static html files to
urlpath (optional - static compilation) = The site URL path to the static files
css (optional) = The css stylesheet to include
title (optional) = The defualt title to be prepended to all page titles
Contains: <page> tags and <*> tags.
<page>
Attributes:
link = The address of this page relative to its parent (URLs are case insensitive and a space matches an underscore)
name (optional) = A name to display in autogenerated links
hidden (optional) = If "true", the page is never displayed in any menus
ref (optional) = An external url to reference, for links in menus to external web sites
title (optional) = The title to be appended to all page titles
Contains: a <subpages> tag and <*> tags.
<subpages>
Attributes: None
Contains: <page> tags and <*> tags.
<*> (a.k.a variable tags)
Attributes: None
Contains: The arbitrary HTML to replace this variable with when found in the html template and other variable definitions
Parsing Stages
Variable Initialization and Scoping
In the first pass through template.sws, all tags that are children of <site> or <page> that are not named <page> or <subpages> are treated as variables in which their value is the inner value of the given element. Variables are scoped according to depth and the selected page. Only nodes in the line of ancestors from the requested page are collected from and deeper definitions take precedence over shallower definitions. A few variables are automagically created for your convenience (see Automagic Variables).
Automagic Variables
For convenience a few variables are automatically populated
alllinks - All links as <a> tags, collected into <div> tags by level in the navigation tree.
links - Only the top level links
sub(*n)links - Links at level (n+1)
breadcrumb - A list of <span> tags that contain each section of the URL
path - Only the top level part of the URL
sub(*n)path - Path at level (n+1)
Recursive Variable Substitution
Next, each tag in the template is replaces by its variable contents, and then the variable contents are parsed for potential replacements. Note that if you reference a variable within its definition, it will result in an infinite loop (so don't do this). The replacement rules are as follows. Assuming "foo" is defined as "bar":
| Source | Replacement | |
| <div id="foo" /> | <div id="foo">bar</div> | |
| <foo /> | bar |
An Example
See the example here or the template.sws and html template for this website