# `StringParser_BBCode` class documentation

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

## 2. Defining own BBCode

### 2.1 Including the class

To be able to use the class the two files stringparser.class.php and stringparser_bbcode.class.php have to be copied into a common directory. Now the file stringparser_bbcode.class.php has to be embedded into the own PHP file:

`<?php
require_once 'path/to/stringparser_bbcode.class.php';
// further PHP code
?>`

To use the class you must create an object of it:

`<?php
require_once 'path/to/stringparser_bbcode.class.php';
$bbcode = new StringParser_BBCode ();
// further PHP code
?>`

Now the class is included into the PHP script and ready for use.

### 2.2 The first code

To define a BBCode you must call the `addCode` method of the class. In the following example a code with these characteristics is to be defined:

- The code should be `[b]`.
- The code should be replaced with `<b>` and `</b>`.
- The code should be allowed inside block and inline elements.
- The code itself should be an inine element.

To acchieve this the following code is necessary:

`<?php
require 'path/to/stringparser_bbcode.class.php';
$bbcode = new StringParser_BBCode ();
$bbcode->addCode ('b', 'simple_replace', null, array ('start_tag' => '<b>', 'end_tag' => '</b>'),
'inline', array ('block', 'inline'), array ());
// further PHP code
?>`

The method addCode is defined as follows:

`void addCode (string $code, string $type, string $callback, string $params, string $content_type,
array $allowed_in, array $not_allowed_in);`

The following list explains the parameters of the `addCode` method:

`$code` (in the example `'b'`)
  This is the name of the code. This means, it is going to looked for `[b]` in this example. If you changed this parameter to `'chatchme'` the class would look for `[chatchme]`.
`$type` (in the example `'simple_replace'`)
  This is the manner how the code should be processed. `'simple_replace'` has the consequence that the start tag (here: `[b]`) and the end tag (here: `[/b]`) are always to be replaced through the same strings. Beneath you will find more information on processing types.
`$callback` (in the example `null`)
  Here you can put a function that is to be called during the replacement process. Because the processing type `'simple_replace'` requires no function it is possible to simply supply `null` for this parameter - in this case it will simple not be considered.
`$params` (in the example `array ('start_tag' => '<b>', 'end_tag' => '</b>')`)
  This parameter normally accepts values that are to be passed to the replacement function when it is called. Because for this processing type there is no need for a function, this parameter specifies the replacement strings instead.
`$content_type` (in the example `'inline'`)
  This is the content type of this code.
`$allowed_in` (in the example `array ('block', 'inline')`)
  This parameter is the list of content types inside which the code is allowed. If the code is found directly inside another content type it is ignored.
`$not_allowed_in` (in the example `array ()`)
  This parameter is the list of content types inside which the code is forbidden. If the code inside one of these content types, it is ignored. All parents of the code are taken into account.

### 2.3 Processing types

The class makes it possible to react differently to codes. For this purpose, there are several processing types.

`'simple_replace'`
  With this processing type start and end tags will simply be replaced through strings. `[b]` can be replaced with `<b>` and `[/b]` with `</b>` for example. With this processing type it is not possible to use attributes. The strings that define the replacements musst stand in `$params['start_tag']` and `$params['end_tag']`. Have a look at the example above.
`'simple_replace_single'`
  This is identical to `'simple_replace'` except for the fact that there is only one tag and the element ends directly after it and contains no content. For this reason, it is necessary to set only `$params['start_tag']`.
`'callback_replace'`
  With this processing type a function is called that has to return the text that is to be used as a replacement. This is explained in the chapter callback functions.
`'callback_replace_single'`
  Like `'callback_replace'` but as in `'simple_replace_single'` there is only one tag.
`'usecontent'`
  This processing type is just like `'callback_replace'` with the difference that inside the element it will not be looked for further BB-Codes. Have a look at the section special codes.
`'usecontent?'`

  This processing type can either behave like `'usecontent'` or like `'callback_replace'`. First of all, there is a check if a certain attribute is set. If this is the case, the processing type behaves like `'callback_replace'`. In the other case the processing type behaves like `'usecontent'`. The name of the attribute that is to be looked for has to be specified in `$params['usecontent_param']`. An example for the use of this processing type is the often used BB-Code `[url]`: This code can be used in two different manners: `[url]http://www.example.com/[/url]` und `[url=http://www.example.com/]title of the link, also containing [b]bold[/b] text[/url]`. In the first case `'usecontent'` would be the processing type of choice because the link destination is specified between start and end tag of this element and it would be nonsense to replace further BB-Codes inside `http://www.example.org/`. On the other hand `'callback_replace'` would be the processing type of choice in the second example because the link destination is specified as an attribute and the link text itself may still contain further <bbr>BBCodes.

  Notice: Further, it is possible to supply several parameters for `usecontent_param`: just hand over an array instead of a string. Example: `$bbcode->addCode (..., array('usecontent_param' => array ('parameter1', 'parameter2')), ...);`.

`'callback_replace?'`
  This processing type is the opposite of `'usecontent?'`: if an attribute specified with `usecontent_param` exists the code will be treated as if it were `'usecontent'`, else as if it were `'callback_replace'`.

### 2.4 Parsing text

To convert a text one must call the `parse` method of the class:

`// code to include the class, calls to addCode, etc..
$new_text = $bbcode->parse ($old_text);`

The contents of `$old_text` is processed here and the result of it is stored in `$new_text`. The method `parse` may be called as many times as wanted inside your code but it will always instantly return `false` if it is called during another parsing process.

- Next: 3. Parser functions
- Previous: 1. Introduction