Package org.apache.tapestry5

## Interface MarkupWriter

- All Known Implementing Classes:
    `MarkupWriterImpl`

      public interface MarkupWriter

  An interface used by objects, such as Tapestry components, that need to render themselves as some form of XML markup. A markup writer maintains the idea of a current element. Attributes are added to the current element, and new text and elements are placed inside the current element. In this way, the markup writer maintains a facade that XML markup is generated as a stream, even though the implementation builds a kind of DOM tree. The DOM tree can be also be manipulated. This solves a number of problems from Tapestry 4 (and earlier) where random access to the DOM was desired and had to be simulated through complex buffering.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addListener​(MarkupWriterListener listener)` | Adds a markup writer listener that will be notified as elements are started and ended.
    `Element` | `attributeNS​(java.lang.String namespace, java.lang.String attributeName, java.lang.String attributeValue)` | Creates an attribute within the namespace for the current element.
    `void` | `attributes​(java.lang.Object... namesAndValues)` | Adds a series of attributes and values.
    `void` | `cdata​(java.lang.String content)` | Adds parsed character content.
    `void` | `comment​(java.lang.String text)` | Adds an XML comment.
    `Element` | `defineNamespace​(java.lang.String namespace, java.lang.String namespacePrefix)` | Defines a namespace for the currently active element.
    `Element` | `element​(java.lang.String name, java.lang.Object... attributes)` | Begins a new element as a child of the current element.
    `Element` | `elementNS​(java.lang.String namespace, java.lang.String elementName)` | Starts an element within the given namespace.
    `Element` | `end()` | Ends the current element.
    `Document` | `getDocument()` | Returns the Document into which this writer creates elements or other nodes.
    `Element` | `getElement()` | Returns the currently active element.
    `void` | `removeListener​(MarkupWriterListener listener)` | Removes a previously added listener.
    `void` | `toMarkup​(java.io.PrintWriter writer)` | Converts the collected markup into an markup stream (according to rules provided by the `Document`'s `MarkupModel`).
    `void` | `write​(java.lang.String text)` | Writes the text as a child of the current element.
    `void` | `writef​(java.lang.String format, java.lang.Object... args)` | Writes a formatted string.
    `void` | `writeRaw​(java.lang.String text)` | Writes raw text, text with existing markup that should be passed through the client without change.

- - ### Method Detail

    - #### element

          Element element​(java.lang.String name,
                          java.lang.Object... attributes)

      Begins a new element as a child of the current element. The new element becomes the current element. The new Element is returned and can be directly manipulated (possibly at a later date). Optionally, attributes for the new element can be specified directly.
      Parameters:
        `name` - the name of the element to create
        `attributes` - an even number of values, alternating names and values
      Returns:
        the new DOM Element node
      See Also:
        `attributes(Object[])`

    - #### end

          Element end()

      Ends the current element. The new current element will be the parent element. Returns the new current element (which may be null when ending the root element for the document).

    - #### write

          void write​(java.lang.String text)

      Writes the text as a child of the current element.

    - #### writef

          void writef​(java.lang.String format,
                      java.lang.Object... args)

      Writes a formatted string.

    - #### writeRaw

          void writeRaw​(java.lang.String text)

      Writes raw text, text with existing markup that should be passed through the client without change. This can be useful when the markup is read from an external source (a file or a database) and is simply to be included.
      Parameters:
        `text` -
      See Also:
        `Raw`

    - #### comment

          void comment​(java.lang.String text)

      Adds an XML comment. The text should be just the comment content, the comment delimiters will be provided. Note that, as of Tapestry 5.2., no extra whitespace is added (previous releases added a space around the text).

    - #### cdata

          void cdata​(java.lang.String content)

      Adds parsed character content. This will be enclosed in a CDATA block if supported. When not supported, this is the same as `write(String)`.
      Parameters:
        `content` - pre-parsed content

    - #### attributes

          void attributes​(java.lang.Object... namesAndValues)

      Adds a series of attributes and values. Null values are quietly skipped. If a name already has a value, then the new value is ignored.

    - #### toMarkup

          void toMarkup​(java.io.PrintWriter writer)

      Converts the collected markup into an markup stream (according to rules provided by the `Document`'s `MarkupModel`). The markup stream is sent to the writer.

    - #### getDocument

          Document getDocument()

      Returns the Document into which this writer creates elements or other nodes.

    - #### getElement

          Element getElement()

      Returns the currently active element.

    - #### defineNamespace

          Element defineNamespace​(java.lang.String namespace,
                                  java.lang.String namespacePrefix)

      Defines a namespace for the currently active element. The namespace URI will be mapped to the provided namespace prefix within the Element.
      Parameters:
        `namespace` - the namespace URI
        `namespacePrefix` - the prefix for elements and attributes associated with the namespace (may be the empty string for the default namespace)
      Returns:
        the currently active element

    - #### elementNS

          Element elementNS​(java.lang.String namespace,
                            java.lang.String elementName)

      Starts an element within the given namespace. The correct namespace prefix will be identified and used. Must be balanced by a call to `end()`.
      Parameters:
        `namespace` - URI containing the element
        `elementName` - name of the element within the namespace
      Returns:
        the new Element

    - #### attributeNS

          Element attributeNS​(java.lang.String namespace,
                              java.lang.String attributeName,
                              java.lang.String attributeValue)

      Creates an attribute within the namespace for the current element.
      Parameters:
        `namespace` - URI containing the element
        `attributeName` - name of the attribute within the namespace
        `attributeValue` - the value for the attribute
      Returns:
        the currently active element

    - #### addListener

          void addListener​(MarkupWriterListener listener)

      Adds a markup writer listener that will be notified as elements are started and ended.

    - #### removeListener

          void removeListener​(MarkupWriterListener listener)

      Removes a previously added listener.