File: README — Documentation for bbcodeizer (0.1.2)

BBCodeizer

BBCodeizer is a gem used to translate BBCode to HTML. The main interface is provided through the helper method “bbcodeize.” Use of it is as simple as passing a string to bbcodeize:

<%= bbcodeize post.body %>

You can also invoke the BBCodeizer directly without the helper:

render :text => BBCodeizer.bbcodeize(post.body)

All settings are centralized so you can very quickly deactivate any tag or modify the HTML that is generated. You can modify these settings by adding lines to the end of your environment.rb. For example:

# deactivate [color], [size], and [code] tags
BBCodeizer.deactivate(:color, :size, :code)

# use <b> instead of <strong>
BBCodeizer.replace_using(:bold, '<b>\1</b>')

These changes should be considered one-time configuration, e.g. tags cannot be deactivated then activated again.

Warning

While BBCodeizer does some validation (see below), you should be aware it is possible to create unsafe HTML in the wrong hands (for example, invoking Javascript using the [url] tag). It is highly recommended you run the resulting HTML through a sanity checker such as WhiteList:

http://svn.techno-weenie.net/projects/plugins/white_list/

Once installed, the following is a helper method that will produce nicely formatted, safe HTML:

def format_text(text)
  white_list(simple_format(auto_link(bbcodeize(h(text)))))
end

Supported Tags

BBCodeizer currently supports the following tags. The default HTML expansion is documented here.

[u]text[/u]

  <u>text</u>

[b]text[/b]

  <strong>text</strong>

[i]text[/i]

  <em>text</em>

[img]http://example.com/image.gif[/img]

  <img src="http://example.com/image.gif" />

[[email protected]]Joe Example[/email]

  <a href="mailto:[email protected]">Joe Example</a>

[email][email protected][/email]

 <a href="mailto:[email protected]">[email protected]</a>

[code]bbcodeize(string)[/code]

  <pre>bbcodeize(string)</pre>

[url=http://www.google.com]Google[/url]

  <a href="http://www.google.com">Google</a>

[url]http://www.google.com[/url]

  <a href="http://www.google.com">http://www.google.com</a>

[quote="Shakespeare"]To be or not to be[/quote]

  <blockquote><cite>Shakespeare wrote:</cite><br />To be or not to
be</blockquote>

[quote]That is the question[/quote]

  <blockquote>That is the question</blockquote>

[size=32]Big Text[/size]

  <span style="font-size: 32px">Big Text</span>

[color=red]Red Text[/color] [color=#ABCDEF]Alphabet-colored Text[/color]

  <span style="color: red">Red Text</span>
  <span style="color: #ABCDEF">Alphabet Colored Text</span>

Validation

BBCodeizer aims to produce HTML that will not break your site - all opening tags must have a closing tag or they will not be replaced (unmatched tags are left as-is). All [code] and [quote] tags are left entirely untouched if there is any mismatch with either of these. All other tags will replace as many as possible and leave the remaining unmatched tags as-is.

BBCodeizer attempts to produce XHTML-compliant markup, however, misuse of nesting tags is not validated or corrected. For example:

[b]bold [u]bold + underline[/b] underline[/u]

Will produce the following HTML:

<strong>bold <u>bold + underline</strong> underline</u>

Colors in the [color] tag are not validated - any string can be used. Strings containing semicolons are not allowed to prevent users from adding additional style rules.

Sizes used in the [size] tag are validated - only 1 or 2 digit numbers are accepted.