Documentation
- Introduction
- Classes
Introduction
Getting started
Welcome. Installation of jBBCode is quick and simple. First, download and unarchive the latest version of jBBCode. Upload the directory to your server. Remember that jBBCode requires PHP 5.3+. To include jBBCode in your project, you can either manually include Parser.php or use a PSR-0 autoloader. To manually include jBBCode, wherever you use jBBCode, require_once the Parser.php file:
require_once "./path/to/jBBCode/Parser.php";
Parser.php will handle including the rest of the relevant files. Once you've included Parser.php, jBBCode is installed and ready to go.
To begin parsing BBCode, you'll need to define a few bbcodes. The DefaultCodeDefinitionSet class can provide some basic common bbcodes for you, or you can define your own.
Because jBBCode uses namespaces, you'll need to use the namespace syntax when using jBBCode. For example:
<?php require_once "jbbcode-1.2.0/Parser.php"; $parser = new JBBCode\Parser(); $parser->addCodeDefinitionSet(new JBBCode\DefaultCodeDefinitionSet()); $parser->parse(htmlentities($_GET['input'])); print $parser->getAsHtml();
See example 1 for more help.
Defining new codes
Defining new bbcodes is simple with jBBCode. New text-replacement bbcodes are added to the parser through creating instances of the CodeDefinition class and adding them to the parser through its addCodeDefinition method. The easiest way to create new CodeDefinitions is through the CodeDefinitionBuilder class. The builder's constructor requires the tag name for the bbcode and a replacement string. The replacement string should be html containing {param} and possibly {option}. When the BBCode is translated to html, the contents between the tags will take the place of {param}. Your bbcode's can also take an argument (referred to as an option) in an opening tag. If you enable the option on a bbcode, the {option} string in the replacement text will be replaced with the argument provided to the bbcode. Here's a couple examples defining very simple text-replacement bbcodes and adding them to a parser.
$builder = new JBBCode\CodeDefinitionBuilder('i', '{param}'); $parser->addCodeDefinition($builder->build()); $builder = new JBBCode\CodeDefinitionBuilder('u', '{param}'); $parser->addCodeDefinition($builder->build());
To make use of the {option}, you must enable it on your CodeDefinition. The builder provides the setUseOption method for this purpose. Creating a bbcode with an option is illustrated below.
$builder = new JBBCode\CodeDefinitionBuilder('url', '{param}'); $builder->setUseOption(true)->setOptionValidator(new \JBBCode\validators\UrlValidator()); $parser->addCodeDefinition($builder->build());
The above example makes use of an InputValidator. Often your bbcodes will take values that are inserted into html. It's important to validate these values to prevent security risks. When constructing a definition through the CodeDefinitionBuilder you can apply validators to the definition through the setOptionValidator and setBodyValidator methods to validate the {option} and {param} respectively. Note that it only makes sense to set a body validator if you additionally setParseContent(false), otherwise the body of the bbcode is treated as bbcode itself.
For defining bbcodes that do more than just text replacement, see the next section, Defining custom CodeDefinitions.
Defining custom CodeDefinitions
With jBBCode, bbcodes are not limited to simple text replacement. Through extending the CodeDefinition class, you can override default text replacement and use all the power of PHP in evaluating the BBCode. Because the parse tree has already been constructed, accessing an element's content and attribute is simple. Generally, when creating your own custom CodeDefinition, the only methods you really need to override are the constructor (to define the tag name and option parameters) and asHtml which takes an ElementNode that is defined by your CodeDefinition and returns the html representation of that ElementNode.
Here is an example that extends CodeDefinition in order to use regular expressions on the code's content. The result is a YouTube embed bbcode that only requires the url of the YouTube video.
<?php class YoutubeEmbed extends JBBCode\CodeDefinition { public function __construct() { parent::__construct(); $this->setTagName("youtubeEmbed"); } public function asHtml(JBBCode\ElementNode $el) { $content = ""; foreach($el->getChildren() as $child) $content .= $child->getAsBBCode(); $foundMatch = preg_match('/v=([A-z0-9=\-]+?)(&.*)?$/i', $content, $matches); if(!$foundMatch) return $el->getAsBBCode(); else return "<iframe width=\"640\" height=\"390\" src=\"http://www.youtube.com/embed/".$matches[1]."\" frameborder=\"0\" allowfullscreen></iframe>"; } }
The custom CodeDefinition is then loaded into the parser through the addCodeDefintion:
$youtubeEmbed = new YoutubeEmbed(); $parser->addCodeDefinition($youtubeEmbed);
The youtubeEmbed bbcode defined here is currently in use at http://xboxamerica.com.
Classes
Parser
The Parser class is the main jBBCode class and the one you should include in your file. This class constructs the parse tree and references all the other classes. Most users will only need to directly use this class.
addBBCode
(deprecated)
adds a simple text-replacement bbcode to the parser's list of bbcode definitions.
- $tagName (string)
- $replace (string)
- $useOption = false (boolean)
- $parseContent = true (boolean)
- $nestLimit = -1 (integer)
- $optionValidator = null (InputValidator)
- $bodyValidator = null (InputValidator)
addCodeDefinition
adds a code definition (see CodeDefinition class) to the parser's list of bbcode definitions. This method is often used with custom definitions that extend the CodeDefinition class.
- $definition (CodeDefinition)
addCodeDefinitionSet
adds a set of CodeDefinitions to the parser's list of bbcode definitions.
- $set (CodeDefinitionSet)
getAsText
returns the parse tree as text only (without any markup at all).
getAsBBCode
returns the parse tree as bbcode. This method will close any tags that were not explicitly closed.
getAsHTML
returns the parse tree as html.
accept
Passes the given NodeVisitor into the accept method of the DocumentElement, effectively traversing the parse tree with the visitor.
- $visitor (NodeVisitor)
parse
Constructs the parse tree from a string of bbcode markup.
- $str (string)
removeOverNestedElements
(deprecated)
Removes any elements from the parse tree that are nested beyond the limit set by the element's CodeDefinition.
codeExists
determines whether a bbcode is defined for the given tag name and option setting.
- $tagName (string)
- $usesOption = false (boolean)
CodeDefinition
A CodeDefinition object defines a specific bbcode. The parser maintains a list of CodeDefinition objects which represents all the possible bbcodes the parser will recognize. A CodeDefinition object may be created through Parser's addBBCode method, or by extending CodeDefinition class and manually instantiating an instance of the subclass. CodeDefinitions are used during the translation from the parse tree to html.
::construct
a static method to construct a new CodeDefinition instance.
- $tagName (string)
- $replacementText (string)
- $useOption = false (boolean)
- $parseContent = true (boolean)
- $nestLimit = -1 (integer)
- $optionValidator = null (InputValidator)
- $bodyValidator = null (InputValidator)
__construct
(deprecated)
Constructs a new CodeDefinition and set properties to their defaults. This method is deprecated and in a future release will be made private.
asHtml
Returns the HTML representation of the element provided as an argument. This method is commonly overriden by custom CodeDefinitions.
- $el (ElementNode)
asText
Returns the text representation of the element provided as an argument. You may want to override this method in your custom CodeDefinitions.
- $el (ElementNode)
getTagName
Returns the CodeDefinition's tag name
getReplacementText
Returns the the replacement text of the CodeDefinition. For default CodeDefinitions, this contains the HTML markup with {param}.
usesOption
Returns whether or not its CodeDefinition expects (and needs) to have an option passed to it within its opening tag.
parseContent
Returns whether or not this CodeDefinition will parse its children.
getNestLimit
Returns the maximum number of elements defined by this CodeDefinition that can be embedded within each other.
setTagName
(deprecated)
Sets this CodeDefinition's tag name
- $tagName (string)
setReplacementText
(deprecated)
Sets the replacement text of this CodeDefinition
- $txt (string)
setUseOption
(deprecated)
Sets whether or not this CodeDefinition requires an option to be passed in its opening tag.
- $bool (boolean)
CodeDefinitionBuilder
The recommended way to create text replacement CodeDefinitions is through this CodeDefinitionBuilder class. It implements the Builder pattern for CodeDefinitions. Create a builder, set the appropriate values through function calls and then call its build method to construct the builder.
setReplacementText
Sets the replacement text that should be used for the CodeDefinition.
- $replacementText (string)
setUseOption
Sets whether or not the built CodeDefinition should use the {option} bbcode argument.
- $option (boolean)
setParseContent
Sets whether or not the built CodeDefinition should allow its content to be parsed and evaluted as bbcode.
- $parseContent (boolean)
setNestLimit
Sets the nest limit for the CodeDefinition. A nest limit of -1 signifies no limit.
- $limit (integer)
setOptionValidator
Sets the InputValidator that should be used to validate the option argument to this bbcode.
- $validator (InputValidator)
ElementNode extends Node
An ElementNode is a node within the parse tree that is defined by a CodeDefinition. It contains children, a subtree of the parse tree, and a reference to the CodeDefinition that defined it. It optionally may contain an attribute as well.
getCodeDefinition
Returns the CodeDefinition that defines the type of this element
setCodeDefinition
Set the CodeDefinition that defines the type of this element
- $codeDef (CodeDefinition)
getAttribute
Returns the attribute (value for the {option}) of this element
getChildren
Returns all of the child nodes of this node
getAsText
Returns the element as text (without any markup)
getAsBBCode
Returns the element as BBCode
getAsHTML
Returns the element as HTML
addChild
Appends an element to this element's children (and updates the child's parent)
- $child (Node)
removeChild
Removes a child element if the element is really a child of the target
- $child (Node)
Node
An abstract class for a node in the parse tree.
getParent
Returns this node's parent
hasParent
Returns true if this node has a parent, false if it does not
isTextNode
Returns true if this node is a text node (returns false by default, and is overridden by TextNode to return true)
accept
allows the given NodeVisitor instance to visit this node
- $visitor (NodeVisitor)