milesjohnson

For each string or block of text that you want parsed, you would need to initiate a new Decoda object by passing the string variable into the class constructor. We create a new object for each string so that we may alter its output, and not conflict for other strings that may be on the page.

// Include the class
include('decoda.php');
 
// String to be parsed
$string = 'Hello, my name is [b]Miles Johnson[/b], you may visit my website at [url]http://www.milesj.me/[/url].';
 
// Load the text and parse
$code = new Decoda($string);
$code->parse();

If you would like the parsed string to be returned instead of echoed, you would pass an argument of true to the parse() method.

$string = $code->parse(true);

In the next section, you will learn how to toggle the settings for auto-clickable links/emails, shorthand links/emails and making the output XHTML.

Auto-Clickables
Decoda by default will automatically take any links and emails (that are not wrapped with [url] and [mail]) and turn them into clickable hyperlinks. To disable this feature, you would use the makeClickable method(). Be sure to pass a boolean value of true or false as the argument.

$code = new Decoda($string);
$code->makeClickable(false);
$code->parse();

Shorthand Links
If you would like a hyperlink to display its shorthand variant (displaying the word link or mail, instead of the text/url/email), you would call the method useShorthand(). You would call it the same way as makeClickable().

$code->useShorthand(false);

Enabling GeSHi
To enable or disable GeSHi's code syntax highlighting, you would call the useGeshi() method.

$code->useGeshi(false);

Using XHTML
By default, all strings are parsed as HTML 4.1, if you would like to use XHTML, you will need to edit the $xhtml property manually. There is no wrapper method to alter this setting, so you will need to find the $xhtml property in the decoda.php class file and set it to true or false.

You may restrict what tags should be parsed by passing an array of the tag names within the constructor. This is very useful for certain areas of your site where you want only bold, italics and underline available, and to not parse the other code.

The following default tag names are: b, i, u, align, color, font, h16, size, sub, sup, code, url, email, img, div, quote, list and any others you add with addMarkup().

$code = new Decoda($string, array('b', 'i', 'u'));
$code->parse();

CakePHP Alternative
Using the restrictions in the CakePHP helper is a tad different. You would apply them as a third argument in the parse() method, like so.

$decoda->parse($string, false, array('b', 'i', 'u'));

If for some reason the tag you want to have is not supported by Decoda, you can use the addMarkup() method. Alternatively you can edit the decoda.php class file itself and add your tag to the $markup property. This method will only work for basic find and replacing, no callbacks are supported. A good understanding of regional expressions is required.

$code = new Decoda($string);
$code->addMarkup('p', '/\[p\](.*?)\[\/p\]/is', '<p>$1</p>');
$code->parse();

Now that you have learned how to parse the markup, I will need to show you how the markup is written. If you have used BB code before (on a forum system), this should be relatively easy for you. Lets begin with the basic tags.

Basics
The most basic of tags will require no attributes at all, these tags are: b, i, u, code, sup, sub, h1-h6. To use these tags, you would place the tag around the string you want altered. For example if you want some text to be bolded, you would do the following:

// Examples
[b]Bold[/b] 		// Outputs <strong>Bold</strong>
[i]Italics[/i]		// Outputs <em>Italics</em>
[h3]Title[/h3]		// Outputs <h3>Title</h3>

Images
Unlike most BB code systems, this system allows img tags to use attributes. You are able to add a width and height attribute, which will accept an integer and a percentage. The following examples will work:

[img]http://www.domain.com/image.jpg[/img]
[img width=100]http://www.domain.com/image.jpg[/img]
[img height=50%]http://www.domain.com/image.gif[/img]
[img width=100 height=50]http://www.domain.com/image.png[/img]

Links and Emails
There are a few variations for using the link and email tags. In the example below are all the variations that are possible. All these variations will work, regardless of your $useShorthand setting.

