← Back to branch summary

~ubuntu-branches/ubuntu/quantal/cubictemp/quantal

« back to all changes in this revision

Viewing changes to doc/subs.html

  • Committer: Bazaar Package Importer
  • Author(s): Mohammed Adnène Trojette
  • Date: 2009-03-21 19:56:53 UTC
  • mfrom: (3.1.1 squeeze)
  • Revision ID: james.westby@ubuntu.com-20090321195653-2tj0jz2itpfyxt8y
Tags: 2.0-1
http://bugs.debian.org/516162
* New upstream release.
* debian/control:
   + bump Standards-Version to 3.8.1.
   + bump debhelper compatibility to 7.
   + add ${misc:Depends} to Depends.
* Remove unneeded patches and patching system accordingly.
* Update debian/copyright: licence is now MIT.
* Update packaging to prevent FTBFS. Thanks to Josselin
  Mouette. (Closes: #516162)

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/subs.html
1
 
 
2
 
 
3
 
<html>
4
 
        <head>
5
 
                <LINK REL=StyleSheet HREF="./style/style.css" TYPE="text/css">
6
 
        </head>
7
 
                <a href="templates.html">&lt;--previous</a> |
8
 
        <a href="./index.html">contents</a> |
9
 
        <a href="subs/xss.html">next--&gt;</a> 
10
 
 
11
 
        <hr>
12
 
        <body>
13
 
        <h1>Substitutions</h1>
14
 
                
15
 
<h2> Introduction to Substitutions </h2>
16
 
 
17
 
<p> From the examples in the previous section, it may seem that text between the 
18
 
 
19
 
<code class="template">@!...!@</code> 
20
 
 
21
 
delimiters is treated simply as an identifier to be replaced. This is not the
22
 
case - Cubictemp actually evaluates everything between the delimiters as an
23
 
expression in the namespace specified by the keyword arguments. It is the
24
 
result of this evaluation that is converted to a string with the built-in
25
 
function <code>repr</code>, and placed in the template. This means that
26
 
<i>any</i> valid Python expression which can be evaluated in the indicated
27
 
namespace can appear in a substitution tag.</p>
28
 
 
29
 
<p>To illustrate this, take a look at the template below:</p>
30
 
 
31
 
<code class="template">
32
 
        @!foo!@ times two is @!foo*2!@<br>
33
 
        @!foo!@ squared is @!foo*foo!@<br>
34
 
</code>
35
 
 
36
 
<p> ...and this accompanying code snippet: </p>
37
 
 
38
 
 
39
 
<code>
40
 
        <pre><div class="pythoncode"><font color="#C00000">import</font> <font color="#000000">cubictemp</font>
41
 
 
42
 
<font color="#000000">temp</font> <font color="#0000C0">=</font> <font color="#000000">cubictemp</font><font color="#0000C0">.</font><font color="#000000">File</font><font color="#0000C0">(</font><font color="#004080">"template"</font><font color="#0000C0">,</font> <font color="#000000">foo</font><font color="#0000C0">=</font><font color="#0080C0">3</font><font color="#0000C0">)</font>
43
 
<font color="#C00000">print</font> <font color="#000000">temp</font><font color="#000000"></font></div></pre>
44
 
</code>
45
 
 
46
 
<p> The output here would look like this:</p>
47
 
 
48
 
 
49
 
<code class="output">
50
 
        3 times two is 6<br>
51
 
        3 squared is 9<br>
52
 
</code>
53
 
 
54
 
<p> Similarly, if <code>"foo"</code> happened to be a dictionary, we could extract
55
 
a value from it inside a template like this:</p>
56
 
 
57
 
<code class="template">
58
 
                @!foo["bar"]!@ 
59
 
</code>
60
 
 
61
 
<p> And if <code>"foo"</code> was an object with an attribute <code>"x"</code>,
62
 
we could reference the attribute by saying:</p>
63
 
 
64
 
<code class="template">
65
 
                @!foo.x!@ 
66
 
</code>
67
 
 
68
 
<p> This ability to evaluate expressions makes Cubictemp templates very
69
 
powerful and expressive. </p>
70
 
 
71
 
<h2> A word about expressions and statements</h2>
72
 
 
73
 
<p> At this point it is important to distinguish between Python expressions and
74
 
Python statements. Python <b>expressions</b> can conveniently be thought of as
75
 
anything that can be on the right-hand-side of an equals sign. Arithmetic
76
 
operators, boolen operators, parentheses for grouping, method/function calls
77
 
and object instantiation are all valid components of expressions. Python
78
 
<b>statements</b>, on the other hand, include things like "if", "while",
79
 
"print" and variable assignment. CubicTemp allows <i>only expressions </i> in
80
 
places where it evaluates Python code. This is a deliberate choice - limiting
81
 
templates to expressions ensures that all program logic lives in the Python
82
 
program files where they belong. This enforces a hard separation between code
83
 
and presentation, making it easier to unit-test, change and maintain the
84
 
application as a whole.</p>
85
 
 
86
 
 
87
 
 
88
 
        </body>
89
 
        <hr>
90
 
    <table width="100%">
91
 
        <tr>
92
 
            <td>
93
 
                        <a href="templates.html">&lt;--previous</a> |
94
 
        <a href="./index.html">contents</a> |
95
 
        <a href="subs/xss.html">next--&gt;</a> 
96
 
 
97
 
            </td>
98
 
            <td align="right">
99
 
                (11/16/04)
100
 
            </td>
101
 
        </tr>
102
 
    </table>
103
 
        <center> Cubictemp v0.4 Manual </center>
104
 
</html>
 
1
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 
2
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta  content="text/html; charset=utf-8" http-equiv="Content-Type"/><link  href="static/yui/fonts/fonts.css" type="text/css" rel="StyleSheet"/>
 
3
<link  href="static/yui/reset/reset.css" type="text/css" rel="StyleSheet"/>
 
4
<link  href="static/yui/grids/grids.css" type="text/css" rel="StyleSheet"/>
 
5
<link  href="static/style.css" type="text/css" rel="StyleSheet"/>
 
6
<link  href="static/yui/base/base.css" type="text/css" rel="StyleSheet"/>
 
7
<link  href="docstyle.css" type="text/css" rel="StyleSheet"/>
 
8
<link  href="syntax.css" type="text/css" rel="StyleSheet"/>
 
9
 
 
10
 
 
11
<title>Cubictemp Manual - Tags</title></head><body><div class="yui-t2" id="doc3"><div style="" id="hd"><h1> Cubictemp - Tags </h1></div><div id="bd"><div id="yui-main"><div style="" class="yui-b"><h1>Tags and Expressions</h1><p>Cubictemp evaluates expressions between tag delimiters as expressions in the
 
12
specified namespace. The result is converted to a string, and placed in the
 
13
rendered template. There are two flavours of delimiters - <strong>escaped</strong>:</p><pre class="output">
 
14
@!...!@
 
15
</pre><p>and <strong>unescaped</strong>:</p><pre class="output">
 
16
$!...!$
 
17
</pre><p>In Python, an <b>expression</b> can be thought of as anything that can be
 
18
assigned to a variable. Arithmetic operators, boolean operators, parentheses
 
19
for grouping, method/function calls, object instantiation and conditional
 
20
expressions are all valid components of expressions. Python <b>statements</b>
 
21
include things like <b>while</b>, <b>print</b>, variable assignment and full
 
22
<b>if</b> blocks.  Cubictemp allows <b>only expressions</b> in subtitution
 
23
tags. </p><h3> Example</h3><p>Template:</p><pre class="output">
 
24
@!foo!@ times two is @!foo*2!@
 
25
@!foo!@ squared is @!foo*foo!@
 
26
@!"yes" if (1==2) else "no"!@
 
27
key is @!mydict["key"]!@
 
28
</pre><p>Code:</p><div class="highlight"><pre><span class="k">import</span> <span class="nn">cubictemp</span>
 
29
<span class="k">print</span> <span class="n">cubictemp</span><span class="o">.</span><span class="n">File</span><span class="p">(</span>
 
30
            <span class="s">&quot;template&quot;</span><span class="p">,</span>
 
31
            <span class="n">foo</span><span class="o">=</span><span class="mf">3</span><span class="p">,</span>
 
32
            <span class="n">mydict</span><span class="o">=</span><span class="nb">dict</span><span class="p">(</span><span class="n">key</span><span class="o">=</span><span class="s">&quot;value&quot;</span><span class="p">)</span>
 
33
        <span class="p">)</span>
 
34
</pre></div><p>Output:</p><pre class="output">
 
35
3 times two is 6
 
36
3 squared is 9
 
37
no
 
38
key is value
 
39
</pre><h1>Escaping</h1><p>In an escaped substitution tag, the &amp;, &lt;, &gt;, &quot;, &#146;
 
40
characters are converted to their corresponding HTML escape sequences.  Always
 
41
use the <b>escaped</b> substitution syntax if you can. When you really need to
 
42
place HTML in a substitution tag, make sure you carefully evaluate the
 
43
application context to make sure that users cannot inject malicious data.</p><h3> Example</h3><div class="highlight"><pre><span class="k">import</span> <span class="nn">cubictemp</span>
 
44
<span class="k">print</span> <span class="n">cubictemp</span><span class="o">.</span><span class="n">Template</span><span class="p">(</span>
 
45
        <span class="s">&quot;@!x!@ $!x!$&quot;</span><span class="p">,</span>
 
46
        <span class="n">x</span> <span class="o">=</span> <span class="s">&quot;&lt;H1&gt;foo&lt;/H1&gt;&quot;</span>
 
47
    <span class="p">)</span>
 
48
</pre></div><p>... will print:</p><div class="highlight"><pre><span class="nt">&lt;H1&gt;</span>foo<span class="nt">&lt;/H1&gt;</span> <span class="ni">&amp;lt;</span>H1<span class="ni">&amp;gt;</span>foo<span class="ni">&amp;lt;</span>/H1<span class="ni">&amp;gt;</span>
 
49
</pre></div><h1>Controlling Escaping</h1><p>Sometimes, it is handy to be able to construct objects that bypass Cubictemp's
 
50
escaping mechanism, regardless of the type of tag in which they occur. You can
 
51
signal this to cubictemp by giving the object a special attribute
 
52
<b>_cubictemp_unescaped</b> which evaluates to true.</p><p><strong>Template</strong>, <strong>File</strong>, and named block objects all have a
 
53
<b>_cubictemp_unescaped</b> attribute, so none of these objects will be escaped
 
54
when referenced inside an escaped tag.</p></div></div><div style="" class="yui-b"><div class="pageindex"><ul><li class="inactive"><a href="index.html">Introduction</a></li><li class="active"><a href="subs.html">Tags</a></li><li class="inactive"><a href="blocks.html">Blocks</a></li><li class="inactive"><a href="processors.html">Processors</a></li><li class="inactive"><a href="api.html">API</a></li><li class="inactive"><a href="admin.html">Administrivia</a></li></ul></div></div></div><div style="" id="ft"><p>Copyright Nullcube 2008</p></div></div></body></html>
 
 
b'\\ No newline at end of file'