Article
Use BB Code in Your PHP Application
Page: 1 2
Configuration Options
In addition to the UBB tags listed above, many other tags come shipped with the BBCodeParser and are available for your use. In order to benefit from them, however, you must first configure the parser, which is done using an "INI" (initialization) file. A sample INI file is included in this article's code archive, located in the examples/ directory of the BBCodeParser package.
You can use this INI file from its original location or copy it to a handy directory of your choice, for example, your root testing directory. Then, go back to the test file through which the HTML_BBCodeParser class is created and change the instantiating line:
$options = @parse_ini_file('BBCodeParser.ini');
$parser = new HTML_BBCodeParser($options);
By doing this, you supply to the class all the options that are read from the INI file. You can change the path and the name of the INI file if needed.
The INI File
The most important configuration item you can set in the INI file is this line:
filters = Basic,Extended,Links,Images,Lists,Email
This tells the parser which filters are to be parsed and which should be ignored. A filter is simply a PHP class used by the BBCodeParser that defines a set of BB tags. The table below describes which BB tags each BBCodeParser filter gives you:
The key benefit of the parser is that it can be configured to allow or disallow tags or groups of tags. If, for example, you use this parser in your CMS and you don't want to allow the client to add images, because you're afraid they might mess up your nice design, you can remove the Images filter via the INI file.
Other config options you may want to change in the INI file are:
- "quotestyle" -- you can set this value to "double" to be XHTML-compliant
- "open" and "close" entries -- you may want to enclose their default values with quotes if you're running PHP5
Here's how these settings will appear in your INI file:
quotestyle = double
open = "["
close = "]"
The test script bb_test3.php and the INI file BBCodeParser.ini are included in the code archive for this article.
UBB Code Syntax
At this point, you may well be thinking, "Oh, no! Not another markup language to learn…" Don't worry; chances are that you and your users already know most of these tags. If, for example, you've ever posted in a phpBB-based forum, such as the SitePoint Forums, or its blog and article comments, you know about UBB code.
It's fair to say, though, that some of the tags might require further clarification, since almost every UBB code implementation is a sort of a UBB dialect. Not to worry -- there's an easy way to get the hang of it. You can learn the UBB code syntax, and at the same time test your parsing script, by pasting the following user input in the text area of your test script. Then, sit back and admire the results.
[color=red]I'm red and I'm hot[/color]
[size=16]16pt sized text. That's big.[/size]
[font=Verdana]I can use all kinds of fonts![/font]
[align=right]This chunk is aligned to the right[/align]
[align=center]I'm centered[/align]
Hey, [quote=http://www.h2g2.com]Don't panic![/quote]
[code]if ($code) {
echo "Code in fixed-width font";
}[/code]
[img]http://www.sitepoint.com/images/sitepoint-logo.gif[/img]
[img w=80 h=25]http://www.sitepoint.com/images/sitepoint-logo.gif [/img]
http://www.sitepoint.com
[url]http://www.sitepoint.com[/url]
[url=http://www.sitepoint.com]SP[/url]
[url=http://www.sitepoint.com t=_blank]SP in a new window[/url]
[url=http://www.sitepoint.com t=_blank][img w=80 h=25]http://www.sitepoint.com/images/sitepoint-logo.gif[/img][/url]
moi@example.org
[email]toi@example.org[/email]
[email=we@example.org]drop us an email[/email]
[ulist]
[*]one
[*]two
[/ulist]
[list]
[*]first
[*]second
[/list]
[list=1]
[*]ordered item 1
[*]and ordered item 2
[/list]
[list=i]
[*]ordered item 1 type i
[li=4]ordered item 4 type i[/li]
[/list]
[list=I]
[*]ordered item 1 type I
[/list]
[list=a s=5]
[li]ordered item 5 type a[/li]
[*]ordered item 6 type a
[/list]
[list=A]
[li]ordered item 1 type A[/li]
[li=12]ordered item 12 type A[/li]
[/list]
[list=A s=3]
[li]ordered item 1, nested list:
[li]nested item 1[/li]
[list=I]
[li]nested item 2[/li]
[/list][/li]
[li]ordered item 2[/li]
[/list]
Here's how the results should appear:
You can use CSS to refine the display of some of the tags, including <a>, <code>, <q> (the [quote] BB tag) and so on. Optionally, you can also use nl2br() to convert new lines to <br />.
Create Your Own BB Tags
Like it so far? Well, now's the time for you to step up and take full control over your destiny! Or, in other words, to customize the parser at will.
In this section, you'll create you own custom parser filter and custom BB tags. Let's call the filter MyBB, and the tags [h], [line] and [block]. When these tags are parsed, they'll be replaced with the good old HTML tags <h1>, <hr /> and <blockquote>.
In order to do so, you'll need to create a class definition for the MyBB filter. The class needs to:
- be named
HTML_BBCodeParser_Filter_MyBB - extend the base
HTML_BBCodeParserclass - be placed in a
MyBB.phpfile - be located in
YourPEARDir/HTML/BBCodeParser/Filter
Without further ado, here's the code you need to have in the MyBB.php file in order to provide the heading, horizontal line and block quote formatting features:
<?php
require_once 'HTML/BBCodeParser.php';
class HTML_BBCodeParser_Filter_MyBB extends HTML_BBCodeParser
{
var $_definedTags =
array('block' => array( 'htmlopen' => 'blockquote',
'htmlclose' => 'blockquote',
'allowed' => 'all',
'attributes'=> array()
),
'line' => array( 'htmlopen' => 'hr',
'htmlclose' => '',
'allowed' => 'all',
'attributes'=> array()
),
'h' => array( 'htmlopen' => 'h1',
'htmlclose' => 'h1',
'allowed' => 'all',
'attributes'=> array()
),
);
}
?>
The only thing left is to add MyBB to the INI file's filter line:
filters = Basic,Extended,Links,Images,Lists,Email,MyBB
You're done! Here are the custom tags in action.
Related Files
That's it for this BB tags tutorial. You've learned something you can start using right away to enrich your applications!
Firstly, visit http://pear.php.net and download PEAR libraries free of charge. This is a good idea, as it allows you to flex you sysadmin muscles a bit as you install PEAR. If you remember what we said in the setup section of this tutorial, all you need is the PEAR base classes and the BBCodeParser package.
Here are the other files that were created and used in this tutorial, and which are available in the code archive:
- Directory structure -- a text file that shows the directory structure I used for the examples, provided for your reference only in
directory_structure.txt - Initialization script --
init.inc.php - Test scripts --
test1.php,test2.phpandtest3.php - The custom filter, which should be saved in YourPEARDir/HTML/BBCodeParser/Filter/MyBB.php --
MyBB.php - The configuration file --
BBCodeParser.ini - Everything as a zip file –
bb.zip
Experiment … and Stay Tuned
You know that the best way to learn is by doing, so go ahead: set up your environment, run the examples and try them out. Adding BB code functionality to your CMS (guestbook/blog/forum/you-name-it) has never been easier!
… and stay tuned for the next part of this tutorial.