Using Rextile

Running Rextile

Rextile is an offline site-construction tool that works on files and folders. Running it is very simple. Just change to your site’s root folder and issue:

/path/to/rextile/rextile

Here’s what this does:

• Read and eval _site.rb. This is where you set global options like template_path.

• Read all files ending in .rextile in the current folder and its subfolders. Process each one (see below) and write out the resulting .htm file (output path and name can be changed), unless it is still the same as before.

How .rextile Files Are Processed

For each .rextile file, Rextile processes first the Textile form, then the XHTML form.

Textile Processing

• Set html_name to the name of of text .rextile file, but with the extension changed to .htm.

• Read the file into a string called rextile.

• Look for a file called _wrapper.rextinc (file lookup rules are listed below).

• If found, replace rextile with the contents of the wrapper file, but substitute the sequence CONTENT GOES HERE by the former contents of rextile.

• Run erb on the string rextile.

• Run RedCloth on the string rextile, returning a new string html.

• Issue a warning for all remaining links of the form <a href="-...">. This helps you spot missing deferred link targets if you always write deferred links like :-abbr.

XHTML Processing

• In the string html, convert all <§...§> sequences to <%...%> sequences.

• Look for a file called _wrapper.xhtmlinc (file lookup rules are listed below).

• If found, replace html with the contents of the wrapper file, but substitute the sequence CONTENT GOES HERE by the former contents of html.

• Replace all <%i expr %> sequences by the result of evaluating expr. This is meant for include files, as in <%i read_closest_file( '_header.xhtml' ) %> which must be processed first as they may contain definitions used by later script sequences.

• Setup html_doc as an Hpricot DOM tree of html as it stands so far.

• Run erb on the string html.

• Setup html_doc as an Hpricot DOM tree of html anew.

• Process all nodes in html_doc matching the CSS selector pre.rscript, as explained below.

• Convert the DOM back to HTML and write it to html_name, unless the existing file already contains the very same HTML.

XHTML Script Node Processing

• Set html_script_node to the node being processed.

• Evaluate the node’s text.

• Build a new DOM from the evaluation result, interpreted as a single-root XHTML snippet.

• Replace the node by the root of the new DOM.

Out-of-order Processing

You can instruct Rextile to process a file during the processing of another file. This is handy when automatically building listings of other files in index pages, for example. To do this, just say process 'my/path/myfile.rextile' within an embedded script. Rextile maintains a list of files already processed so files don’t get processed twice.

You can see this in action in the file sample/articles/index.rb.

File Lookup

When Rextile looks for the wrapper files _wrapper.rextinc and _wrapper.xhtml, it uses the method read_closest_file() to do so. This method looks in the current .rextile file’s folder, and then in all its parent folders up to the site root. Finally, it looks in template_path. It returns the first matching file. This means you can override the files at every folder level of your site.

The standard template also makes use of this method to find auxiliary files like, for example, _init.rb.

There are two other, related methods, that concatenate all of the files, rather than just returning the first match. They are

• read_prepended_files() – adds files in outer folders first
• read_appended_files() – adds files in outer folders last

The standard template uses the former to read _settings.rb. This means that inner settings are evaluated last and thus have precendence.

Dependency Checking

Largish sites can take quite a while to build. To speed up the repeated rebuilds while you’re developing content, you can make Rextile keep track of which files need to be regenerated. To enable this, add to your _site.rb a line like the following:

@dependency_info = '/path/to/rextile.deps'

Rextile will then store information on what files depend on which other file versions in that file and only rebuild out-of-date files on subsequent runs.

Accessing External Files

To enable dependency checking, you have to make sure that you read external files used by your inlined scripts using the file-reading functions provided by Rextile as described above. To build folder indices, use glob( pattern ) and read_file( name ), again as provided by Rextile.

Sample Wrapper Files

_wrapper.rextinc

The Rextile wrapper file, if present, is used to define a common header and footer for every page. Rextile simply uses the wrapper file’s source and, within it, replaces the sequence CONTENT GOES HERE by the page’s source text. For example:

p=. Header

CONTENT GOES HERE

p=. Footer

More typical than this contrived example is putting a script block in the header part where you initialize custom instance variables and require global modules. Those can then be used in script blocks within the pages themselves, and in the HTML script blocks in _wrapper.xhtml. See the standard template for a more elaborate example.

_wrapper.xhtmlinc

The XHTML wrapper file, if present, defines the common XHTML header and footer for every page. Rextile simply uses the wrapper file’s source and, within it, replaces the sequence CONTENT GOES HERE by the body XHTML produced for the page. For example:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
</head>
<body>

CONTENT GOES HERE

</body>
</html>

Using XHTML script blocks of the form <%...%> here is very handy. See the standard template for a more elaborate example.