Mercurial > genshi > mirror
comparison doc/builder.txt @ 226:4d8a9e03b23d trunk
Add reStructuredText documentation files.
| author | cmlenz |
|---|---|
| date | Fri, 08 Sep 2006 08:44:31 +0000 |
| parents | |
| children | 84168828b074 |
comparison
equal
deleted
inserted
replaced
| 225:16d7b5db7ef4 | 226:4d8a9e03b23d |
|---|---|
| 1 .. -*- mode: rst; encoding: utf-8 -*- | |
| 2 | |
| 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>! |