From e36935c390bf289c41a07f742aad14dadf058927 Mon Sep 17 00:00:00 2001 From: Holger Schurig Date: Wed, 23 Jun 2010 13:10:11 +0200 Subject: [PATCH] doc template_make: finally documented how templates work --- in/plugins/template_mako.md | 141 +++++++++++++++++++++++++++++++++++- 1 file changed, 139 insertions(+), 2 deletions(-) diff --git a/in/plugins/template_mako.md b/in/plugins/template_mako.md index 45528bb..fff1cc9 100644 --- a/in/plugins/template_mako.md +++ b/in/plugins/template_mako.md @@ -1,6 +1,143 @@ -title: Web page template +title: Mako template linktitle: template_mako.py parent: Plugins ctime: 2009-06-26 +change: finally documented how templates work -TODO +This plugin uses the [[Mako template +library|http://www.makotemplates.org/]] to render the actual pages +during the "`pagetemplate`" [[hook|hooks]]. + += Configuration = + +== template == + +Name of the template file. Must be specified in "`webber.conf`", but +can be overriden, see "[[inheritance]]" and "[[pageformat]]". + + template: "default" + +Note that you don't need to add the "`.tmpl`" file suffix. + +== style_dir == + +Directory where templates (and often CSS files) reside. Defaults to +"`in/style`". + +== input_encoding and output_encoding == + +Name of the encoding for the input files (page files, templates etc) +and the output files (rendered HTML pages). Must be specified in +"`webber.conf`". + + input_encoding: "iso-8859-1" + output_encoding: "iso-8859-1" + += Template files = + +The "`*.tmpl`" files in the specified style directory can now utilize +the fill power of Mako. Here's an example of a rather minimal +template: + + + + + ${file.title | entity} + + % if len(keywords): + + % endif + % if len(description): + + % endif + + +

${file.title | entity}

+ ${body} + + + +== Example of template inheritance == + +However, be replacing "`${body}`" with a named make container, we can +use inheritance to modify the page body on a per-file basis. Add this +at the top of the file: + + <%def name="contents()">\ + ${body} + \ + ####################################################################### + +and replace "`${body}`" with: + + ${self.contents()} + +Now you can create a new template file, e.g. "`history.tmpl`" that +inherits from "`default.tmpl`" and add's a list of recently changed +files: + + <%inherit file="default.tmpl"/> + ####################################################################### + <%def name="contents()">\ + ${body} + <% + recently = get_recently() + %> + % if len(recently)>1: +

What's new?

+ % for page, link in recently: + % if page.mtime > page.ctime: + Modified ${format_date(page.mtime)}\ + % else: + Created ${format_date(page.ctime)}\ + % endif + : ${page.title | entity}
+ % endfor + % endif + \ + + + + +== Page attributes == + +As you migt have seen in the above example, you have access to various +objects and their members ("`${page.title}`"), variables ("`${body}`") +and functions ("`$format_date()`"). + +=== ${file} === + +This is the file object. TODO + +=== ${body} === + +This is the page body, as rendered by the [[hooks|hooks]] "`htmlize"` +and "`linkify`". + +=== ${rootpath} === + +This is the path from the current file to the top-level directory. You +can use this for relative links inside your document. + +Example: conside that the current rendered page is test/foo/bar.html. Then +"`${rootpath}`" is "`../../"`. So you can access your main index.html +file by "`${rootpath}index.html`". + +=== ${description} === + +That's the "`description:`" text from your [[page|pageformat]]. You +can use this in meta tags in your HTML header. + +=== ${keywords} === + +That's the "`keywords:`" text from your [[page|pageformat]]. You +can use this in meta tags in your HTML header. + +=== Functions marked with @set_function() === + +Any function marked with "`@set_function("name")`" can be used in the +template. Whatever text the function returns is put into the final +page. + +All functions are documented on the "[[functions]]" page. -- 2.39.2