dokuwiki api spans

This section describes text formatting using span functions.

Simple span functions

These are the basic span functions with a predefined style. These are also called for basic DokuWiki rendering and therefore the function declarations need to match the class Doku_Renderer.

strong_open()

The function opens a span for bold text. Also see DokuWiki basic text formatting.

strong_close()

The function closes a bold text span.

---

emphasis_open()

The function opens a span for italic text. Also see DokuWiki basic text formatting.

emphasis_close()

The function closes a italic text span.

---

underline_open()

The function opens a span for underlined text. Also see DokuWiki basic text formatting.

underline_close()

The function closes a underlined text span.

---

monospace_open()

The function opens a span for monospace text. Also see DokuWiki basic text formatting.

monospace_close()

The function closes a monospace text span.

---

subscript_open()

The function opens a span for subscript text. Also see DokuWiki basic text formatting.

subscript_close()

The function closes a subscript text span.

---

superscript_open()

The function opens a span for superscript text. Also see DokuWiki basic text formatting.

superscript_close()

The function closes a superscript text span.

---

deleted_open()

The function opens a span for deleted/strike-through text. Also see DokuWiki basic text formatting.

deleted_close()

The function closes a deleted/strike-through text span.

Code examples for simple span functions

Generating strong text

The following code:

    $renderer->cdata('This is ');
    $renderer->strong_open();
    $renderer->cdata('bold');
    $renderer->strong_close();
    $renderer->cdata('text.');

generates "This is bold text."

Combining styles

Nested function calls can be used to generate a combination of text styles. The following code:

    $renderer->cdata('This is ');
    $renderer->strong_open();
    $renderer->emphasis_open();
    $renderer->cdata('bold and italic');
    $renderer->emphasis_close();
    $renderer->strong_close();
    $renderer->cdata('text.');

generates "This is bold and italic text.". This also works correct if the opening and closing sequence does not go from outside to inside and back:

    $renderer->cdata('This is ');
    $renderer->strong_open();
    $renderer->emphasis_open();
    $renderer->cdata('bold and italic');
    $renderer->strong_close();
    $renderer->emphasis_close();
    $renderer->cdata('text.');

But e.g. omitting a close causes an error. The following code:

    $renderer->cdata('This is ');
    $renderer->strong_open();
    $renderer->emphasis_open();
    $renderer->cdata('bold and italic');
    //$renderer->strong_close();
    $renderer->emphasis_close();
    $renderer->cdata('text.');

generates an broken/invalid ODT document which can not be opened.

Advanced span functions

The advanced span functions are not called for the standard basic DokuWiki text formatting. They can be used to create text formatting styles that are not covered by the simple span functions.

_odtSpanOpen($style_name)

The function opens a span using the ODT style with name $style_name.

_odtSpanOpenUseCSS($element=NULL, $attributes=NULL, cssimportnew $import=NULL)

The function opens a span using CSS. The text formatting created by the span will be as corresponding for a HTML element $element with attributes $attributes. $element only needs to be specified if the HTML element which shall be used for CSS selector matching shall be something different than span. $import holds the imported CSS code to use. This parameter is usually omitted. In that case the configured and imported DokuWiki CSS template code is used.

_odtSpanOpenUseProperties($properties)

The function opens a span using $properties. $properties is supposed to be an array with key value pairs in which the key corresponds to CSS property names.

_odtSpanClose()

The function closes a span.

---

generateSpansfromHTMLCode($HTMLCode)

The function will add the content in $HTMLCode and at the same time it converts all HTML spans found in $HTMLCode to ODT spans. This is a standalone function, DO NOT call _odtSpanClose() for it.

Code examples for advanced span functions

Creating colored text with _odtSpanOpenUseProperties

The following code:

    $renderer->cdata('This is ');

    $properties ['color'] = 'blue';
    $renderer->_odtSpanOpenUseProperties($properties);

    $renderer->cdata('blue');

    $renderer->_odtSpanClose();

    $renderer->cdata(' text.');

generates "This is blue text." with the word blue having a blue text color.

Creating colored text with _odtSpanOpenUseCSS

The following code:

    $renderer->cdata('This is ');

    $renderer->_odtSpanOpenUseCSS(NULL, 'style="color: red;"');

    $renderer->cdata('red');

    $renderer->_odtSpanClose();

    $renderer->cdata(' text.');

generates "This is red text." with the word red having a red text color.

_odtSpanOpenUseCSS also uses imported CSS code

Let's assume that in the DokuWiki CSS template code the following rule exists:

.myclass {
    background-color: blue;
}

In such a case the following code:

    $renderer->cdata('This is ');

    $renderer->_odtSpanOpenUseCSS(NULL, 'class="myclass" style="color: red;"');

    $renderer->cdata('red');

    $renderer->_odtSpanClose();

    $renderer->cdata(' text.');

generates "This is red text." with the word red having a red text color and a blue background-color.

Easy span creation with generateSpansfromHTMLCode

Example 1

The following code:

    $renderer->generateSpansfromHTMLCode('<u><strong>This is bold and underlined text.</strong></u>');
    $renderer->generateSpansfromHTMLCode('<strong><u>This is bold and underlined text.</strong></u>');

generates the text "This is bold and underlined text." two times. In both cases the text will be bold and underlined.

Example 2

The following code:

    $renderer->generateSpansfromHTMLCode('<span style="color:red;background-color:blue;">This is some more text.</span>');

generates the text "This is some more text." with a red color on a blue background.

Example 3

The following code:

    $renderer->generateSpansfromHTMLCode('<strong>This is <div>bold</div> text.</strong>');

generates the text This is <div>bold</div> text.". The div element is not a span and will be converted to plain text to prevent the document from being broken. Unbalanced span tags will also be converted to plain text.