IV. API Reference

[ Previous: B. Core Parsing Functions | Next: D. Content-Trimming Functions ]

C. Language-Behavior Functions

void BBCode::SetTagMarker ( string $marker )
This function changes NBBC's tag marker, which is the character used to separate tags from content. You may set this to any of '[', '<', '{', or '('. NBBC allows you to change the tag marker so that you can use it in more environments, and you could even use it as an HTML validator.
Parameters:
  • marker: The type of tag marker to use; this must be one of '[', '<', '{', or '('. Other values must not be used with the current version of NBBC.
Note: The default tag marker is obviously '[' since NBBC is designed to process BBCode. If you intend to use NBBC to process HTML, though, you should not only change the tag marker, but you should also allow ampersands with the SetAllowAmpersand() function: If you forget to allow ampersands, your users will be unable to display < and > characters because the initial & used in HTML to represent them (as in the case of &lt; and &gt;) will be converted to an &amp; in the output.

Very important note: The tag marker cannot be changed during a parse! This function must not be called by a tag callback function; any changes to the tag marker during a Parse() will be ignored until the next time Parse() is called.
string BBCode::GetTagMarker ( )
This function returns the current tag marker. See SetTagMarker() for more details.
Return values: Returns one of '[', '<', '{', or '('.
void BBCode::SetAllowAmpersand ( bool $allow )
This function determines whether ampersands (the '&' character) are converted to &amp; in the output or sent to the output verbatim.
Parameters:
  • allow: If set to false, all '&' characters are converted to "&amp;"; this is the default behavior. If set to true, all '&' characters are left unchanged in the output.
Note: This function exists so that you can allow the user to type HTML entities like '&lt;' directly. By default, any time the user types an '&' character, it will be turned into '&amp;'; but if you allow ampersands to pass through unchanged, the user can type '&eacute;' and get '&eacute;' in the output, thus displaying as 'é'. This is effectively a pass-through, allowing the user to do HTML things that would otherwise be unsafe; but it's very important when the tag marker is set to '<', because otherwise the user would have no way to display '<' or '>' without them being converted to tags.

Note also that in tags marked BBCODE_VERBATIM, this is temporarily disabled: The tag wants its data verbatim, so it's getting its data verbatim.

bool BBCode::GetAllowAmpersand ( )
This function returns the current allow-ampersand state. See SetAllowAmpersand() for more details.
Return values: Returns true or false, depending on whether ampersands are passed verbatim to the output.
void BBCode::SetIgnoreNewlines ( bool $ignore )
This function determines whether newlines are converted to <br /> in the output or sent to the output verbatim; in effect, it allows you to "turn off" the normal way that BBCode handles newlines and have a fully free-formatted language.
Parameters:
  • ignore: If set to false, all newlines (be they Un*x-style "\n", or Windows/DOS-style "\r\n" or "\n\r", or Mac-style "\r") are converted to "<br />"; this is the default behavior. If set to true, all newlines are converted to Un*x-style newlines ("\n") and passed to the output the same as any other whitespace.
bool BBCode::GetIgnoreNewlines ( )
This function returns the current ignore-newline state. See SetIgnoreNewlines() for more details.
Return values: Returns true or false, depending on whether newlines are treated as paragraph breaks (false) or whether they're treated as generic whitespace (true).
void BBCode::SetPlainMode ( bool $enable )
This function turns on "plain mode." When NBBC is in "plain mode", it outputs very lightweight HTML content, using the tags as a guide, but not actually calling any of them directly.
Parameters:
  • enable: If set to true, all plain text will be copied verbatim to the output, and tags will be mostly ignored, using only their 'plain_start' and 'plain_end' and 'plain_content' members as a guideline for generating the output. If set to false (the default), full BBCode-and-HTML formatting logic will be used for all tags.
Note:

Plain mode is useful for generating a non-HTML or minimal-HTML but still-readable representation of the input text quickly, without having to resort to brute-force solutions like strip_tags(). The only HTML tags generated in plain mode will be <b>, <i>, <u>, and <a href="..."> tags. Newlines will be retained in the output, so if you want to display them, a quick call to nl2br() will do the job. Alternatively, a few quick calls to preg_replace() can turn your plain-jane HTML into simple, readable plain text:
Code:
// Convert the input to plain HTML with line breaks intact. $bbcode->SetPlainMode(true); $output = $bbcode->Parse($input); $output = $bbcode->nl2br($output); print $output;
Code:
// Convert the input to "plain HTML"... $bbcode->SetPlainMode(true); $output = $bbcode->Parse($input); // ...and convert to plain text by stripping the <b>, <i>, <u>, and // <a> tags. Just for the heck of it, we do word-wrap too to make it // look nice on text displays and line printers and similar ancient // output devices. $output = wordwrap($bbcode->UnHTMLEncode(strip_tags($output))); print $output;
bool BBCode::GetPlainMode ( )
This function returns the current plain-mode state. See SetPlainMode() for more details.
Return values: Returns true or false, depending on whether plain-jane HTML is generated as output (true) or whether HTML is generated as output (false).
void BBCode::SetLimit ( int $limit )
This function enables output-limiting. When output-limiting is turned on, no more than $limit plain-text characters will be generated in the output (tags like <b> are not counted, but their content is), and the resulting output will be always be broken at whitespace or before/after a tag, never in the middle of a word. Even if output is limited, correct formatting logic will be applied; the output will still be XHTML 1.0 Strict-compliant.
Parameters:
  • limit: If set to nonzero, no more than this many plain-text characters will be generated in the output. If set to zero, there is no limit.
Note:

The purpose of this function is to allow you to generate excerpts of your text, short initial chunks of the text suitable for use as titles or as blurbs in a news box or RSS feed. It does not exist to simply chop off the output in an exacting fashion; rather, it tries to generate something relatively short, near your size limit, while still maintaining formatting. It works very well when used in conjunction with SetPlainMode(), which together can output a short, HTML-free excerpt of any input text.
int BBCode::GetLimit ( )
This function returns the current output-limit length. See SetLimit() for more details.
Return values: Returns the number of characters to which the output is limited, or zero (0) if there is no limit.
void BBCode::SetLimitPrecision ( float $prec )
When limiting text, it's often desirable to allow text that's slightly longer than your limit to pass through: For example, cutting one word off an entire paragraph is wasteful and silly. This function lets you control how accurate the limiting is, whether it will chop things exactly where you specify, or whether you're willing to let some text slip through to get a better appearance.
Parameters:
  • prec: What amount over your limit you're willing to accept. For example, if you're willing to accept up to 10% more than your limit, $prec would be 0.1; 25% more would be 0.25; and so on. The default is 0.15, or up to 15% more than your limit. If you want the text chopped very exactingly at your limit, use a $prec value of 0.
float BBCode::GetLimitPrecision ( )
This function returns the current output-limit precision. See SetLimitPrecision() for more details.
Return values: Returns the current output-limit precision.
void BBCode::SetLimitTail ( string $tail )
When limiting text, it's often desirable to append some kind of text to the end of a string that gets cut off. For example, you may want to add "..." to a string to show that it has been cut. This function lets you specify what gets added to a chopped-off string.
Parameters:
  • tail: If your input gets truncated, this will be appended to the end of the output, before any closing tags and whitespace. The default value is "...", but other common values are " [more]" and " [cont'd]". The tail must be HTML, not plain-text or BBCode.
string BBCode::GetLimitTail ( )
This function returns the current output-limit tail string. See SetLimitTail() for more details.
Return values: Returns the current output-limit tail HTML.
bool BBCode::WasLimited ( )
This function returns true if the most-recently-generated output from Parse() was cut off as the result of an output limit. This provides you with a way to determine whether or not the limit was applied to the input or was unneeded.
Return values: Returns true if the output was truncated, or false if the output was complete.

[ Previous: B. Core Parsing Functions | Next: D. Content-Trimming Functions ]

Copyright © 2010, the Phantom Inker. All rights reserved.