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.
- Next: 9. Complete example
- Previous: 7. Limiting the amount of occurrences