Templayer 1.5.1 Reference

Template classes

function Template [back to top]

class Template(object) [back to top]

__call__ = format(self, layer_name, **args)

__init__(self, name, from_string=False, auto_reload='never', allow_degenerate=False, encoding='utf_8')

name -- template file name or file-like object
from_string -- if True treat name as a string containing the
               template data instead of a file to read from
auto_reload -- if the template has not been checked in this
               many seconds then check it and reload if there
               are any changes.  If 'never' only load the 
               template file once.
 
               Checking and reloading is done by the 
               start_file() function.
               
               Ignored if from_string is True or if name is a 
               file-like object.
allow_degenerate -- If True then template is allowed to not
               have a {contents}...{/contents} block.  In this
               case the entire file is available as a layer
               called '*'.  eg. l = tmpl.format('*', ...)
encoding -- encoding for template file

finalize(self, value)

Return unwrapped value as a string.
 
Override this function to reverse wrapping applied before
sending to the output file.

format(self, layer_name, **args)

Return a layer with slots filled by args.
 
self.format(...) and self(...) are equivalent.

format_header_footer(self, **args)

Returns header and footer with slots filled by args.

layer(self, name)

Return the complete layer named name as a string.

layer_split(self, name)

Return the layer named name split on SLOT_MARKs.

missing_slot(self, names, layer)

Called when one or more slots are not found in a layer.

post_process(self, value)

Returns wrapped value.
 
Override to wrap processed text in order to mark it as 
having been processed.

pre_process(self, key, value)

Returns key, filtered/escaped value.
 
Override this function to provide escaping or filtering of
text sent from the module user.

reload_template(self)

Reload the template data from the template file.

set_template_data(self, tmpl)

Parse and store the template data passed.

start_file(self, file=None, encoding='utf_8')

Return a FileWriter object that uses this template.
 
file -- file object or None to use sys.stdout.
 
If self.auto_reload is not None this function will first 
check and reload the template file if it has changed.

template_file_changed(self)

Return True if the template file has been modified since
the last time it was loaded.

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

function HTMLTemplate [back to top]

class HTMLTemplate(Template) [back to top]

Method resolution order:

HTMLTemplate

Template

object

finalize(self, value)

Unwrap RawHTML object value for output.

post_process(self, value)

Wrap value in RawHTML object.

pre_process(self, key, value)

Use expand_html_markup to process value.

__call__ = format(self, layer_name, **args)

Return a layer with slots filled by args.
 
self.format(...) and self(...) are equivalent.

__init__(self, name, from_string=False, auto_reload='never', allow_degenerate=False, encoding='utf_8')

name -- template file name or file-like object
from_string -- if True treat name as a string containing the
               template data instead of a file to read from
auto_reload -- if the template has not been checked in this
               many seconds then check it and reload if there
               are any changes.  If 'never' only load the 
               template file once.
 
               Checking and reloading is done by the 
               start_file() function.
               
               Ignored if from_string is True or if name is a 
               file-like object.
allow_degenerate -- If True then template is allowed to not
               have a {contents}...{/contents} block.  In this
               case the entire file is available as a layer
               called '*'.  eg. l = tmpl.format('*', ...)
encoding -- encoding for template file

format(self, layer_name, **args)

Return a layer with slots filled by args.
 
self.format(...) and self(...) are equivalent.

format_header_footer(self, **args)

Returns header and footer with slots filled by args.

layer(self, name)

Return the complete layer named name as a string.

layer_split(self, name)

Return the layer named name split on SLOT_MARKs.

missing_slot(self, names, layer)

Called when one or more slots are not found in a layer.

reload_template(self)

Reload the template data from the template file.

set_template_data(self, tmpl)

Parse and store the template data passed.

start_file(self, file=None, encoding='utf_8')

Return a FileWriter object that uses this template.
 
file -- file object or None to use sys.stdout.
 
If self.auto_reload is not None this function will first 
check and reload the template file if it has changed.

template_file_changed(self)

Return True if the template file has been modified since
the last time it was loaded.

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

Output classes

function FileWriter [back to top]

class FileWriter(object) [back to top]

__init__(self, file, template, encoding='utf_8')

file -- output stream or None to use sys.stdout
template -- template object for generating this file
 
This constructor is usually not called directly.  Use
template.start_file() to create a FileWriter instead.

close(self)

Close all child layers and flush the output to the output 
stream.  This function must be called to generate a complete
file.
 
Returns the file object where output was sent.

flush(self)

Flush as much output as possible to the output stream.

open(self, **args)

Return a new layer representing the content between the
header and footer.  Use keyword arguments to fill the
slots in the header and footer.

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

function Layer [back to top]

class Layer(object) [back to top]

__init__(self, template, header, footer)

template -- template object for generating this layer
header -- text before the content of this layer
footer -- text after the content of this layer
 
This constructor should not be called directly.  Use
the open() function in a FileWriter or the open_layer()
function in another Layer object to create a new Layer.

close(self)

Close this layer and return its output.
 
This function should not be called directly.  Use the
close() function in the FileWriter object instead.

close_child(self)

If we have an open child layer close it and add its
output to our own.

flush(self)

Flush as much output as possible and return it.
 
This function should not be called directly.  Use the
flush() function in the FileWriter object instead.

open_layer(self, layer, **args)

layer -- name of layer in the template to open
Use keyword arguments to fill this layer's slots.
 
open_layer( layer name, ** args ) -> child Layer object
 
open a layer as a child of this one, filling its slots with
values from args

write(self, text)

