1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.3.9: http://docutils.sourceforge.net/" />
<title>Generating Markup Programmatically</title>
<link rel="stylesheet" href="style/edgewall.css" type="text/css" />
</head>
<body>
<div class="document" id="generating-markup-programmatically">
<h1 class="title">Generating Markup Programmatically</h1>
<!-- -*- mode: rst; encoding: utf-8 -*- -->
<p>Genshi provides a <tt class="docutils literal"><span class="pre">builder</span></tt> module which lets you generate markup from Python
code using a very simple syntax. The main entry point to the <tt class="docutils literal"><span class="pre">builder</span></tt> module
is the <tt class="docutils literal"><span class="pre">tag</span></tt> object (which is actually an instance of the <tt class="docutils literal"><span class="pre">ElementFactory</span></tt>
class). You should rarely (if ever) need to directly import and use any of the
other classes in the <tt class="docutils literal"><span class="pre">builder</span></tt> module.</p>
<div class="contents topic" id="contents">
<p class="topic-title first"><a name="contents">Contents</a></p>
<ul class="auto-toc simple">
<li><a class="reference" href="#creating-elements" id="id1" name="id1">1 Creating Elements</a></li>
<li><a class="reference" href="#creating-fragments" id="id2" name="id2">2 Creating Fragments</a></li>
</ul>
</div>
<div class="section" id="creating-elements">
<h1><a name="creating-elements">1 Creating Elements</a></h1>
<p>Elements can be created through the <cite>tag</cite> object using attribute access, for
example:</p>
<pre class="literal-block">
>>> from genshi.builder import tag
>>> doc = tag.p('Some text and ', tag.a('a link', href='http://example.org/'), '.')
>>> doc
<Element "p">
</pre>
<p>This produces an <tt class="docutils literal"><span class="pre">Element</span></tt> instance which can be further modified to add child
nodes and attributes. This is done by “calling” the element: positional
arguments are added as child nodes (alternatively, the <tt class="docutils literal"><span class="pre">append</span></tt> method can be
used for that purpose), whereas keywords arguments are added as attributes:</p>
<pre class="literal-block">
>>> doc(tag.br)
<Element "p">
>>> print doc
<p>Some text and <a href="http://example.org/">a link</a>.<br/></p>
</pre>
<p>If an attribute name collides with a Python keyword, simply append an underscore
to the name:</p>
<pre class="literal-block">
>>> doc(class_='intro')
<Element "p">
>>> print doc
<p class="intro">Some text and <a href="http://example.org/">a link</a>.<br/></p>
</pre>
<p>As shown above, an <tt class="docutils literal"><span class="pre">Element</span></tt> can easily be directly rendered to XML text by
printing it or using the Python <tt class="docutils literal"><span class="pre">str()</span></tt> function. This is basically a
shortcut for converting the <tt class="docutils literal"><span class="pre">Element</span></tt> to a stream and serializing that
stream:</p>
<pre class="literal-block">
>>> stream = doc.generate()
>>> stream
<genshi.core.Stream object at 0x72d230>
>>> print stream
<p class="intro">Some text and <a href="http://example.org/">a link</a>.<br/></p>
</pre>
</div>
<div class="section" id="creating-fragments">
<h1><a name="creating-fragments">2 Creating Fragments</a></h1>
<p>The <tt class="docutils literal"><span class="pre">tag</span></tt> object also allows creating “fragments”, which are basically lists
of nodes (elements or text) that don't have a parent element. This can be useful
for creating snippets of markup that are attached to a parent element later (for
example in a template). Fragments are created by calling the <tt class="docutils literal"><span class="pre">tag</span></tt> object:</p>
<pre class="literal-block">
>>> fragment = tag('Hello, ', tag.em('word'), '!')
>>> fragment
<Fragment>
>>> print fragment
Hello, <em>world</em>!
</pre>
</div>
</div>
</body>
</html>
|