dokuwiki api paragraphs

This section describes paragraph formatting using paragraph functions.

Simple paragraph functions

These are the basic paragraph 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.

p_open($style=NULL)

The function opens a new paragraph using the style with name $style. If $style is omitted then the standard style 'Text_20_body' will be used, also see file styles.xml. The function only opens a new paragraph if there is no paragraph opened already.

p_close()

The function closes a paragraph if any paragraph is open. If the function is called without an paragraph being open then it will have no effect. So the function can be called to make sure an eventually open paragraph is closed without fearing an error in case no paragraph is open.

---

preformatted($text)

The function opens a new paragraph using style Preformatted_20_Text, adds the $text and closes the paragraph immediately. Leading newlines are removed. An empty line at the end of $text is removed to. Linebreaks ("\n") are converted to "<text:line-break/>". Tabs ("\t") are converted to "<text:tab/>". Space are preserved by e.g. replacing 3 spaces with "<text:s text:c="3"/>".

---

_highlight($type, $text, $language=null)

The function opens a paragraph and inserts $text in it using GeSHi (also see https://www.dokuwiki.org/devel:geshi) for syntax highlighting. The paragraph is closed immediately. If $type is set to "file" then the style Source_20_File will be used, otherwise Source_20_Code will be used. If $language is set to NULL only preformatted text will be generated without syntax highlighting.

Code examples for simple paragraph functions

Generate a paragraph with style 'predefined'

The following code:

    $renderer->p_open('Preformatted_20_Text');
    $renderer->cdata('This is predefined text.');
    $renderer->p_close();

generates a paragraph with the content "This is predefined text" using the style named "Preformatted_20_Text".

Advanced paragraph functions

The advanced paragraph functions are not called from the DokuWiki parser. They can be used to create paragraphs with your own styles.

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

The function opens a paragraph using CSS. The style created for the paragraph 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 p. $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. Use p_close() to close the paragraph.

_odtParagraphOpenUseProperties($properties)

The function opens a paragraph using $properties. $properties is supposed to be an array with key value pairs in which the key corresponds to CSS property names. Use p_close() to close the paragraph.

Code examples for advanced paragraph functions

Creating a paragraph with a border

The following code:

    // Make sure to close any eventually open paragraph first!
    $renderer->p_close();
    $properties ['border'] = '2pt dashed black';
    $renderer->_odtParagraphOpenUseProperties($properties);

    $renderer->cdata('This is text in a border.');

    $renderer->p_close();

generates "This is text in a border." with a black dashed border around it.

Creating a paragraph in a border using CSS directly

The following code:

    // Make sure to close any eventually open paragraph first!
    $renderer->p_close();
    $renderer->_odtParagraphOpenUseCSS(NULL, 'style="border:2pt dashed blue;"');

    $renderer->cdata('This is text in a border.');

    $renderer->p_close();

generates "This is text in a border." with a blue dashed border around it.

_odtParagraphOpenUseCSS also uses imported CSS code

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

.myclass {
    margin-left: 5cm;
}

In such a case the following code:

    // Make sure to close any eventually open paragraph first!
    $renderer->p_close();
    $renderer->_odtParagraphOpenUseCSS(NULL, 'class="myclass" style="border:2pt dashed blue;"');

    $renderer->cdata('This is text in a border.');

    $renderer->p_close();

generates "This is text in a border." with a blue dashed border around it. Additionally the paragraph is indented by 5 centimeters because of the left margin set in .myclass.