text -- text or markup as interpreted by the template

write_layer(self, layer, **args)

layer -- name of layer in the template to write
Use keyword arguments to fill this layer's slots.

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

Django integration

function django_form [back to top]

django_form(form, errors=True, join_errors=<function <lambda>>)

Converts a django FormWrapper object to a dictionary that
can be used by Templayer.  Each field is rendered into a
%form.NAME% slot.
 
If errors is True then this function will also render
errors into %form.NAME.errors% slots.
 
When there is more than one error on a single field the
errors will be joined with the join_errors function.
The default join_errors function puts a newline between each
error.
 
eg:
If tmpl is an HTMLTemplate object with a {form_layer} layer
and form is a FormWrapper object with username and password
fields, then this code will fill the {form_layer} layer's 
%title%, %form.username%, %form.password%, 
%form.username.errors% and %form.password.errors% slots:
 
tmpl.format('form_layer', title="hello", **django_form(form))

function django_template_loader [back to top]

django_template_loader(template_name, template_dirs=None)

This function should be included in settings.TEMPLATE_LOADERS when
using the django_template decorator.
 
eg:
TEMPLATE_LOADERS += ['templayer.django_template_loader']

function django_template [back to top]

django_template(tmpl, template_name)

This is a decorator for functions you want to make behave like 
standard Django templates.  When django_template_loader is 
included in settings.TEMPLATE_LOADERS Django will find the 
decorated function when looking for template_name.
 
tmpl is the Templayer template object that will be used to create
the file layer passed to the decorated function.
 
The decorated function must have a signature like:
@templayer.django_template(tmpl, "appname/somepage.html")
def mock_template(fwriter, context, optional1, optional2 ...)
 
Where fwriter is a new FileWriter object, context is a context
instance and all parameters that follow will have their values
copied from the context based on the name of the parameters.
 
The function must call fwriter.open(..) to render the page then 
return the fwriter object (or None) to send it to the client.  
fwriter.close() is called automatically.  Other objects returned 
or exceptions raised will be passed through to Django.

function django_view [back to top]

django_view(tmpl)

This is a decorator for Django view functions that will handle
creation of the file layer object from the template tmpl.
 
The function must have a signature like:
@templayer.django_view(tmpl)
def decorated_view(fwriter, request, ...)
 
fwriter is the new FileWriter object and the rest of the parameters
are the same as what was passed to the view.  
 
The function must call fwriter.open(..) to render the page then 
return the fwriter object (or None) to send it to the client.  
fwriter.close() is called automatically.  Other objects returned 
or exceptions raised will be passed through to Django.

function get_django_template [back to top]

get_django_template(name, auto_reload='debug', allow_degenerate=False, encoding='utf_8')

Use Django's template loading machinery to create an
HTMLTemplate object.
 
auto_reload -- when set to 'debug' will auto-reload only when 
        settings.DEBUG is set to True

Utility functions

function html_url_encode [back to top]

html_url_encode(text, query=False)

text -- text to be included as part of a URL
query -- if True use "+" instead ot "%20" for spaces

function html_href [back to top]

html_href(link, value)

Return '<a href="link">value</a>'.
 
Neither link nor value is escaped by this function.

function html_target [back to top]

html_target(target, caption)

Return '<a name="target">caption</a>'.
 
Neither target nor caption is escaped by this function.

function html_escape [back to top]

html_escape(text)

text -- text to be escaped for inclusion within HTML.

HTML Markup (yes, markup language markup)

function join [back to top]

join(markup_list, separator)

HTML Markup like markup_list.join(separator)

function pluralize [back to top]

pluralize(count, sigular_content, plural_content)

HTML Markup (singular_content if count==1 else plural_content)

function urljoin [back to top]

urljoin(head, tail)

HTML Markup join safe url head with unsafe tail

function href [back to top]

href(link, content)

HTML Markup <a href="link">content</a>

function target [back to top]

target(name)

HTML Markup <a name="name"></a>

function BR [back to top]

BR(count=1)

HTML Markup <br/> * count

function P [back to top]

P(content='')

HTML Markup <p>content</p>

function I [back to top]

I(content)

HTML Markup <i>content</i>

function B [back to top]

B(content)

HTML Markup <b>content</b>

function U [back to top]

U(content)

HTML Markup <u>content</u>

function entity [back to top]

entity(entity)

HTML Markup &entity;

function expand_html_markup [back to top]

expand_html_markup(v)

Return an HTML string based on markup v.
 
HTML markup is expanded recursively. Each of the content
values below are passed to expand_html_markup again before 
applying the operation on the right:
 
string or unicode string    ->  HTML-escaped version of string
[content1, content2, ...]   ->  concatenate content1, content2, ...
('join',list,sep)     ->  join items in list with seperator sep
('pluralize',count,singular_content,plural_content)
                      ->  if count == 1 use singular_content,
                          otherwise use plural_content
('urljoin',head,tail) ->  join safe url head with unsafe url-ending tail
('href',link,content) ->  HTML href to link wrapped around content
('target',name)       ->  HTML target name
('br',)               ->  HTML line break
('br',count)          ->  HTML line break * count
('p',)                ->  HTML paragraph break
('p',content)         ->  HTML paragraph
('i',content)         ->  italics
('b',content)         ->  bold
('u',content)         ->  underline
('&',entity)          ->  HTML entity (entity has no & or ;)
RawHTML(value)        ->  value unmodified

function RawHTML [back to top]

class RawHTML(object) [back to top]

__init__(self, value)

value -- segment of HTML as a string

__repr__(self)

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)