# Templayer 1.5.1 Reference

Templayer Home Page / Tutorial / Reference

Template classes Template HTMLTemplate Output classes FileWriter Layer Django integration django_form django_template_loader django_template django_view get_django_template Utility functions html_url_encode html_href html_target html_escape | HTML Markup (yes, markup language markup) join pluralize urljoin href target BR P I B U entity expand_html_markup RawHTML

## Template classes

### function Template [back to top]

### class Template(object) [back to top]

Methods defined here:

__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.
  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.`

Data descriptors defined here:

__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

Methods defined here:

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.`

Methods inherited from Template:

__call__ = format(self, layer_name, **args)
  `Return a layer with slots filled by args.
  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.
  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.`

Data descriptors inherited from Template:

__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]

Methods defined here:

__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.`

Data descriptors defined here:

__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]

Methods defined here:

__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.`

Data descriptors defined here:

__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]

Methods defined here:

__init__(self, value)
  `value -- segment of HTML as a string`

__repr__(self)

Data descriptors defined here:

__dict__
  `dictionary for instance variables (if defined)`

__weakref__
  `list of weak references to the object (if defined)`