StringParser_BBCode class documentation
Author: Christian Seiler

# `StringParser_BBCode` class documentation

- Project homepage
- Documentation
- PHPDOC Documentation
- Download
- Diese Seite auf Deutsch

## 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);`

- Next: 7. Limiting the amount of occurrences
- Previous: 5. Filters