1 | | {{{ |
2 | | #!rst |
3 | | ================================== |
4 | | Generating Markup Programmatically |
5 | | ================================== |
6 | | |
7 | | Markup provides a ``builder`` module which lets you generate markup from Python |
8 | | code using a very simple syntax. The main entry point to the ``builder`` module |
9 | | is the ``tag`` object (which is actually an instance of the ``ElementFactory`` |
10 | | class). You should rarely (if ever) need to directly import and use any of the |
11 | | other classes in the ``builder`` module. |
12 | | |
13 | | |
14 | | .. contents:: Contents |
15 | | :depth: 2 |
16 | | .. sectnum:: |
17 | | |
18 | | |
19 | | Creating Elements |
20 | | ================= |
21 | | |
22 | | Elements can be created through the `tag` object using attribute access, for |
23 | | example:: |
24 | | |
25 | | >>> from markup.builder import tag |
26 | | >>> doc = tag.p('Some text and ', tag.a('a link', href='http://example.org/'), '.') |
27 | | >>> doc |
28 | | <Element "p"> |
29 | | |
30 | | This produces an ``Element`` instance which can be further modified to add child |
31 | | nodes and attributes. This is done by “calling” the element: positional |
32 | | arguments are added as child nodes (alternatively, the ``append`` method can be |
33 | | used for that purpose), whereas keywords arguments are added as attributes:: |
34 | | |
35 | | >>> doc(tag.br) |
36 | | <Element "p"> |
37 | | >>> print doc |
38 | | <p>Some text and <a href="http://example.org/">a link</a>.<br/></p> |
39 | | |
40 | | If an attribute name collides with a Python keyword, simply append an underscore |
41 | | to the name:: |
42 | | |
43 | | >>> doc(class_='intro') |
44 | | <Element "p"> |
45 | | >>> print doc |
46 | | <p class="intro">Some text and <a href="http://example.org/">a link</a>.<br/></p> |
47 | | |
48 | | As shown above, an ``Element`` can easily be directly rendered to XML text by |
49 | | printing it or using the Python ``str()`` function. This is basically a |
50 | | shortcut for converting the ``Element`` to a stream and serializing that |
51 | | stream:: |
52 | | |
53 | | >>> stream = doc.generate() |
54 | | >>> stream |
55 | | <markup.core.Stream object at 0x72d230> |
56 | | >>> print stream |
57 | | <p class="intro">Some text and <a href="http://example.org/">a link</a>.<br/></p> |
58 | | |
59 | | |
60 | | Creating Fragments |
61 | | ================== |
62 | | |
63 | | The ``tag`` object also allows creating “fragments”, which are basically lists |
64 | | of nodes (elements or text) that don't have a parent element. This can be useful |
65 | | for creating snippets of markup that are attached to a parent element later (for |
66 | | example in a template). Fragments are created by calling the ``tag`` object: |
67 | | |
68 | | >>> fragment = tag('Hello, ', tag.em('word'), '!') |
69 | | >>> fragment |
70 | | <Fragment> |
71 | | >>> print fragment |
72 | | Hello, <em>world</em>! |
73 | | }}} |
| 1 | [[Include(trunk/doc/builder.txt)]] |