Edgewall Software

Changes between Version 5 and Version 6 of MarkupBuilder


Ignore:
Timestamp:
Sep 8, 2006, 10:09:57 AM (18 years ago)
Author:
cmlenz
Comment:

Move to reStructuredText

Legend:

Unmodified
Added
Removed
Modified

  • MarkupBuilder

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