/ 
App-ZofCMS-Plugin-LinkifyText-0.0102
/ App::ZofCMS::Plugin::LinkifyText

NAME

App::ZofCMS::Plugin::LinkifyText - plugin to convert links in plain text into proper HTML <a> elements

SYNOPSIS

In ZofCMS Template or Main Config File:

plugins => [
    qw/LinkifyText/,
],

plug_linkify_text => {
    text => qq|http://zoffix.com foo\nbar\nhaslayout.net|,
    encode_entities => 1, # this one and all below are optional; default values are shown
    new_lines_as_br => 1,
    cell => 't',
    key  => 'plug_linkify_text',
    callback => sub {
        my $uri = encode_entities $_[0];
        return qq|<a href="$uri">$uri</a>|;
    },
},

In HTML::Template template:

<tmpl_var name='plug_linkify_text'>

DESCRIPTION

The module is a plugin for App::ZofCMS that provides means convert URIs found in plain text into proper <a href=""> HTML elements.

This documentation assumes you've read App::ZofCMS, App::ZofCMS::Config and App::ZofCMS::Template

FIRST-LEVEL ZofCMS TEMPLATE AND MAIN CONFIG FILE KEYS

plugins

plugins => [
    qw/LinkifyText/,
],

Mandatory. You need to include the plugin to the list of plugins to execute.

plug_linkify_text

plug_linkify_text => {
    text => qq|http://zoffix.com foo\nbar\nhaslayout.net|,
    encode_entities => 1,
    new_lines_as_br => 1,
    cell => 't',
    key  => 'plug_linkify_text',
    callback => sub {
        my $uri = encode_entities $_[0];
        return qq|<a href="$uri">$uri</a>|;
    },
},

plug_linkify_text => {
    text => qq|http://zoffix.com foo\nbar\nhaslayout.net|,
    encode_entities => 1,
    new_lines_as_br => 1,
    cell => 't',
    key  => 'plug_linkify_text',
    callback => sub {
        my $uri = encode_entities $_[0];
        return qq|<a href="$uri">$uri</a>|;
    },
},

plug_linkify_text => sub {
    my ( $t, $q, $config ) = @_;
    return {
        text => qq|http://zoffix.com foo\nbar\nhaslayout.net|,
    }
}

Mandatory. Takes a hashref or a subref as a value; individual keys can be set in both Main Config File and ZofCMS Template, if the same key set in both, the value in ZofCMS Template will take precedence. If subref is specified, its return value will be assigned to plug_linkify_text as if it was already there. If sub returns an undef, then plugin will stop further processing. The @_ of the subref will contain (in that order): ZofCMS Tempalate hashref, query parameters hashref and App::ZofCMS::Config object. The following keys/values are accepted:

text

plug_linkify_text => {
    text => qq|http://zoffix.com foo\nbar\nhaslayout.net|,
}

plug_linkify_text => {
    text => [
        qq|http://zoffix.com|,
        qq|foo\nbar\nhaslayout.net|,
    ]
}

Mandatory. Can be set to either a string of text, arrayref of strings of text or a subref. If value is a subref its @_ will contain (in this order) ZofCMS Template hashref, query parameters hashef and App::ZofCMS::Config object. The return value will be assigned to text argument as if it was there originally. undef values will cause the plugin to stop executing any further. The one string vs. arrayref values affect plugin's output format. See OUTPUT section below for details.

encode_entities

plug_linkify_text => {
    text => qq|http://zoffix.com foo\nbar\nhaslayout.net|,
    encode_entities => 1,
}

Optional. Takes either true or false values. When set to a true value, plugin will encode HTML entities in the provided text before processing URIs. Defaults to: 1

new_lines_as_br

plug_linkify_text => {
    text => qq|http://zoffix.com foo\nbar\nhaslayout.net|,
    new_lines_as_br => 1,
}

Optional. Applies only when encode_entities (see above) is set to a true value. Takes either true or false values. When set to a true value, the plugin will convert anything that matches /\r?\n/ into HTML <br> element. Defaults to: 1

cell

plug_linkify_text => {
    text => qq|http://zoffix.com foo\nbar\nhaslayout.net|,
    cell => 't',
}

Optional. Takes a literal string as a value. Specifies the name of the first-level key in ZofCMS Template hashref into which to put the result; this key must point to either an undef value or a hashref. See key argument below as well. Defaults to: t

key

plug_linkify_text => {
    text => qq|http://zoffix.com foo\nbar\nhaslayout.net|,
    key  => 'plug_linkify_text',
}

Optional. Takes a literal string as a value. Specifies the name of the second-level key that is inside cell (see above) key - plugin's output will be stored into this key. Defaults to: plug_linkify_text

callback

plug_linkify_text => {
    text => qq|http://zoffix.com foo\nbar\nhaslayout.net|,
    callback => sub {
        my $uri = encode_entities $_[0];
        return qq|<a href="$uri">$uri</a>|;
    },
},

Optional. Takes a subref as a value. This subref will be used as the "callback" sub in URI::Find::Schemeless's find() method. See URI::Find::Schemeless for details. Defaults to:

sub {
    my $uri = encode_entities $_[0];
    return qq|<a href="$uri">$uri</a>|;
},

OUTPUT

$VAR1 = {
    't' => 'plug_linkify_text' => '<a href="http://zoffix.com/">http://zoffix.com/</a>'
};

$VAR1 = {
    't' => 'plug_linkify_text' => [
        { text => '<a href="http://zoffix.com/">http://zoffix.com/</a>' },
        { text => '<a href="http://zoffix.com/">http://zoffix.com/</a>' },
};

Depending on whether text plugin's argument is set to a string or an arrayref of strings, the plugin will set the key key under cell first-level key to either a converted string or an arrayref of hashrefs respectively. Each hashref will have only one key - text - value of which is the converted text (thus you can use this arrayref directly in <tmpl_loop>).

AUTHOR

'Zoffix, <'zoffix at cpan.org'> (http://haslayout.net/, http://zoffix.com/, http://zofdesign.com/)

BUGS

Please report any bugs or feature requests to bug-app-zofcms-plugin-linkifytext at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=App-ZofCMS-Plugin-LinkifyText. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc App::ZofCMS::Plugin::LinkifyText

You can also look for information at:

COPYRIGHT & LICENSE

Copyright 2009 'Zoffix, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.