StringParser_BBCode class documentation

6. Flags to control the behaviour of the class

6.1 General

One may set flags for each defined code. A flag tells the class that there are certain particularities with this code that are to be accounted for. To set a flag for a code, one must call the setCodeFlag method:

$bbcode->setCodeFlag ('b', 'my_flag', 'my_value');

This method has the following prototype:

void setCodeFlag (string $code, string $name, mixed $value);

$code
Specifies the name of the code for which a flag is to be set..
$name
Specifies the name of the flag that is to be set. Notice: If a flag has already been set and the method is called a second time the former value will be overwritten. Secondly it will not be checked if the flag itself is valid, having the consequence that you may set arbitrary flags - but only certain flags that are listed below a special meaning for the class - all others will be ignored.
$value
The value of the flag that is to be set.

6.2 List of all flags

The following table shows a list of all flags that are recognized by the class. Notice: Most of the values for the flags are constants. These are not to be put in quotes. In case this had to be the case this would be marked explicitly!

Name of the flag Value Meaning
'case_sensitive' true / false Specifies whether the code should be treated case sensitive or not. Default is true meaning that case sensitivity is active (e.g. [b] is not equal [B]). Please also have a look at the caseSensitive global flag.
'closetag' Specifies how to treat with the end tag. This flag and its behaviour is everything else than trivial so it is wise to experiment a bit with all values to see what they do exactly.
BBCODE_CLOSETAG_FORBIDDEN The end tag is forbidden, it may not show up in the text. If it does show up it will be ignored and appended as if it were normal text and the element will not be closed at that position. The rest of the behaviour is identical to BBCODE_CLOSETAG_OPTIONAL.
BBCODE_CLOSETAG_OPTIONAL The end tag is optional. If it does show up it closes the element normally. If the parent element is closed the current element is also closed. If a new start tag of the same code shows up this element is also closed before a new element is opened. This is useful for e.g. lists which could look like:
[list]
[*] Item
[*] Item
[/list]
The first list item will be closed before the second list item is opened. And the second list item will be closed when the list is closed. This can be achieved by setting the 'closetag' flag of the [*] code to this value (BBCODE_CLOSETAG_OPTIONAL) or alternatively to BBCODE_CLOSETAG_FORBIDDEN.
BBCODE_CLOSETAG_IMPLICIT
(standard setting)		 The end tag is only optional if the parent element is closed. Example:
[b]this is [i]a text[/b]
If the [i] code posseses the flag 'closetag' with this value it will be closed when the [/b] occurs. Another example:
[list]
[*] [b]Item
[*] Item
[/list]
Here the [b] element will be closed when the second [*] tag is found because the parent element (starting with the first [*] tag) is closed.
BBCODE_CLOSETAG_IMPLICIT_ON_CLOSE_ONLY This just behaves like BBCODE_CLOSETAG_IMPLICIT with the only difference that in case of
[list]
[*] [b]Item
[*] Item
[/list]
the [b] element is not closed because the parent element would only be closed because another element of the same type would be opened. Because the [b] element is not closed consequently the first [*] element will also not be closed and therefore the second [*] tag will be ignored because it is not allowed inside [b].
BBCODE_CLOSETAG_MUSTEXIST The end tag must exist. If it does not exist the start tag will be ignored and appended as text. An element of this type can also not be closed by the parent element.
'opentag.before.newline' Specifies how a possibly existing newline character (\n) that shows up before the start tag has to be treated. To the possible values see below.
'opentag.after.newline' Specifies how a possibly existing newline character (\n) that shows up after the start tag has to be treated. To the possible values see below.
'closetag.before.newline' Specifies how a possibly existing newline character (\n) that shows up before the end tag has to be treated. To the possible values see below.
'closetag.after.newline' Specifies how a possibly existing newline character (\n) that shows up after the end tag has to be treated. To the possible values see below.
Possible values for the four flags above BBCODE_NEWLINE_PARSE
(default setting)		 The newline character will per processed normally as any other character.
BBCODE_NEWLINE_IGNORE The newline character will not be processed by parser functions but will be appended to the output.
BBCODE_NEWLINE_DROP The newline character will be removed completely from the output.
'paragraph_type' Flags that are necessary for paragraph handling. Have a look at the chapter Paragraph handling.
'paragraphs'
'occurrence_type' An internal flag that is used by the method setOccurrenceType. It should never be necessary to set or read this flag manually. Have a look at setOccurrenceType in the chapter Limiting the amount of occurrences.

6.3 Global flags

There also exist several global flags. These are flags that are not set for a single code but that are set for the whole class.

caseSensitive

This controls whether the whole class behaves case sensitive. You can alter the flag with the method setGlobalCaseSensitive. You may retreive the current value with the globalCaseSensitive method. If true (default) the class assumes all codes are case sensitive which do not have the code flag 'case_sensitive' set to false. When set to false the class assumes all codes are case insensitive; the 'case_sensitive' code flag is ignored in that case. Example:

$bbcode->setGlobalCaseSensitive (false);

mixedAttributeTypes

If this flag is activated, [code=foo attr=bar] will have two attributes (default = 'foo', attr = 'bar'), if the flag is deactivated, the same string will have only one attribute (default = foo attr=bar). The default value is off. You may retreive the current value with the mixedAttributeTypes method. Example:

$bbcode->setMixedAttributeTypes (true);