Voidspace

rest2web: Building Websites Across the Known Universe

The User Values

Extra Values in Your Templates

Introduction

rest2web generates pages by inserting special values into your web page templates. This includes the body of the page, the title, and so on. You can see from the templates page the values you can use in your templates. uservalues are a way of inserting extra values into your template. As you might guess, you specify the names and values.

One obvious use of this is to provide several different translations [1] of your website.

uservalues

uservalues are specified in a similar way to the restindex. uservalues are specified immediately after the restindex. :

restindex
    crumb: A Page
/restindex

uservalues
    value1: Some Value
    heading: <h1>A Heading</h1>
    long_value: """
A multi line value
which spreads across
several lines.
"""
    another_long_value:"""
        This one
        has a big indent
        in front of it ! """
/uservalues

An addition to the restindex syntax, is that multiline values use triple quotes.

Caution!

Indentation is not removed from multi line values. The text between the triple quotes is inserted literally wherever you use the value. You can use single or double quote marks.

There is one special value, the body value discussed below.

Reserved Names

You can't use any name that shadows a name already used by the templating system. This means that the following names are all reserved. Trying to use them will cause a SyntaxError. :

reserved_names = [
    'title', 'breadcrumbs', 'sections', 'pagename', 'pagepath',
    'encoding', 'output_encoding', 'final_encoding', 'path_to_root',
    'sectionlist', 'rest_dict', 'doc', 'stdout', 'modified', 'modtime',
    'template_file', 'template_encoding', 'indexpage', 'indextree',
    'thispage', 'sidebar', 'minibar', 'print_crumbs', 'Processor', 'tags',
    'default_section',
    ]

Note

See that title is a reserved name. If you want to set the page title, you should use the page-title keyword in your restindex.

The body Value

The body value is special. This lets you specify a file that is the content for this page. Any content following the uservalues is ignored - and the specified file is used instead.

If that file has template tags that use the uservalues - then they will be substituted when the template is processed.

The file specified can be an absolute path, or a path relative to the page it is bein used in.

For example, say we have the following for our uservalues :

uservalues
    body: ../templates/a_page.txt
    greeting: <h1>Howdy</h1>
/uservalues

rest2web will use the file ../templates/a_page.txt as the body of this page. If it contains a tag that looks like <% greeting %>, then it will be replaced with <h1>Howdy</h1> when the template is processed.

Warning

Using the body value you separate your content from your file containing the restindex/uservalues. You must store them with the same encoding.

Translations

A good example of using the body value is for multiple translations of websites. A typical example is where you have several pages of content that you want to mirror in different languages. That is, you want the same pages, with the same structure, just key sections swapping over.

The body value lets you keep your page frameworks all in one place. The framework should use the uservalues - and then just have several directories of pages which point to the framework... but have the right values set for the uservalues.

There is an example in the example site - the translation pages. See the source of these pages for a clear illustration how of how it works.

Now I'll attempt to explain it in words Razz .

Suppose you want three translations for your site. You'll put the english files in a directory called en, the French ones in a directory called fr, and the German ones in a directory called de. The HTML framework of each page is going to be identical in each directory - it's just the viewable words that will be different.

To achieve this we add a fourth directory called templates. It's in here that we are going to put our HTML frameworks. Everywhere we want some text to appear we will put a uservalue placeholder instead.

We have our usual template.txt which contains the outline of the page. We'll create a file in the template directory called index_page.txt [2]. It might look something like :

<div class="someClass">
    <h1><% greeting %></h1>
</div>

<div class="para">
    <p><% para1 %></p>
</div>

This page body has a placeholder for the headline and the paragraph.

In index.txt in your en folder you would then put :

restindex
    format: html
    crumb: English Index
    page-title: English Index
/restindex
uservalues
    body:       ../templates/index_page.txt
    greeting:   Hello and Welcome
    para1:      """This is the body text,
 with <em>some HTML</em> in it."""
/uservalues

When rendered, it fetches the index_page.txt as the body, and inserts the English values into it.

In index.txt in your fr folder you would then put :

restindex
    format: html
    crumb: French Index
    page-title: French Index
/restindex
uservalues
    body:       ../templates/index_page.txt
    greeting:   Bonjour et Bienvenue
    para1:      """Du Francais ici,
 avec <em>du HTML</em>."""
/uservalues

When rendered, this creates the French page.

You create your basic directory structure in the templates directory. You mirror this in your other directories; but your files are all basically identical and you only need to edit the uservalues.

With a little trickery in the body or the templates it ought to be simple to include links between pages in one language and the other ones.

The Order of Processing

If the page format is html then uservalues are inserted when the template is processed.

If the page format is rest then the uservalues are inserted into the body before it is passed to docutils. The whole of the body - with substitued values for any of your uservalues will then be processed as reST. This means that your body mustn't contain any of the usual template values - because they haven't been created yet. Because docutils escapes template markers that appear in the body of your page [3], you probably weren't doing this anyway !.

It does mean that chunks of code in the body do get executed and replaced. If this messes up using uservalues in your index, then let me know. I can implement an alternative method of inserting uservalues into the body that doesn't execute code chunks [4].

Even if the page format is rest, the uservalues will still be used when the template is processed. (After the body has been rendered by docutils). This means you could have some uservalues for your body, and others in your template.


Footnotes

[1]This footnote is just so that the words internationalization (i18n), and localization (l10n) appear somewhere on this page Smile .
[2]We won't call it index.txt, which is a special file in rest2web. The example site uses _index.txt.
[3]<% value %> will become &lt;% value %&gt;; which doesn't work Sad . If you do need to do this (by the way) you could always use the raw role. This could introduce complications with uservalues though.
[4]Unfortunately here it's a trade off between the ability to do one thing (insert uservalues into your body text and process as reST) and another (using the templating system in the body of your text).

Return to Top
Part of the rest2web Docs
Page last modified Thu Mar 30 17:04:24 2006.


Site Built with rest2web SourceForge.net Logo Certified Open Source

Python on Voidspace