StringParser_BBCode class documentation

8. Paragraph handling

8.1 General

With the help of this class there is the possibility to automatically detect paragraphs and enclose them with the corresponding HTML tags. For example could the following text:

This is the first paragraph of a long text! This is the second paragraph of a long text!

automatically be converted to the following HTML code:

<p>This is the first paragraph of a long text!</p> <p>This is the second paragraph of a long text!</p>

If no BBCodes are presend in the text this undertaking is trivial and could be implemented with a simple function. It becomes difficult if BBCodes are opened inside of a paragraph and closed in the next.

It is possible to influence the class how it detects paragraphs and outputs them. For this there is the method setParagraphHandlingParameters:

void setParagraphHandlingParameters (string $detect_string, string $start_tag, string $end_tag);

$detect_string
The string that is to be searched for.
$start_tag
The start tag that is to be used when the output is done.
$end_tag
The end tag that is to be used when the output is done.

The standard settings are:

$bbcode->setParagraphHandlingParameters ("\n\n", "<p>, "</p>");

If one is content with these standard settings it is not necessary to call this method.

8.2 Activating paragraph handling

Paragraph handling is disabled by default. Paragraphs that are written directly in the text (inside the so-called root element) and paragraphs that occur inside BBCodes may be replaced. To active paragraph handling for paragraphs that occur inside the root element it is necessary to call the method setRootParagraphHandling:

$bbcode->setRootParagraphHandling (true);

To replace paragraphs inside a BBCode it is necessary to set a flag for this code:

$bbcode->setCodeFlag ('*', 'paragraphs', true);

Here the paragraph handling would be activated inside the [*] element.

8.3 Further possibilities

Normally, if a BBCode start tag occurs inside a paragraph and the end tag in a next paragraph, the BBCode will be closed just before the end of the first paragrah and reopened in the next paragraph. Example:

This is the first paragraph [b]of a long text! This is the second paragraph[/b] of a long text!

This would normally be replaced with:

<p>This is the first paragraph <b>of a long text!</b></p> <p><b>This is the second paragraph</b> of a long text!</p>

There is also the possibility to prohibit the interruption of a BBCode by paragraph handling. In the case of hyperlinks this can be quite useful. In this case one must set the 'paragraph_type' code flag to BBCODE_PARAGRAPH_ALLOW_INSIDE:

$bbcode->setCodeFlag ('url', 'paragraph_type', BBCODE_PARAGRAPH_ALLOW_INSIDE);

The following text:

This is the first paragraph [url=http://www.example.org/]of a long text! This is the second paragraph[/url] of a long text!

would be replaced with:

<p>This is the first paragraph <a href="http://www.example.com/">of a long text!<br> <br> This is the second paragraph</a> of a long text!</p>

As one can see the element is not interrupted by paragraph handling and the two newline characters are simply replaced by the parser functions.

There are also codes where the HTML replacement may not occur inside a HTML paragraph because this would be invalid HTML. An example would be lists. To account for lists one must set the 'paragraph_type' code flag to BBCODE_PARAGRAPH_BLOCK_ELEMENT (Notice: The BLOCK has nothing in common with the 'block' standard content type except for the name):

$bbcode->setCodeFlag ('list', 'paragraph_type', BBCODE_PARAGRAPH_BLOCK_ELEMENT);

The following text:

This is the first paragraph [list] [*]List item [/list]

Would be replaced with this:

<p>This is the first paragraph </p><ul> <li>List item </li></ul>

Or, if inside of [*] paragraph handling has also been activated, with this:

<p>This is the first paragraph </p><ul> <li><p>List item </p></li></ul>

Hint: Set the flag 'opentag.before.newline' and 'closetag.after.newline' of a code which has BBCODE_PARAGRAPH_BLOCK_ELEMENT set to BBCODE_NEWLINE_IGNORE or BBCODE_NEWLINE_DROP. Else empty paragraphs like <p></p> are created.