/usr/share/doc/rest2web/html/templating.html is in rest2web-doc 0.5.2~alpha+svn-r248-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<title>Templating with rest2web</title>
<link rel="stylesheet" href="stylesheets/rest2web.css" type="text/css" />
<link rel="stylesheet" href="stylesheets/voidspace_docutils2.css" type="text/css" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="description" content="rest2web - build websites with Python and docutils." />
<meta name="author" content="Michael Foord" />
<meta name="copyright" content="© 2003-2006 Michael Foord, subject to BSD License" />
<meta name="keywords" content="rest2web - build websites with Python and docutils,
rest, restructured text, text, website, internet, web, net, web builder, site,
site builder, docutils, i18n, internationalization, templates, templating,
python, " />
</head>
<body style="background: url(images/logos/img_background.gif) top center repeat-y;">
<div id="wrap">
<div id="header-section">
<a href="http://www.voidspace.org.uk/python/index.shtml" title="Voidspace"><img src="images/logos/header760.gif" alt="Voidspace"/></a>
<p align="center" class="headertitle"><span style="font-size:130%">rest2web:</span> Building Websites Across the Known Universe</p>
</div>
<div id="header">
<ul>
<li><a href="index.html">rest2web</a></li>
<li>></li>
<li>Templates</li>
</ul>
</div>
<table>
<tr>
<td><img src="images/logos/1.gif" width="1" height="1" alt="" /></td>
<!-- main content cell first, with rowspan=2 -->
<td valign="top" align="left" rowspan="2">
<div id="middle-column">
<a name="startcontent" id="startcontent"></a>
<div id="gallery">
<div class="document" id="templating-with-rest2web">
<h1 class="title">Templating with rest2web</h1>
<h2 class="subtitle" id="using-rest2web-templates">Using rest2web Templates</h2>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#introduction" id="id12">Introduction</a></li>
<li><a class="reference internal" href="#the-templates" id="id13">The Templates</a><ul>
<li><a class="reference internal" href="#inserting-html" id="id14">Inserting HTML</a></li>
<li><a class="reference internal" href="#inserting-rest" id="id15">Inserting ReST</a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-list-of-values" id="id16">The List of Values</a></li>
<li><a class="reference internal" href="#the-template-file" id="id17">The Template File</a></li>
<li><a class="reference internal" href="#note-about-macros" id="id18">Note About Macros</a></li>
<li><a class="reference internal" href="#footnotes" id="id19">Footnotes</a></li>
</ul>
</div>
<div class="section" id="introduction">
<h1><a class="toc-backref" href="#id12">Introduction</a></h1>
<p><strong>rest2web</strong> templates are rendered using a python module called <tt class="docutils literal"><span class="pre">embedded_code</span></tt> from the <a class="reference external" href="http://www.voidspace.org.uk/python/firedrop2/">firedrop2</a> blog tool. It is aptly named; because it allows you to embed chunks of <a class="reference external" href="http://www.python.org">Python</a> code into text files. Wherever there is a chunk of Python in the template, this is executed - and the output is put into the text. This means that if you are a Python programmer, the templating system is <em>very</em> simple. <img src="images/smilies/smile.gif" alt="Smile" /> </p>
<p>Even if you've never used Python before, the system is very easy to learn. Have a look at <a class="reference external" href="tutorial.html">the tutorial</a>, which will get you up and started very quickly. Of course, once you start using Python, it won't be long before you're addicted. <img src="images/smilies/wink.gif" alt="Wink" /> </p>
<p>This page describes the templating system - and the <em>special values</em> that you use with it. These values can be used in your <acronym title="HyperText Markup Language">HTML</acronym> templates <em>and</em> your pages.</p>
</div>
<div class="section" id="the-templates">
<h1><a class="toc-backref" href="#id13">The Templates</a></h1>
<p>The point of templating is to dynamically insert values into generated pages. The <strong>rest2web</strong> templating system can be used to insert special values into your templates (which go into every page that uses that template) - or into individual pages.</p>
<p>There are two sets of tags to do this, depending on whether you want to insert HTML or ReST into your templates. You would only insert ReST into your <em>pages</em>, rather than into your templates. This would usually be done in conjunction with <a class="reference external" href="reference/uservalues.html">uservalues</a>.</p>
<div class="section" id="inserting-html">
<h2><a class="toc-backref" href="#id14">Inserting HTML</a></h2>
<p>There are two sets of tags to use with template values. The simplest is to insert a single name between template tags. This is evaluated and the value inserted into the page. This looks like - <tt class="docutils literal"><span class="pre"><%</span> <span class="pre">name</span> <span class="pre">%></span></tt> - where <em>name</em> is our special value.</p>
<p>The second way allows you to execute blocks of code. Chunks of code can be inserted between <tt class="docutils literal"><span class="pre"><#</span> <span class="pre">...</span> <span class="pre">#></span></tt> tags. Anything that is printed <a class="footnote-reference" href="#id6" id="id1">[1]</a> will be put into the page. The code must be valid python, which includes obeying Python's rules about indentation. Here's a quick example :</p>
<pre class="literal-block">
<#
import urllib
blank = '&nbsp;'
row = '<tr><td>%s</td><td>%s</td></tr>'
entry = '<a href="#%s">%s</a>'
# Get a list of the sections *excluding* the default section
sectlist = [(urllib.quote(section), section.title())
for section in sections if section is not None]
index = 0
while index < len(sectlist):
entry_1 = entry % sectlist[index]
if index == len(sectlist)-1:
entry_2 = blank
else:
entry_2 = entry % sectlist[index+1]
print row % (entry_1, entry_2)
index += 2
#>
</pre>
<p>In case you can't work it out, this chunk of code uses <tt class="docutils literal"><span class="pre">urllib.quote</span></tt> to make section names safe for inclusion in a <acronym title="Uniform Resource Locator">URL</acronym> link. It then inserts a link to each section in an anchor tag (<em>entry</em>) in a table row (<em>row</em>).</p>
<p><tt class="docutils literal"><span class="pre">embedded_code</span></tt> will automatically remove any (uniform) excess indentation - this means the whole chunk of code can be indented to fit in with your page structure.</p>
<p>The code chunks are all executed inside a <strong>namespace</strong>. This determines what variables (names) are available to you to use. All the code in a page is executed inside the same namespace - this means that changes you make in a chunk of code at the start of a page will be visible to later chunks of code. This can be useful - but it also means you shouldn't mangle variables you intend to use later.</p>
<p>There are a set of <a class="reference external" href="functions.html">standard functions</a> available to you to perform common tasks. Printing indexes, breadcrumbs, and sidebars can all be done with single line commands.. <img src="images/smilies/surprised.gif" alt="Surprised" /> </p>
</div>
<div class="section" id="inserting-rest">
<h2><a class="toc-backref" href="#id15">Inserting ReST</a></h2>
<p>The basic principle for inserting ReST into your pages (before they are turned
into HTML) is exactly the same as inserting HTML into your template pages.</p>
<p>The difference is, that you use different tag styles. For single values use :</p>
<blockquote>
<tt class="docutils literal"><span class="pre"><*</span> <span class="pre">...</span> <span class="pre">*></span></tt></blockquote>
<p>For chunks of embedded code use :</p>
<blockquote>
<tt class="docutils literal"><span class="pre"><$</span> <span class="pre">...</span> <span class="pre">$></span></tt></blockquote>
</div>
</div>
<div class="section" id="the-list-of-values">
<h1><a class="toc-backref" href="#id16">The List of Values</a></h1>
<p>So the only thing remaining is for you to know what special values are available. Below is the full list of <em>normally available values</em>. You can also add your own values to the namespace, using <a class="reference external" href="reference/uservalues.html">uservalues</a> <a class="footnote-reference" href="#id7" id="id2">[2]</a> :</p>
<ol class="arabic">
<li><p class="first"><em>title</em> - title of the page being rendered.</p>
</li>
<li><p class="first"><em>body</em> - full body of the page.</p>
</li>
<li><p class="first"><em>breadcrumbs</em> - this is a list of tuples that represents the navigation trail for this page.</p>
<blockquote>
<p>Each tuple is <tt class="docutils literal"><span class="pre">(crumb_link,</span> <span class="pre">crumb)</span></tt>. <tt class="docutils literal"><span class="pre">crumb_link</span></tt> is a relative link from the document being rendered to the target of the crumb. This means the crumb links will still work when the site is viewed from the filesytem, or moved around in a website.</p>
<p>You can use a chunk of code to insert these into links :</p>
<pre class="literal-block">
<#
# this is the breadcrumbs code
# breadcrumbs is a list of tuples
anchor = '<a href="%s">%s</a>'
divider = ' > '
index = -1
while index < len(breadcrumbs)-2:
index += 1
entry = breadcrumbs[index]
print (anchor % entry),
print divider,
if breadcrumbs:
print breadcrumbs[-1][1] # not as a link
#>
</pre>
<p>An alternative way of doing your breadcrumbs, used in the example site, is available as a <a class="reference external" href="functions.html">standard function</a> <strong>print_crumbs</strong>. It makes each 'crumb' a list item - '<li>..</li>'. CSS is then used to show this as a horizontal list, without bullet decoration. Simply put <tt class="docutils literal"><span class="pre"><#</span> <span class="pre">print_crumbs(breadcrumbs)</span> <span class="pre">#></span></tt> in your template to call it. See the <a class="reference external" href="functions.html">standard functions</a> page for more details.</p>
</blockquote>
</li>
<li><p class="first"><em>sections</em> - This is a data structure with information about all the pages in the current directory. It is a dictionary with all the sections.</p>
<blockquote>
<p>Each key is a section name (the default section is keyed by <tt class="docutils literal"><span class="pre">None</span></tt> - <tt class="docutils literal"><span class="pre">sections[None]</span></tt>). Each section is also a dictionary. Each section dictionary has the following keys :</p>
<blockquote>
<ul>
<li><p class="first">title</p>
</li>
<li><p class="first">description</p>
</li>
<li><dl class="first docutils">
<dt>pages - this is a list of dictionaries. Each dictionary represents a page. Each page dictionary has the following keys :</dt>
<dd><ul class="first last simple">
<li><strong>target</strong> - the page location</li>
<li><strong>section</strong> - which section it is in</li>
<li><strong>link-title</strong> - the title to use in the link to the page</li>
<li><strong>page-description</strong> - a description of the page</li>
<li><strong>crumb</strong> - the crumb (very short name) for that page</li>
<li><strong>namespace</strong> - the namespace for the page (a dictionary). Values will be encoded with the <tt class="docutils literal"><span class="pre">final_encoding</span></tt> for <em>this page</em>. If the page isn't being built then this value will be <tt class="docutils literal"><span class="pre">None</span></tt>.</li>
<li><strong>subdir</strong> - does this page represent a subsection ? (it will be the index page for a subdirectory if this value is <tt class="docutils literal"><span class="pre">True</span></tt>)</li>
</ul>
</dd>
</dl>
</li>
</ul>
<p>The values 'crumb', 'link-title', 'section', and 'page-description', will all be encoded using the <tt class="docutils literal"><span class="pre">final_encoding</span></tt> for the <em>page that is accessing them</em>. This means it is safe to use them directly in your template without worry about the encoding of the page they come from. This is not true for values in the 'namespace' of each page.</p>
</blockquote>
<p><tt class="docutils literal"><span class="pre">sections</span></tt> has a method for sorting the pages contained in all the section dictionaries. By default the pages are sorted according to the <tt class="docutils literal"><span class="pre">section-pages</span></tt> in the restindex. If you don't use section-pages, the ordering is arbitrary. The <tt class="docutils literal"><span class="pre">sortpages</span></tt> method allows you to sort the pages by <tt class="docutils literal"><span class="pre">link-title</span></tt> (alphabetical) or pass in a custom function to do the sorting. (The same sort of function you would pass to the Python <tt class="docutils literal"><span class="pre">sort</span></tt> method of lists.)</p>
<div class="pysrc"><span class="pytext">sections</span><span class="pyoperator">.</span><span class="pytext">sortpages</span><span class="pyoperator">(</span><span class="pytext">sortorder</span><span class="pyoperator">,</span> <span class="pytext">section</span><span class="pyoperator">=</span><span class="pytext">True</span><span class="pyoperator">)</span><span class="pytext"></span></div><p><tt class="docutils literal"><span class="pre">sortorder</span></tt> can either be the string <tt class="docutils literal"><span class="pre">link-title</span></tt> or a custom function.</p>
<p>By default, calling <tt class="docutils literal"><span class="pre">sortpages</span></tt> will sort all the sections. Alternatively you can pass in a string (or None), to specify which section to sort.</p>
<p>Don't forget that there will always be a section with the key <tt class="docutils literal"><span class="pre">None</span></tt> - this is the default section. If you're not using sections, all the pages will be in this section. If every page is in a named section then this section will be empty - but it will still exist. This means that if you loop over all the sections (<tt class="docutils literal"><span class="pre">sections.keys()</span></tt>) one of them will be <tt class="docutils literal"><span class="pre">None</span></tt>.</p>
<p>You can use the 'sections' value to automatically construct things like table of links, like the example at the start of this page. There is also a <a class="reference external" href="functions.html">standard function</a> called <tt class="docutils literal"><span class="pre">minibar</span></tt> available to you. This is typically used to create a sidebar that contains links to all the pages in the section. You can call it by putting <tt class="docutils literal"><span class="pre"><#</span> <span class="pre">minibar(sections)</span> <span class="pre">#></span></tt> in your template. See the page on <a class="reference external" href="functions.html">standard functions</a> for more details (and other parameters you can pass to it).</p>
<p>Note that the 'sections' value has <em>references</em> to the namespace of each page (in it's 'pages' value) - not a separate copy. That means that if your template changes anything in the pages, this change is likely to affect the rendering of other pages.</p>
<p>See the <em>minibar</em> function in the <a class="reference external" href="functions.html">standard functions</a>, for one way of handling this value.</p>
</blockquote>
</li>
<li><p class="first"><em>default_section</em> - This is the default section from the <tt class="docutils literal"><span class="pre">sections</span></tt> value. It is <em>exactly</em> the same as <tt class="docutils literal"><span class="pre">sections[None]</span></tt>.</p>
</li>
<li><p class="first"><em>pagename</em> - the filename of the page (not the full path).</p>
</li>
<li><p class="first"><em>pagepath</em> - full path from top level to current document.</p>
</li>
<li><p class="first"><em>encoding</em> - the original encoding supplied or guessed for the document</p>
</li>
<li><p class="first"><em>output_encoding</em> - the output encoding specified for this page. It can be a specific encoding, or <tt class="docutils literal"><span class="pre">none</span></tt>, or <tt class="docutils literal"><span class="pre">unicode</span></tt> (both text values). See the docs on the <a class="reference external" href="restindex.html">restindex</a>.</p>
</li>
<li><p class="first"><em>final_encoding</em> - This is the final encoding used to encode the output of the page. It may be <tt class="docutils literal"><span class="pre">None</span></tt> if the value for <em>output_encoding</em> was <tt class="docutils literal"><span class="pre">unicode</span></tt>. (In which case the final encoding will follow the template encoding).</p>
</li>
<li><p class="first"><em>path_to_root</em> - path from current document to top level site directory (ends in '/'). This can be <strong>very useful</strong> for providing paths to resources without having to use an absolute URL.</p>
<blockquote>
<p>For example; if your images folder is in your top level directory you could use <tt class="docutils literal"><span class="pre"><img</span> <span class="pre">src="<%</span> <span class="pre">path_to_root</span> <span class="pre">%>images/image.jpg"</span> <span class="pre">/></span></tt> instead of <tt class="docutils literal"><span class="pre"><img</span> <span class="pre">src="/images/image.jpg"</span> <span class="pre">/></span></tt>. This means the reference resolves correctly when viewed from the file system.</p>
</blockquote>
</li>
<li><p class="first"><em>sectionlist</em> - The list of subsections in this directory.</p>
</li>
<li><p class="first"><em>rest_dict</em> - only present if the page generated from reST content, else <tt class="docutils literal"><span class="pre">None</span></tt>. This is the full dictionary of parts returned by the docutils <tt class="docutils literal"><span class="pre">html_parts</span></tt> function.</p>
</li>
<li><p class="first"><em>doc</em> - everything that has been printed so far (only available for <tt class="docutils literal"><span class="pre"><#</span> <span class="pre">...</span> <span class="pre">#></span></tt> type code). This is a <tt class="docutils literal"><span class="pre">StringIO</span></tt> instance.</p>
</li>
<li><p class="first"><em>stdout</em> - the <em>real</em> <tt class="docutils literal"><span class="pre">sys.stdout</span></tt>. Can be used if you want your code to print a traceback to the shell (only available for <tt class="docutils literal"><span class="pre"><#</span> <span class="pre">...</span> <span class="pre">#></span></tt> type code).</p>
</li>
<li><p class="first"><em>modified</em> - the time the page was last modified, as a number of seconds since the <em>epoch</em> <a class="footnote-reference" href="#id8" id="id3">[3]</a></p>
</li>
<li><p class="first"><em>modtime</em> - a string representing the time the page was last modified, created using <tt class="docutils literal"><span class="pre">time.ctime(modified)</span></tt>.</p>
</li>
<li><p class="first"><em>template_file</em> - a path to the file we are using as the template for generating this page.</p>
</li>
<li><p class="first"><em>template_encoding</em> - the encoding used to decode the template file.</p>
</li>
<li><p class="first"><em>indexpage</em> - the information dictionary for the index page for this section. This page <em>isn't</em> included in the <tt class="docutils literal"><span class="pre">sections</span></tt> value, so it is available separately.</p>
</li>
<li><p class="first"><em>indextree</em> - <tt class="docutils literal"><span class="pre">indextree</span></tt> is a nested data structure representing the pages that have been rendered so far. This will include all the pages and directories <em>above</em> the one currently being rendered. <tt class="docutils literal"><span class="pre">indextree</span></tt> itself is the top level index page (the 'root' of your site). It has members which represent all the other pages and directories.</p>
<blockquote>
<p>Each member is a page. If a page is an index page, it may itself have members that are pages in that directory. Get all that. <img src="images/smilies/smile.gif" alt="Smile" /> </p>
<p>You can use this data-structure to build sidebars and menus etc.</p>
<p>See the <em>sidebar</em> function in the <a class="reference external" href="functions.html">standard functions</a> for a simple example of using <tt class="docutils literal"><span class="pre">indextree</span></tt> to do this.</p>
<p>For full details on this complicated value, see the <a class="reference external" href="reference/indextree.html">indextree</a> page.</p>
</blockquote>
</li>
<li><p class="first"><em>thispage</em> - This is a reference into the <tt class="docutils literal"><span class="pre">indextree</span></tt> data structure. It just points to the current page. It would allow you to create menus from the 'bottom up'. For example you could create a navigation trail from the current page back to the main index, rather than the other way round.</p>
<blockquote>
<p>Note that if the current page has 'include' set to 'No', then <em>thispage</em> will be <tt class="docutils literal"><span class="pre">None</span></tt>, because the current page isn't in <em>indextree</em>.</p>
</blockquote>
</li>
<li><p class="first"><em>sidebar</em> - A <a class="reference external" href="functions.html">standard function</a> for printing sidebars. In fact it is a generator that yields pages one at a time. For details on how to use it see the page on <a class="reference external" href="functions.html">standard functions</a>.</p>
</li>
<li><p class="first"><em>minibar</em> - Another <a class="reference external" href="functions.html">standard function</a> for printing simpler sidebars. It prints a list of all the pages in the current section. For details on how to use it see the page on <a class="reference external" href="functions.html">standard functions</a>.</p>
</li>
<li><p class="first"><em>print_crumbs</em> - This is a <a class="reference external" href="functions.html">standard function</a> for printing navigation trails, known as breadcrumbs. For details on how to use it see the page on <a class="reference external" href="functions.html">standard functions</a>.</p>
</li>
<li><p class="first"><em>print_details</em> - This is a <a class="reference external" href="functions.html">standard function</a> for printing indexes.</p>
</li>
<li><p class="first"><em>section_contents</em> - This is a <a class="reference external" href="functions.html">standard function</a> that returns a list of tuples about pages in a specific section. The data it returns is easier to use than the data contained in <tt class="docutils literal"><span class="pre">sections['section_name']['pages']</span></tt>.</p>
</li>
<li><p class="first"><em>Processor</em> - The actual processor object that is doing the work. Be careful with it <img src="images/smilies/biggrin.gif" alt="Very Happy" /> . A few potentially useful attributes are <tt class="docutils literal"><span class="pre">Processor.dir</span></tt>, <tt class="docutils literal"><span class="pre">Processor.dir_as_list</span></tt>, and <tt class="docutils literal"><span class="pre">Processor.dir_as_url</span></tt> <a class="footnote-reference" href="#id9" id="id4">[4]</a>.</p>
</li>
<li><p class="first"><em>page_description</em> - A string with the description of the current page. Can be useful if you only want to write it in one place. <img src="images/smilies/smile.gif" alt="Smile" /> </p>
</li>
<li><p class="first"><em>include</em> - This is a <a class="reference external" href="functions.html">standard function</a> for including files within templates. These can be nested (included files can include other files). Files are first looked for in the directory being processed, if it isn't found the parent directory is tried, and then its parent etc. Included files <em>will</em> be processed, so they can include embedded code tags.</p>
</li>
<li><p class="first"><em>globalValues</em> - This is a dictionary of globalValues that will be available to all your pages. Initially it is empty, but anything you put in here will be available in all your pages. You can use this to share information between pages, or setup global values. If you do this in your template, you can check if the values exist already and only set them up once.</p>
</li>
<li><p class="first"><em>current_dir</em> - The current directory being rendered, relative to the top level directory. You can turn this into an absolute path using <tt class="docutils literal"><span class="pre">os.path.join(os.getcwd(),</span> <span class="pre">current_dir)</span></tt>.</p>
</li>
<li><p class="first"><em>source_file</em> - The source filepath for the page.</p>
</li>
<li><p class="first"><em>target_dir</em> - The target file directory (as an absolute file path) being rendered into. Note: if the file has a target specified it may not be put in this directory. Use <tt class="docutils literal"><span class="pre">os.path.dirname(target_file)</span></tt> instead.</p>
</li>
<li><p class="first"><em>full_page_url</em> - The full url (starting with '/') for the current page. Using this means that your pages may not work from the filesystem. <img src="images/smilies/smile.gif" alt="Smile" /> </p>
</li>
<li><p class="first"><em>target_file</em> - The full output filepath of the page being rendered.</p>
</li>
</ol>
<p>Pages and templates are passed through <tt class="docutils literal"><span class="pre">embedded_code</span></tt>. This means that if you have HTML pages you can embed code in them. In reST pages you ought to be able to use the <em>raw</em> directive to embed code chunks. This is primarily useful for index pages, where you want to use embedded code to dynamically generate the <em>body</em> of the page - depending on what sections and links are available.</p>
</div>
<div class="section" id="the-template-file">
<h1><a class="toc-backref" href="#id17">The Template File</a></h1>
<p>You can specify a template file for every page and index - using the <tt class="docutils literal"><span class="pre">template</span></tt> value in the restindex. If none is specified it first tries <tt class="docutils literal"><span class="pre">template.txt</span></tt> in <strong>that</strong> <a class="footnote-reference" href="#id10" id="id5">[5]</a> directory first (even if the index is in an alternative directory using <tt class="docutils literal"><span class="pre">index-file</span></tt>).</p>
<p>If a template file is specified in the index-file, then the location must be specified relative to the directory the index-file is in.</p>
<p>If no template file is specified, and there is no 'template.txt' in the same directory as the index file, then the template for the directory above will be used. This means that if you have a 'template.txt' in your root directory it can be used for the whole site.</p>
</div>
<div class="section" id="note-about-macros">
<h1><a class="toc-backref" href="#id18">Note About Macros</a></h1>
<p>There is another way of calling simple functions from within templates. These are called macros. Macros allow you to use a shorthand for often-used text or HTML. Included is an example macro file (and supporting modules), It has macros for inserting smilies, colorizing Python files, acronyms, etc. You will need to modify it for your own sites, by putting the correct paths into the source code at least. See the page on <a class="reference external" href="macros.html">macros</a> for more details.</p>
</div>
<hr class="docutils" />
<div class="section" id="footnotes">
<h1><a class="toc-backref" href="#id19">Footnotes</a></h1>
<table class="docutils footnote" frame="void" id="id6" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>Or written to <tt class="docutils literal"><span class="pre">stdout</span></tt>.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id7" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id2">[2]</a></td><td>You can also specify 'global uservalues' at the command line or in the config file. These will be available to every page.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id8" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id3">[3]</a></td><td>See the Python <tt class="docutils literal"><span class="pre">time</span></tt> module. <a class="reference external" href="http://docs.python.org/lib/module-time.html">http://docs.python.org/lib/module-time.html</a></td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id9" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id4">[4]</a></td><td>These are different ways of representing the directory being rendered.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id10" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id5">[5]</a></td><td>By <em>that directory</em> - I mean the directory that the <tt class="docutils literal"><span class="pre">index.txt</span></tt> file is located in, and where probably most of the content will be located.</td></tr>
</tbody>
</table>
</div>
</div>
</div>
<div id="end">
<p><a href="#startcontent">Return to Top</a><br />
<small>Part of the <a href="http://www.voidspace.org.uk/python/rest2web/">rest2web Docs</a></small><br />
<small>Page last modified <strong>Mon Nov 20 00:12:12 2006</strong>.</small>
</p>
</div>
</div></td>
</tr>
<tr>
<td valign="top" align="left" width="25%">
<div id="left-column">
<div id="sidie">
<ul>
<li class="left-navheader-first">
<a href="index.html" class="left-navheader">Index Page</a>
</li>
<li class="left-navheader">Pages</li>
<li><a href="introduction.html">Introduction</a></li>
<li><a href="quickstart.html">Quickstart</a></li>
<li><a href="config_file.html">Config File</a></li>
<li><a href="tutorial.html">Tutorial</a></li>
<li><a href="command_line.html">Command Line</a></li>
<li><a href="force_mode.html">Force Mode</a></li>
<li><a href="templating.html">Templates</a></li>
<li><a href="restindex.html">restindex</a></li>
<li><a href="functions.html">Functions</a></li>
<li><a href="macros.html">Macros</a></li>
<li><a href="special_files.html">Special Files</a></li>
<li class="left-navheader">Sub Sections</li>
<li><a href="reference/index.html">Reference</a></li>
<li><a href="test_site/index.html">Test Site</a></li>
<li><a href="translation/index.html">Translation</a></li>
<li><a href="gallery_test/index.html">Gallery</a></li>
</ul>
</div>
<p class="sidieimg">
<a href="http://www.python.org">
<img src="images/logos/new_python.gif" width="88"
height="103" border="0" alt="Powered by Python" />
</a>
</p>
<p class="sidieimg">
<a href="http://sourceforge.net/donate/index.php?group_id=138579">
<img src="http://images.sourceforge.net/images/project-support.jpg" width="100"
height="32" border="0" alt="Support This Project" />
</a>
</p>
<p class="sidieimg">
<a href="http://www.voidspace.org.uk/python/rest2web/"><img
src="images/logos/rest2web140x62.gif" width="142" height="62"
alt="Site Built with rest2web" /></a><br />
</p>
</div>
</td>
</tr>
</table>
<hr />
<p class="sidieimg">
<a href="http://www.voidspace.org.uk/python/rest2web/"><img src="images/logos/rest2web200x80.gif" width="200" height="80" alt="Site Built with rest2web" /></a>
<a href="http://sourceforge.net"><img src="http://sourceforge.net/sflogo.php?group_id=138579&type=5" width="210" height="62" alt="SourceForge.net Logo" /></a>
<a href="http://www.opensource.org"><img src="images/logos/osi-certified-120x100.gif" width="120" height="100" alt="Certified Open Source" border="1" /></a>
</p>
<p class="sidieimg">
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
_uacct = "UA-203625-1";
urchinTracker();
</script>
</p>
<p class="sidieimg">
<a href="http://www.voidspace.org.uk/python/index.shtml"><img
src="images/logos/pythonbanner.gif" width="468" height="60"
alt="Python on Voidspace" /></a>
</p>
<div id="footer">
Copyright © Voidspace<br />Design by <a href="http://www.fuchsiashockz.co.uk">Fuchsiashockz</a> | <a href="http://validator.w3.org/check?uri=referer" title="Validate code as W3C XHTML 1.1 Strict Compliant">W3C XHTML 1.1</a> | <a href="http://jigsaw.w3.org/css-validator/check?uri=referer" title="Validate Style Sheet as W3C CSS 2.0 Compliant">W3C CSS 2.0</a>
</div>
</div>
</body>
</html>
|