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:

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

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.
 

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

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

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.