DevGuide TextFilters

MDG: Creating Text Filters

One of the very first Melody plugins ever created was a simple text filter. Text filters are used to transform the plain text input by a user into the entry and page editing interfaces, or through a commenting form into some other format. This first plugin called "Convert Line Breaks" made it possible for someone to enter the follow text into Melody:

Last night I had a great time with some friends.

We went to a restaurant and then a movie.

To the following:

Last night I had a great time with some friends.<br />
<br />
We went to a restaurant and then a movie.

The added break tags (<br />) helps preserve the formatting of the original text without requiring the user to know HTML.

Melody ships with several built in text filters, including:

• Markdown
• Textile
• SmartyPants
• Convert line breaks

Each of these text filters converts the text written in an alternate markup into the corresponding HTML syntax. However, there are many other possible uses for a text transformation plugin including one that may auto-correct spelling, automatically link certain words to specific websites, etc.

Note: The text entered by the user is stored in the database in its original form. The transformation occurs at the time the entry is published only.

To register a text filter, use the following code sample:

name: Example Plugin for Melody
id: Example
description: This plugin is an example plugin for Melody.
version: 1.0
text_filters:
    mytransform:
        label: My Text Transform
        handler: $Example::Example::Plugin::mytransform
        condition: $Example::Example::Plugin::mytransform_when

There are a number of properties for a text filter that can used when registering the text filter with Melody. These options are:

• label - the display name of the text filter as it will appear in the Melody user interface

• handler - a reference to a subroutine responsible for handling the transformation

• condition - in the event that the text filter should only be applied under specific conditions, one can identify a reference to a subroutine that will return true if the filter can be applied, and false otherwise.

Text Filter Handler

The text filter handler is simple. It takes a single argument as input: the text being transformed. It then is responsible for returning the transformed text.

The example below works by converting all instances of the word "cat" with "dog."

package Example::Plugin;
use strict;

sub mytransform {
    my ($str) = @_;
    $str =~ s/\bcat\b/dog/mg;
    return $str;
}

1; # Every module must return true

Conditional Text Filtering

In the code sample above where a text filter is registered with Melody, a condition is defined under which text filtering is allowed. The call back determines whether or not the text filter can be selected by a user via the web interface. The callback is called with a single parameter, the type of the object being transformed. Allowable values for the object type are:

• "entry"
• "comment"

The callback should return "1" if filtering is allowed, and "0" otherwise.

# Will only allow the text filter to be applied to comments
sub transform_when {
    my ($obj_type) = @_;
    return 1 if $obj_type && ($obj_type eq 'comment');
}

Continue Reading

• MDG: Custom OpenID Authentication Handlers

 

Questions, comments, can't find something? Let us know at our community outpost on Get Satisfaction.

Credits

• Author: Byrne Reese
• Edited by: