File: node7.html

package info (click to toggle)
cherrypy 0.10-1
links: PTS
area: main
in suites: sarge
size: 10,324 kB
ctags: 1,759
sloc: python: 14,411; sh: 6,915; perl: 2,472; makefile: 76
file content (439 lines) | stat: -rw-r--r-- 14,086 bytes
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>5. Templating languages: CHTL and CGTL</title>
<META NAME="description" CONTENT="5. Templating languages: CHTL and CGTL">
<META NAME="keywords" CONTENT="tut">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link rel="STYLESHEET" href="tut.css" type='text/css'>
<link rel="first" href="tut.html">
<link rel="contents" href="contents.html" title="Contents">

<LINK REL="next" HREF="node8.html">
<LINK REL="previous" HREF="node6.html">
<LINK REL="up" HREF="tut.html">
<LINK REL="next" HREF="node8.html">
<meta name='aesop' content='information'>
</head>
<body>
<DIV CLASS="navigation">
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td><A HREF="node6.html"><img src="../icons/previous.gif"
  border="0" height="32"
  alt="Previous Page" width="32"></A></td>
<td><A HREF="tut.html"><img src="../icons/up.gif"
  border="0" height="32"
  alt="Up One Level" width="32"></A></td>
<td><A HREF="node8.html"><img src="../icons/next.gif"
  border="0" height="32"
  alt="Next Page" width="32"></A></td>
<td align="center" width="100%">CherryPy Tutorial</td>
<td><A HREF="node2.html"><img src="../icons/contents.gif"
  border="0" height="32"
  alt="Contents" width="32"></A></td>
<td><img src="../icons/blank.gif"
  border="0" height="32"
  alt="" width="32"></td>
<td><img src="../icons/blank.gif"
  border="0" height="32"
  alt="" width="32"></td>
</tr></table>
<b class="navlabel">Previous:</b> <a class="sectref" HREF="node6.html">4. Creating a first</A>
<b class="navlabel">Up:</b> <a class="sectref" HREF="tut.html">CherryPy Tutorial</A>
<b class="navlabel">Next:</b> <a class="sectref" HREF="node8.html">6. Views, functions and</A>
<br><hr>
</DIV>
<!--End of Navigation Panel-->
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>

<UL CLASS="ChildLinks">
<LI><A href="node7.html#SECTION007100000000000000000">5.1 Tags</a>
<UL>
<LI><A href="node7.html#SECTION007110000000000000000">5.1.1 py-eval</a>
<LI><A href="node7.html#SECTION007120000000000000000">5.1.2 py-attr</a>
<LI><A href="node7.html#SECTION007130000000000000000">5.1.3 py-exec and py-code</a>
<LI><A href="node7.html#SECTION007140000000000000000">5.1.4 py-if and py-else</a>
<LI><A href="node7.html#SECTION007150000000000000000">5.1.5 py-for</a>
</ul>
<LI><A href="node7.html#SECTION007200000000000000000">5.2 Putting it together</a>
</ul>
<!--End of Table of Child-Links-->
<HR>

<H1><A NAME="SECTION007000000000000000000">
5. Templating languages: CHTL and CGTL</A>
</H1>

<P>
CherryPy comes with TWO templating languages. They are very similar to each other, but they are used in
different situations. They have been designed to be very easy to use, and yet very powerful.

<UL>
<LI><b>CherryPy HTML Templating Language (CHTL)</b>: It is used to produce HTML output. It has been designed so that
HTML editors keep the dynamic informations in the page. This way, webdesigners can edit the pages using their
favorite HTML editor without losing the information that the developers put in them. The trick is to hide code
in the attributes of HTML tags.
</LI>
<LI><b>CherryPy Generic Templating Language (CGTL)</b>: It is used to produce non-HTML output (for instance
Javascript, CSS, XML, ...). It is very close to CHTL, except that we cannot use HTML tags to hide the code, and the
syntax is a bit simpler. <b>If you don't use any HTML editor to create your pages, then you should probably use
CGTL only as it is simpler than CHTL</b>.
</LI>
</UL>

<P>
Note that you can also use other templating languages if you want (for instance, there is a HowTo that explains how to use Cheetah), or you can just use plain python to generate your pages.

<P>

<H1><A NAME="SECTION007100000000000000000">
5.1 Tags</A>
</H1>
Both languages use only 6 tags: <code>py-eval</code>, <code>py-attr</code>, <code>py-exec</code>, <code>py-code</code>, <code>py-if</code> (with <code>py-else</code>)
and <code>py-for</code>.

<P>
All tags are used the same way: <code>CherryPyTag="Some Python code"</code>. For instance:
<div class="verbatim"><pre>
py-eval="2*2"
py-exec="a=1"
py-if="2==0"
py-for="i in range(10)"
...
</pre></div>

<P>
If you want to use double-quotes inside the python code, you need to escape them using a backslash, like this:
<div class="verbatim"><pre>
py-eval="'I love \"cherry pies\"'"
</pre></div>

<P>
Let's see what each of these tags is used for:

<P>

<H2><A NAME="SECTION007110000000000000000">
5.1.1 py-eval</A>
</H2>
This tag is used to evaluate a Python expression, like this:
<div class="verbatim"><pre>
Hello, the sum is &lt;py-eval="1+2+3"&gt;
</pre></div>

<P>
This line will be rendered as:
<div class="verbatim"><pre>
Hello, the sum is 6
</pre></div>

<P>
What happens is that CherryPy first evaluates the expression (using <var>eval</var>) and then uses <var>str</var> on the result to convert it to a string.

<P>
All the CGTL tags can be closed using <var>/&gt;</var> or / &gt;, like this:
<div class="verbatim"><pre>
&lt;py-eval="'abcd' * 2" /&gt;
&lt;py-eval="'Hello, %s' % name"/&gt;
</pre></div>

<P>
In its CHTL form, the <var>py-eval</var> tag can be used with any pair of opening/closing tags, like this:

<P>
<div class="verbatim"><pre>
&lt;span class=myClass py-eval="2*3"&gt;&lt;/span&gt;
&lt;a href="myHref" py-eval="'Click here'"&gt;&lt;/a&gt;
&lt;u py-eval="'I\'m with an underline'"&gt;&lt;/u&gt;
...
</pre></div>

<P>
If you don't want to use any HTML tag around the expression, the trick is to use the <code>&lt;div&gt;</code> HTML tag:
<div class="verbatim"><pre>
This is a long string with a &lt;div py-eval="'variable'"&gt;&lt;/div&gt; in it
</pre></div>

<P>

<H2><A NAME="SECTION007120000000000000000">
5.1.2 py-attr</A>
</H2>
This tag is like <code>py-eval</code>, except it's used for HTML tag attributes. The way it is used is as follows:
<div class="verbatim"><pre>
&lt;td py-attr="'red'" bgColor=""&gt;
</pre></div>
This will be rendered as
<div class="verbatim"><pre>
&lt;td bgColor="red"&gt;
</pre></div>
Note that this is equivalent to:
<div class="verbatim"><pre>
&lt;td bgColor="&lt;py-eval="'red'"&gt;"&gt;
</pre></div>
But the first syntax is preferred.

<P>

<H2><A NAME="SECTION007130000000000000000">
5.1.3 py-exec and py-code</A>
</H2>
These tags are used to execute some Python code. <code>py-exec</code> is used to execute one line of Python code, and
<code>py-code</code> is used to execute blocks of Python code.
For instance, the following code:
<div class="verbatim"><pre>
&lt;py-exec="a=2"&gt;
&lt;py-code="
    if a==2:
        b=1
    else:
        b==2
"&gt;
b equals &lt;py-eval="b"&gt;
</pre></div>
Will be rendered as:
<div class="verbatim"><pre>
b equals 1
</pre></div>

<P>
In the CHTL syntax, both tags have to be embedded in &lt;div&gt; and &lt;/div&gt; tags as follow:
<div class="verbatim"><pre>
&lt;div py-exec="a=2"&gt;&lt;/div&gt;
&lt;div py-code="
    if a==2:
        b=1
    else:
        b=2
"&gt;&lt;/div&gt;
</pre></div>

<P>
If you want to render some data inside the Python code, you must append it to the <var>_page</var> variable:
<div class="verbatim"><pre>
&lt;html&gt;&lt;body&gt;
    Integers from 0 to 9:
    &lt;py-code="
        for i in range(10):
            _page.append("%s "%i)
    "&gt;
&lt;/body&gt;&lt;/html&gt;
</pre></div>

<P>
This will be rendered as:
<div class="verbatim"><pre>
&lt;html&gt;&lt;body&gt;
    Integers from 0 to 9:
    0 1 2 3 4 5 6 7 8 9
&lt;/body&gt;&lt;/html&gt;
</pre></div>

<P>

<H2><A NAME="SECTION007140000000000000000">
5.1.4 py-if and py-else</A>
</H2>
These tags are used like <code>if</code> and <code>else</code> in Python. The syntax is as follows:
<div class="verbatim"><pre>
&lt;py-if="1==1"&gt;
    OK
&lt;/py-if&gt;&lt;py-else&gt;
    Not OK
&lt;/py-else&gt;
</pre></div>

<P>
This will be rendered as
<div class="verbatim"><pre>
OK
</pre></div>

<P>
Note that if there is an <code>else</code> clause, the <code>&lt;div py-else&gt;</code> tag must follow the <code>&lt;/div&gt;</code> tag
closing the <code>&lt;div py-if</code> tag, with no significant characters in between (ie: only separators are allowed)

<P>
The CHTL equivalent is:
<div class="verbatim"><pre>
&lt;div py-if="1==1"&gt;
    OK
&lt;/div&gt;
&lt;div py-else&gt;
    Not OK
&lt;/div&gt;
</pre></div>

<P>

<H2><A NAME="SECTION007150000000000000000">
5.1.5 py-for</A>
</H2>
This tag is used like <code>for</code> in Python. The syntax is as follows:
<div class="verbatim"><pre>
&lt;py-for="i in range(10)"&gt;
    &lt;py-eval="i"&gt;
&lt;/py-for&gt;
</pre></div>
This will be rendered as
<div class="verbatim"><pre>
0 1 2 3 4 5 6 7 8 9
</pre></div>

<P>
Note that you can loop over a list of tuples:
<div class="verbatim"><pre>
&lt;py-for="i,j in [(0,0), (0,1), (1,0), (1,1)]"&gt;
    &lt;py-eval="i+j"&gt;
&lt;/py-for&gt;
</pre></div>
This will be rendered as
<div class="verbatim"><pre>
0 1 1 2
</pre></div>

<P>
The CGTL equivalent is:
<div class="verbatim"><pre>
&lt;div py-for="i,j in [(0,0), (0,1), (1,0), (1,1)]"&gt;
    &lt;div py-eval="i+j"&gt;&lt;/div&gt;
&lt;/div&gt;
</pre></div>

<P>
In a <var>py-for</var> loop, CherryPy sets two handy special variables for you: <var>_index</var> and <var>_end</var>. The former
is an integer containing the current number of iterations (from 0 to n-1). The latter contains the total number of
iteration minus one.

<P>
For instance, if you want to display a list with the first item in bold and the last item underlined, you can use
the following code:
<div class="verbatim"><pre>
&lt;py-exec="myList=[1,5,3,2,5,4,5]"&gt;
&lt;py-for="item in myList"&gt;
    &lt;py-if="_index==0"&gt;&lt;b py-eval="item"&gt;&lt;/b&gt;
    &lt;/py-if&gt;&lt;py-else&gt;
        &lt;py-if="_index==_end"&gt;&lt;u py-eval="item"&gt;&lt;/u&gt;
        &lt;/py-if&gt;&lt;py-else&gt;&lt;py-eval="item"&gt;&lt;/py-else&gt;
        &lt;/div&gt;
    &lt;/py-else&gt;
&lt;/py-for&gt;
</pre></div>
This will be rendered as:
<div class="verbatim"><pre>
&lt;b&gt;1&lt;/b&gt; 5 3 2 5 4 &lt;u&gt;5&lt;/u&gt;
</pre></div>

