← Back to branch summary

~ubuntu-branches/ubuntu/raring/genshi/raring-proposed

« back to all changes in this revision

Viewing changes to doc/builder.html

  • Committer: Bazaar Package Importer
  • Author(s): Arnaud Fontaine
  • Date: 2007-04-16 17:49:03 UTC
  • mfrom: (1.1.2 upstream)
  • Revision ID: james.westby@ubuntu.com-20070416174903-x2p3n9g890v18d0m
Tags: 0.4-1
* New upstream release.
* Remove useless python-markup transition package.
* Add Provides against python-markup.
* Add doc-base.
* Add depends against python-xml.
* Add suggests to python-setuptools.

Show diffs side-by-side

added added

removed removed

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