// Links
[url]http://www.domain.com[/url]
[url=http://www.domain.com]My Website![/url]

// Emails
[mail]email@domain.com[/mail]
[mail=email@domain.com]Email Me![/mail]

// You can also use [email] instead of [mail]

Divs
If you ever need to create a div element, you can do so with the div tags. You can pass an id and a class; you may also use multiple classes, just separate the classes with a space.

[div id="content"]Content[/div]
[div class="clear float"]Content[/div]

Quotes
Quotes work in a similar fashion to other BB code parsers. You may supply an author, or do a stand alone quote. When using an author, the author name has to be surrounded by double quotes.

[quote]Content[/quote]
[quote="Author Name"]Content[/quote]

Lists
And finally we get to the lists. Currently, only the ul tag is supported with lists.

[list]
[li]Item 1[/li]
[li]Item 2[/li]
[li]Item 3[/li]
[/list]

Floating Content
You can use the float tags to place images, content, etc on the left or the right. If you use the float tag, you must clear the floats with CSS manually.

[float=left]Image[/float]

The CakePHP Helper works nearly the same as the stand-alone class, but can easily be installed. All you need to do is add it to your controllers $helpers array like so.

var $helpers = array('Decoda');

Once you have enabled the Helper, you can use it in the view like the following. To change the settings (make clickable, shorthand, etc) you would set the property itself within the view, instead of calling a function like the stand-alone version.

// In the views
// Display a blog post
$decoda->parse($blog['Blog']['content']);
 
// Return instead of echoing
$content = $decoda->parse($blog['Blog']['content'], true);
 
// Change the settings before parseing content
$decoda->useShorthand = true;
$decoda->makeClickable = false;
$decoda->parse($blog['Blog']['content']);

The addMarkup() method has been removed from the Decoda Helper version. The $xhtml property was also removed, seeing as how the Form/Html Helpers always output XHTML.

If you don't know what GeSHi is, its a syntax highlighter for code blocks. This would allow your code blocks to display the code in colored formats, depending on the requested language. By default, GeSHi is enabled within the script. To apply color formatting to a code block, you would pass a language tag (without the spaces of course).

[ code lang="php"]<?php // PHP ?>[/ code]

Decoda will apply the basic and fastest settings for GeSHi, but you can apply your own settings by using the setupGeshi() method. You would pass an array of settings to the method. Below is a list of all the settings.

$code->setupGeshi(array(
    'container' 	=> 'pre',	// What to wrap it with: div, pre, table, false
    'line_numbers'	=> false,	// Display line numbers on the left
    'start_number' 	=> 1,		// What number to start the line numbers at
    'use_css'		=> false,	// Use CSS classes instead of styles (needs your own CSS file)
    'auto_casing'	=> false,	// Apply text-transformation to keywords: upper, lower, false
    'tab_width'		=> false,	// How many spaces to indent for a tab (div container only)
    'strict_mode'	=> false	// Code blocks must require opening tags (<?php ?>, etc)
));
 
// In CakePHP you would pass the settings when adding the helper
var $helpers = array('Decoda' => array(
    'geshi' => array(
   		'container' => 'div'
    ),
    'censored' => array()
));

CakePHP Installation
If you are using the CakePHP helper and would like to use GeSHi, you would need to place the geshi folder (within the zip) in your vendors folder.

Troubleshooting
If you are running the script correctly, using the correct lang tag and GeSHi still isn't working, it means the GeSHi class cannot be located. Check your paths and debug it till it works. The way Decoda is setup is that it will still run if GeSHi isn't located, it will just disable it.

So in the new 2.6 version of Decoda, you have the ability to censor words. Each censored word will be replaced by asterisks (****) equal to the length of the word. To add restricted words into the system, use the addCensored() method. It will take an array of words to censor.

$code->addCensored(array('word', 'that', 'will', 'be', 'censored'));

Applying censored words in CakePHP
To censor words in CakePHP is a little bit different. You would pass the censored words as an array when adding the helper; the words should be index by the word censored. The following example explains it more:

var $helpers = array('Decoda' => array(
    'geshi' => array(),
    'censored' => array('word', 'that', 'will', 'be', 'censored')
));