Mercurial > genshi > genshi-test
comparison doc/xml-templates.txt @ 429:6911f3c5a7e8
Updated docs for code blocks and changed error handling.
| author | cmlenz |
|---|---|
| date | Thu, 22 Mar 2007 17:00:09 +0000 |
| parents | ec05506d1bda |
| children | ff7c72b52fb2 |
comparison
equal
deleted
inserted
replaced
| 428:540dd825d072 | 429:6911f3c5a7e8 |
|---|---|
| 63 print stream.render('xhtml') | 63 print stream.render('xhtml') |
| 64 | 64 |
| 65 | 65 |
| 66 .. _`expressions`: | 66 .. _`expressions`: |
| 67 | 67 |
| 68 -------------------- | 68 ------------------------------------ |
| 69 Template Expressions | 69 Template Expressions and Code Blocks |
| 70 -------------------- | 70 ------------------------------------ |
| 71 | 71 |
| 72 Python_ expressions can be used in text and attribute values. An expression is | 72 Python_ expressions can be used in text and attribute values. An expression is |
| 73 substituted with the result of its evaluation against the template data. | 73 substituted with the result of its evaluation against the template data. |
| 74 Expressions need to prefixed with a dollar sign (``$``) and usually enclosed in | 74 Expressions need to prefixed with a dollar sign (``$``) and usually enclosed in |
| 75 curly braces (``{…}``). | 75 curly braces (``{…}``). |
| 92 >>> from genshi.template import MarkupTemplate | 92 >>> from genshi.template import MarkupTemplate |
| 93 >>> tmpl = MarkupTemplate('<em>${dict.foo}</em>') | 93 >>> tmpl = MarkupTemplate('<em>${dict.foo}</em>') |
| 94 >>> print tmpl.generate(dict={'foo': 'bar'}) | 94 >>> print tmpl.generate(dict={'foo': 'bar'}) |
| 95 <em>bar</em> | 95 <em>bar</em> |
| 96 | 96 |
| 97 Another difference is that you can access variables that are not defined, and | 97 Because there are two ways to access either attributes or items, expressions |
| 98 won't get a ``NameError`` exception:: | 98 do not raise the standard ``AttributeError`` or ``IndexError`` exceptions, but |
| 99 | 99 rather an exception of the type ``UndefinedError``. The same kind of error is |
| 100 >>> from genshi.template import TextTemplate | 100 raised when you try to access a top-level variable that is not in the context |
| 101 >>> tmpl = TextTemplate('${doh}') | 101 data. |
| 102 >>> print tmpl.generate() | 102 |
| 103 <BLANKLINE> | 103 |
| 104 | 104 .. _`code blocks`: |
| 105 You **will** however get a ``NameError`` if you try to call an undefined | 105 |
| 106 variable, or do anything else with it, such as accessing its attributes. If you | 106 Code Blocks |
| 107 need to know whether a variable is defined, you can check its type against the | 107 =========== |
| 108 ``Undefined`` class, for example in a `py:if`_ directive:: | 108 |
| 109 | 109 XML templates also support full Python code blocks using the ``<?python ?>`` |
| 110 >>> from genshi.template import TextTemplate | 110 processing instruction:: |
| 111 >>> tmpl = TextTemplate('${type(doh) is Undefined}') | 111 |
| 112 >>> print tmpl.generate() | 112 <div> |
| 113 True | 113 <?python |
| 114 from genshi.builder import tag | |
| 115 def greeting(name): | |
| 116 return tag.b('Hello, %s!' % name') ?> | |
| 117 ${greeting('world')} | |
| 118 </div> | |
| 119 | |
| 120 This will produce the following output:: | |
| 121 | |
| 122 <div> | |
| 123 <b>Hello, world!</b> | |
| 124 </div> | |
| 125 | |
| 126 Code blocks can import modules, define classes and functions, and basically do | |
| 127 anything you can do in normal Python code. What code blocks can *not* do is to | |
| 128 produce content that is included directly in the generated page. | |
| 129 | |
| 130 .. note:: Using the ``print`` statement will print to the standard output | |
| 131 stream, just as it does for other Python code in your application. | |
| 132 | |
| 133 This feature is not supposed to encourage mixing application code into | |
| 134 templates, which is generally considered bad design. If you're using many code | |
| 135 blocks, that me be a sign that you should move such code into separate Python | |
| 136 modules. | |
| 137 | |
| 138 | |
| 139 Built-in Functions & Types | |
| 140 ========================== | |
| 141 | |
| 142 The following functions and types are available by default in template code, in | |
| 143 addition to the standard built-ins that are available to all Python code. | |
| 144 | |
| 145 ``defined(name)`` | |
| 146 ----------------- | |
| 147 | |
| 148 This function determines whether a variable of the specified name exists in | |
| 149 the context data, and returns ``True`` if it does. | |
| 150 | |
| 151 ``value_of(name, default=None)`` | |
| 152 -------------------------------- | |
| 153 | |
| 154 This function returns the value of the variable with the specified name if | |
| 155 such a variable is defined, and returns the value of the ``default`` | |
| 156 parameter if no such variable is defined. | |
| 157 | |
| 158 ``Markup(text)`` | |
| 159 ---------------- | |
| 160 | |
| 161 The ``Markup`` type marks a given string as being safe for inclusion in markup, | |
| 162 meaning it will *not* be escaped in the serialization stage. Use this with care, | |
| 163 as not escaping a user-provided string may allow malicious users to open your | |
| 164 web site to cross-site scripting attacks. | |
| 114 | 165 |
| 115 | 166 |
| 116 .. _`directives`: | 167 .. _`directives`: |
| 117 | 168 |
| 118 ------------------- | 169 ------------------- |