<P>
In the next section, we'll see how to use all these tags together...

<P>

<H1><A NAME="SECTION007200000000000000000">
5.2 Putting it together</A>
</H1>

<P>
We are going to make a web page that displays a table with all HTML colors.
Edit the Hello.cpy file and change it to:

<P>
<div class="verbatim"><pre>
CherryClass Root:
mask:
    def index(self):
        &lt;html&gt;&lt;body&gt;
            &lt;a py-attr="request.base+'/webColors'" href=""&gt;
                Click here to see a nice table with all web colors
            &lt;/a&gt;
        &lt;/body&gt;&lt;/html&gt;
    def webColors(self):
        &lt;html&gt;&lt;body&gt;
            &lt;py-exec="codeList=['00', '33', '66', '99', 'CC', 'FF']"&gt;
            &lt;table border=1&gt;
            &lt;py-for="r in codeList"&gt;
                &lt;py-for="g in codeList"&gt;
                    &lt;tr&gt;
                        &lt;py-for="b in codeList"&gt;
                            &lt;py-exec="color='#%s%s%s'%(r,g,b)"&gt;
                            &lt;td py-attr="color" bgColor="" py-eval="'&amp;nbsp;&amp;nbsp;'+color+'&amp;nbsp;'"&gt;&lt;/td&gt;
                        &lt;/py-for&gt;
                    &lt;/tr&gt;
                &lt;/py-for&gt;
            &lt;/py-for&gt;
        &lt;/body&gt;&lt;/html&gt;
</pre></div>

<P>
Recompile the file, restart the server and refresh the page in your browser. Click on the link and you should see
a nice table with all web colors.

<P>
How does it work ?

<P>
The <code>webColors</code> method is a pretty straight forward use of the CHTL tags.
One more interesting line is:
<div class="verbatim"><pre>
&lt;a py-attr="request.base+'/webColors'" href=""&gt;
</pre></div>

<P>
<var>request</var> is a global variable set by CherryPy for each request of a client. It is an instance of a class with
several variables. One of them is called <code>base</code> and contains the base URL of the website (in our case: <a class="url" href="http://localhost:8000">http://localhost:8000</a>). So,
the line
<div class="verbatim"><pre>
&lt;a py-attr="request.base+'/webColors'" href=""&gt;
</pre></div>
will be rendered as:
<div class="verbatim"><pre>
&lt;a href="http://localhost:8000/webColors"&gt;
</pre></div>
This also tells us that when the browser requests the URL <a class="url" href="http://localhost:8000/webColors">http://localhost:8000/webColors</a>, the <var>webColors</var> method
of the <var>Root</var> class gets called.

<P>
In the next chapter, we'll learn how to use views, functions and when we should use them...

<P>

<DIV CLASS="navigation">
<p><hr>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td><A HREF="node6.html"><img src="../icons/previous.gif"
  border="0" height="32"
  alt="Previous Page" width="32"></A></td>
<td><A HREF="tut.html"><img src="../icons/up.gif"
  border="0" height="32"
  alt="Up One Level" width="32"></A></td>
<td><A HREF="node8.html"><img src="../icons/next.gif"
  border="0" height="32"
  alt="Next Page" width="32"></A></td>
<td align="center" width="100%">CherryPy Tutorial</td>
<td><A HREF="node2.html"><img src="../icons/contents.gif"
  border="0" height="32"
  alt="Contents" width="32"></A></td>
<td><img src="../icons/blank.gif"
  border="0" height="32"
  alt="" width="32"></td>
<td><img src="../icons/blank.gif"
  border="0" height="32"
  alt="" width="32"></td>
</tr></table>
<b class="navlabel">Previous:</b> <a class="sectref" HREF="node6.html">4. Creating a first</A>
<b class="navlabel">Up:</b> <a class="sectref" HREF="tut.html">CherryPy Tutorial</A>
<b class="navlabel">Next:</b> <a class="sectref" HREF="node8.html">6. Views, functions and</A>
<hr>
<span class="release-info">Release 0.10, documentation updated on 19 March 2004.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>