BBcode Management Explained

Let's take an excursion to Administration => Other => BBcodes:


It shows you registered bbcodes as a tables editable and there is a row to add a new bbcode on the bottom of each pages (not shown on this screenshot).

To update bbcode, you should edit data in a matching row and hit Update button. Or hit Delete to remove the row. You cannot update/delete more than 1 row at once. To add a new bbcode, fill the row on the bottom and hit the Add button.

#1. Parameter descriptions

• Name - BBcode name (use alphanumerics and underscores only). This should be exactly the same as the name of the bbcode "tag" in square braces (without arguments).
• Mode - Parsing mode, one of the following: 'str' (str_replace), 'pcre' (preg_replace) and 'callback' (preg_replace_callback).
• Pattern - BBcode string or entire regular expression. Case insensitive.
  * In 'str' mode it's a search needle, which is then replaced with replacement string.
  * In 'pcre' mode it expects a Perl-compatible regular expression pattern (see PCRE details) without delimiters and modifiers (just the pattern itself).
  * In 'callback' mode it is the same as in 'pcre' mode.
• Replacement - Replacement string or regular substitution or callback body.
  * In 'str' mode it is exact replacement for the pattern.
  * In 'pcre' mode it is PCRE replacement with $i placeholders for pattern matches.
  * In 'callback' mode it is a callback function body in PHP. It does not need function declaration and it automatically imports $cfg, $sys, $usr, $L, $skin, $cot_groups from the global scope. Pattern matches are contained in $input array. The function must return a replacement string for entire pattern. Just see existing callbacks as an example.
• Container - Whether bbcode is container (like [bbcode]Something here[/bbcode]). This flag lets the parser know, that it should add closing tags for this bbcode if they are missing.
• Priority - BBcode priority from 1 to 255. Smaller priority bbcodes are parsed first, 128 is default medium priority. Normally 128 is ok. But such bbcodes as CODE should be parsed before any other bbcodes, so they are given higher priority. Or vice versa if your bbcode needs to be parsed last.
• Plugin - Plugin/part name this bbcode belongs to. You cannot change this in editor, but it is used by plugins, so that a plugin can easily install/uninstall its own bbcodes without touching others.
• Post-render - Whether this bbcode must be applied on a pre-rendered HTML cache. Use only if your callback does some per-request calculations. More of HTML cache and post-rendering is explained below.

#2. BBcode API

Here are prototypes of the functions that you can use in your modules and plugins:

/**
 * Registers a new bbcode in database.
 * In 'callback' mode $replacement is normal PHP function body (without declaration) which
 * takes $input array of matches as parameter and must return a replacement string. These
 * variables are also imported as globals in callback function: $cfg, $sys, $usr, $L, $skin, $cot_groups
 *
 * @global $db_bbcode;
 * @param string $name BBcode name
 * @param string $mode Parsing mode, on of the following: 'str' (str_replace), 'pcre' (preg_replace) and 'callback' (preg_replace_callback)
 * @param string $pattern Bbcode string or entire regular expression
 * @param string $replacement Replacement string or regular substitution or callback body
 * @param bool $container Whether bbcode is container (like [bbcode]Something here[/bbcode])
 * @param int $priority BBcode priority from 0 to 255. Smaller priority bbcodes are parsed first, 128 is default medium priority.
 * @param string $plug Plugin/part name this bbcode belongs to.
 * @param bool $postrender Whether this bbcode must be applied on a pre-rendered HTML cache.
 * @return bool
 */
function cot_bbcode_add($name, $mode, $pattern, $replacement, $container = true, $priority = 128, $plug = '', $postrender = false) { }

Use this function in your_plugin.install.php to automatically install bbcodes with your plugin. Don't forget to set $plug = 'your_plugin'.
 

/**
 * Removes a bbcode from parser database.
 *
 * @global $db_bbcode
 * @param int $id BBCode ID or 0 to remove all (use carefully)
 * @param string $plug Remove all bbcodes that belong to this plug
 * @return bool
 */
function cot_bbcode_remove($id = 0, $plug = '') { }

In plugins you usually call it in your_plugin.uninstall.php like cot_bbcode_remove(0, 'your_plugin') to remove all plugin bbcodes at once. But if you specify concrete bbcode id as first parameter and don't pass the second, it will remove just one bbcode.
 

/**
 * Updates bbcode data in parser database.
 *
 * @global $db_bbcode;
 * @param int $id BBCode ID
 * @param bool $enabled Enable the bbcode
 * @param string $name BBcode name
 * @param string $mode Parsing mode, on of the following: 'str' (str_replace), 'pcre' (preg_replace) and 'callback' (preg_replace_callback)
 * @param string $pattern Bbcode string or entire regular expression
 * @param string $replacement Replacement string or regular substitution or callback body
 * @param bool $container Whether bbcode is container (like [bbcode]Something here[/bbcode])
 * @param int $priority BBcode preority from 0 to 255. Smaller priority bbcodes are parsed first, 128 is default medium priority.
 * @param bool $postrender Whether this bbcode must be applied on a pre-rendered HTML cache.
 * @return bool
 */
function cot_bbcode_update($id, $enabled, $name, $mode, $pattern, $replacement, $container, $priority = 128, $postrender = false) { }

This function is used to update bbcodes. Parameters are pretty similar and self-explaining.
 

/**
 * Neutralizes bbcodes in text
 *
 * @param string $text Source text
 * @return string
 */
function cot_bbcode_cdata($text) { }

Use this function inside of your callback BBcodes to disable all bbcodes inside of it. Also requires a small priority number for your bbcode.

/**
 * Parses text body
 *
 * @param string $text Source text
 * @param bool $enable_markup Enable markup or plain text output
 * @param string $parser Non-default parser to use
 * @return string
 */
function cot_parse($text, $enable_markup = true, $parser = '')

This function does the same as before: parses bbcodes, smilies and newlines in text if appropriate parameters are set true. The difference is that you don't need to call this function at all if you have a valid HTML-cache value, and this function will be automatically bypassed if custom parser is used.