Miscellaneous Support Functions - NBBC: The New BBCode Parser

IV. API Reference

[ Previous: I. Replaced-Item Functions | Next: V.A. Alphabetical BBCode List ]

J. Miscellaneous Support Functions

string BBCode::nl2br ( string $input )

This function is nearly identical to PHP's built-in nl2br() function; however, unlike the built-in function, this correctly handles all four major forms of line breaks (Windows "\r\n" and "\n\r"; Un*x "\n"; and Mac "\r"), and always generates "<br />" as its output, making it XHTML-safe. In general, you should always prefer this over the built-in function; while the built-in function is somewhat faster, this yields more correct, more compatible behavior.

Parameters:

input: The string to convert.

Return Value: An identical string, where all newlines have been replaced with XHTML-compatible "<br />" elements.

bool BBCode::IsValidURL ( string $address )

This function tests the input string to see if it is a legal URL. A legal URL must either be a relative URL, in which case it has no protocol identifier, or must contain the http: or https: or ftp: protocol identifiers followed by a legal domain name or IP address.

Parameters:

address: The string to test.

Return Value: True if this is a legal URL; false if this is an illegal URL.

bool BBCode::IsValidEmail ( string $address )

This function tests the input string to see if it is a legal e-mail address. A legal e-mail address must follow the rules defined in the SMTP RFC: It must start with a user's name, that followed with an @ sign, and end with a legal domain name or IP address.

Parameters:

address: The string to test.

Return Value: True if this is a legal e-mail address; false if this is an illegal e-mail address.

Note:

This performs exactly the test required by the SMTP RFC, and no other; so some e-mail addresses that are obviously illegal, like "'#$%'@foo.foo.foo" (a completely garbage address that follows the correct pattern), or "john@sales.yoyodyne" (where the user forgot to add a TLD like ".com" or ".org") are still permitted by this function. Still, this is a useful validator, because it ensures that true garbage addresses like "foo.bar" and "bleep@you" and "go!away" are correctly ignored.

string BBCode::HTMLEncode ( string $input )

This function calls PHP's htmlspecialchars() function. It is called by the parser to convert each chunk of plain text to safe HTML. This function can safely assume that there are no embedded tags or smileys; those will have been removed before this is called.

Parameters:

input: The string to HTML-encode.

Return Value: An encoded HTML string.

Note:

This function is an internal part of the NBBC parser. It is exposed so that if you inherit the BBCode class, you can override it and change its behavior. (You could, for example, use htmlentities() instead of htmlspecialchars(), or maybe add support for processing your own kind of variable {$inserts}, or maybe add support for easy *boldface* and /italics/. It's up to you how you use this function, so long as the output is valid HTML; that freedom is why it is exposed by the parser.)

string BBCode::FixupOutput ( string $input )

This function is used internally by the parser to process strings of plain text: It strips out smileys, converting them to images, and then passes the rest of the text through HTMLEncode() to convert unsafe characters like < and > and & to < and > and &, respectively.

Parameters:

input: The string to convert to HTML.

Return Value: An encoded HTML string.

Note:

This function is an internal part of the NBBC parser. It is exposed for two reasons: First, if you inherit the BBCode class, you can override it and change its behavior; but second, and more importantly, it allows you to easily convert plain-text . (You could, for example, use htmlentities() instead of htmlspecialchars(), or maybe add support for processing your own kind of variable {$inserts}, or maybe add support for easy *boldface* and /italics/. It's up to you how you use this function, so long as the output is valid HTML; that freedom is why it is exposed by the parser.)

string BBCode::FillTemplate ( string $template , array $params , array $default = array() )

This function is used by the parser in a number of places to fill variables into templates, most notably in the templates associated with enhanced tags. It is exposed so that you can use it to fill values into your own templates easily.

Parameters:

template: The template string, possibly containing variable inserts.
params: An array of values to use when filling in the template. For example, if "{$foo}" is found in the template, it will be replaced with the value of the 'foo' member of this array.
default: An array of values to use when a desired value does not exist in the $params array. For example, if "{$foo}" is found in the template, but the $params array does not contain a 'foo' member, FillTemplate() will check to see if the $default array contains a 'foo' member, and if it does, FillTemplate() will use that value instead. Only when neither the $params array nor the $default array contains the value will FillTemplate() use an empty string instead.

Return Value: A string with all variable inserts replaced with values, possibly formatted with formatting flags if any have been given.

Note:

While this function is no substitute for a good, full templating engine like Smarty, it is very lightweight and can perform some of the same operations. NBBC uses it internally in several places, and in NBBC 1.3, it has been exposed as a simple public templating API.

Variable inserts in your templates come in one of four basic forms:

{$param} - A simple replaced variable with no formatting or translation applied to it.
{$param/flags} - A replaced variable that has formatting flags applied to its value when the value is inserted into the template.
{$param.index} and {$param.index/flags} - You can use the special dot (.) operator to access members of an array or members of an object. For example, if $params['person'] contains an array ('father'=<'john','mother'=<'sue'), then you can access the person's mother by writing {$person.mother} in your template. Multiple dot operators are permitted, and are evaluated from left to right, like PHP's arrow (->) operator, but unlike PHP's brackets ([...]) operator.

An example usage of this function is demonstrated below:

Code:

$template = "{$name} is {$age} years old," . " and {$pronouns.owner} mother is {$family.mother}.\n"; $params = Array( 'name' => "John", 'age' => 20, 'gender' => 'male', 'family' => Array( 'father' => "Bill", 'mother' => "Sue", 'brother' => "George", 'sister' => "Sally", ), 'pronouns' => Array( 'self' => "him", 'owner' => "his", ), ); $bbcode = new BBCode; $output = $bbcode->FillTemplate($template, $params); print htmlspecialchars($output);

[ Previous: I. Replaced-Item Functions | Next: V.A. Alphabetical BBCode List ]