python/lib/django-1.5/django/template/__init__.py

   1 """
   2 This is the Django template system.
   3
   4 How it works:
   5
   6 The Lexer.tokenize() function converts a template string (i.e., a string containing
   7 markup with custom template tags) to tokens, which can be either plain text
   8 (TOKEN_TEXT), variables (TOKEN_VAR) or block statements (TOKEN_BLOCK).
   9
  10 The Parser() class takes a list of tokens in its constructor, and its parse()
  11 method returns a compiled template -- which is, under the hood, a list of
  12 Node objects.
  13
  14 Each Node is responsible for creating some sort of output -- e.g. simple text
  15 (TextNode), variable values in a given context (VariableNode), results of basic
  16 logic (IfNode), results of looping (ForNode), or anything else. The core Node
  17 types are TextNode, VariableNode, IfNode and ForNode, but plugin modules can
  18 define their own custom node types.
  19
  20 Each Node has a render() method, which takes a Context and returns a string of
  21 the rendered node. For example, the render() method of a Variable Node returns
  22 the variable's value as a string. The render() method of an IfNode returns the
  23 rendered output of whatever was inside the loop, recursively.
  24
  25 The Template class is a convenient wrapper that takes care of template
  26 compilation and rendering.
  27
  28 Usage:
  29
  30 The only thing you should ever use directly in this file is the Template class.
  31 Create a compiled template object with a template_string, then call render()
  32 with a context. In the compilation stage, the TemplateSyntaxError exception
  33 will be raised if the template doesn't have proper syntax.
  34
  35 Sample code:
  36
  37 >>> from django import template
  38 >>> s = u'<html>{% if test %}<h1>{{ varvalue }}</h1>{% endif %}</html>'
  39 >>> t = template.Template(s)
  40
  41 (t is now a compiled template, and its render() method can be called multiple
  42 times with multiple contexts)
  43
  44 >>> c = template.Context({'test':True, 'varvalue': 'Hello'})
  45 >>> t.render(c)
  46 u'<html><h1>Hello</h1></html>'
  47 >>> c = template.Context({'test':False, 'varvalue': 'Hello'})
  48 >>> t.render(c)
  49 u'<html></html>'
  50 """
  51
  52 # Template lexing symbols
  53 from django.template.base import (ALLOWED_VARIABLE_CHARS, BLOCK_TAG_END,
  54     BLOCK_TAG_START, COMMENT_TAG_END, COMMENT_TAG_START,
  55     FILTER_ARGUMENT_SEPARATOR, FILTER_SEPARATOR, SINGLE_BRACE_END,
  56     SINGLE_BRACE_START, TOKEN_BLOCK, TOKEN_COMMENT, TOKEN_TEXT, TOKEN_VAR,
  57     TRANSLATOR_COMMENT_MARK, UNKNOWN_SOURCE, VARIABLE_ATTRIBUTE_SEPARATOR,
  58     VARIABLE_TAG_END, VARIABLE_TAG_START, filter_re, tag_re)
  59
  60 # Exceptions
  61 from django.template.base import (ContextPopException, InvalidTemplateLibrary,
  62     TemplateDoesNotExist, TemplateEncodingError, TemplateSyntaxError,
  63     VariableDoesNotExist)
  64
  65 # Template parts
  66 from django.template.base import (Context, FilterExpression, Lexer, Node,
  67     NodeList, Parser, RequestContext, Origin, StringOrigin, Template,
  68     TextNode, Token, TokenParser, Variable, VariableNode, constant_string,
  69     filter_raw_string)
  70
  71 # Compiling templates
  72 from django.template.base import (compile_string, resolve_variable,
  73     unescape_string_literal, generic_tag_compiler)
  74
  75 # Library management
  76 from django.template.base import (Library, add_to_builtins, builtins,
  77     get_library, get_templatetags_modules, get_text_list, import_library,
  78     libraries)
  79
  80 __all__ = ('Template', 'Context', 'RequestContext', 'compile_string')