Mercurial > genshi > mirror

annotate doc/builder.txt @ 386:c66370dfc41b trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Unit test fixes for Python 2.3.
author cmlenz
date Mon, 11 Dec 2006 11:13:35 +0000
parents 2682dabbcd04
children
rev   line source
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
1 .. -*- mode: rst; encoding: utf-8 -*-
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
2
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
3 ==================================
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
4 Generating Markup Programmatically
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
5 ==================================
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
6
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
7 Genshi provides a ``builder`` module which lets you generate markup from Python
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
8 code using a very simple syntax. The main entry point to the ``builder`` module
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
9 is the ``tag`` object (which is actually an instance of the ``ElementFactory``
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
10 class). You should rarely (if ever) need to directly import and use any of the
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
11 other classes in the ``builder`` module.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
12
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
13
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
14 .. contents:: Contents
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
15 :depth: 2
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
16 .. sectnum::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
17
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
18
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
19 Creating Elements
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
20 =================
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
21
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
22 Elements can be created through the `tag` object using attribute access, for
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
23 example::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
24
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
25 >>> from genshi.builder import tag
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
26 >>> doc = tag.p('Some text and ', tag.a('a link', href='http://example.org/'), '.')
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
27 >>> doc
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
28 <Element "p">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
29
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
30 This produces an ``Element`` instance which can be further modified to add child
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
31 nodes and attributes. This is done by “calling” the element: positional
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
32 arguments are added as child nodes (alternatively, the ``append`` method can be
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
33 used for that purpose), whereas keywords arguments are added as attributes::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
34
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
35 >>> doc(tag.br)
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
36 <Element "p">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
37 >>> print doc
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
38 <p>Some text and <a href="http://example.org/">a link</a>.<br/></p>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
39
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
40 If an attribute name collides with a Python keyword, simply append an underscore
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
41 to the name::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
42
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
43 >>> doc(class_='intro')
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
44 <Element "p">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
45 >>> print doc
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
46 <p class="intro">Some text and <a href="http://example.org/">a link</a>.<br/></p>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
47
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
48 As shown above, an ``Element`` can easily be directly rendered to XML text by
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
49 printing it or using the Python ``str()`` function. This is basically a
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
50 shortcut for converting the ``Element`` to a stream and serializing that
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
51 stream::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
52
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
53 >>> stream = doc.generate()
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
54 >>> stream
382
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 235
diff changeset
55 <genshi.core.Stream object at ...>
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
56 >>> print stream
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
57 <p class="intro">Some text and <a href="http://example.org/">a link</a>.<br/></p>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
58
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
59
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
60 Creating Fragments
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
61 ==================
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
62
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
63 The ``tag`` object also allows creating “fragments”, which are basically lists
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
64 of nodes (elements or text) that don't have a parent element. This can be useful
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
65 for creating snippets of markup that are attached to a parent element later (for
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
66 example in a template). Fragments are created by calling the ``tag`` object::
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
67
382
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 235
diff changeset
68 >>> fragment = tag('Hello, ', tag.em('world'), '!')
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
69 >>> fragment
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
70 <Fragment>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
71 >>> print fragment
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
72 Hello, <em>world</em>!
Copyright (C) 2012-2017 Edgewall Software