StringParser_BBCode class documentation

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:

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 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.