The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
App-ZofCMS-1.001004
River stage one • 1 direct dependent • 1 total dependent
++
/ 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|,
        ]
    }

    plug_linkify_text => {
        text => sub {
            my ( $t, $q, $config ) = @_;
            return $q->{text_to_linkify};
        },
    }

    plug_linkify_text => {
        text  => \[ qw/replies  reply_text/ ],
        text2 => 'post_text',
        text3 => [ qw/comments  comment_text  comment_link_text/ ],
    }

Pseudo-Mandatory; if not specified (or undef) plugin will not run. Takes a wide range of values:

subref

    plug_linkify_text => {
        text => sub {
            my ( $t, $q, $config ) = @_;
            return $q->{text_to_linkify};
        },
    }

If set to a subref, the sub's @_ will contain $t, $q, and $config (in that order), where $t is ZofCMS Template hashref, $q is query parameter hashref, and $config is App::ZofCMS::Config object. The return value from the sub can be any valid value accepted by the text argument (except the subref) and the plugin will proceed as if the returned value was assigned to text in the first place (including the undef, upon which the plugin will stop executing).

scalar

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

If set to a scalar, the plugin will interpret the scalar as the string that needs to be linkified (i.e. links in the text changed to HTML links). Processed string will be stored into key key under cell first-level key (see the description for these below).

arraref

    plug_linkify_text => {
        text => [
            qq|http://zoffix.com|,
            qq|http://zoffix.com|,
        ]
    }

    # output:
    $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>' },
    };

If set to an arrayref, each element of that arrayref will be taken as a string that needs to be linkified. The output will be stored into key key under cell first-level key, and that output will be an arrayref of hashrefs. 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>)

a ref of a ref

    plug_linkify_text => {
        text  => \[ qw/replies  reply_text/ ],
        text2 => 'post_text',
        text3 => [ qw/comments  comment_text  comment_link_text/ ],
    }

Lastly, text can be set to a... ref of a ref (bare with me). I think it's easier to understand the functionality when it's viewed as a following sequential process:

When text is set to a ref of a ref, the plugin enables the inplace edit mode. This is as far as this goes, and plugin dereferences this ref of a ref into an arrayref or a scalarref. Along with a simple scalar, these entities can be assigned to any extra text keys (see below). What inplace edit mode means is that text no longer contains direct strings of text to linkify, but rather an address of where to find, and edit, those strings.

When inplace mode is turned on, you can tell plugin to linkify multiple places. In order to specify another address for a string to edit, simply add another text postfixed with a number (e.g. text4; what the actual number is does not matter, the key just needs to match qr/^text\d+$/). The values of all the extra text keys do not have to be refs of refs, but rather can be either scalars, scalarrefs or arrayrefs.

A scalar and scalarref have same meaning here, i.e. the scalarref will be automatically dereferenced into a scalar. A simple scalar tells the plugin that the value of this scalar is the name of a key inside {t} ZofCMS Template special key, value of which contains the text to be linkified. The plugin will directly modify (linkify) that text. This can be used, for example, when you use App::ZofCMS::Plugin::DBI plugin's "single" retrieval mode.

The arrayrefs have different meaning. Their purpose is to process arrayrefs of hashrefs (this will probably conjure up App::ZofCMS::Plugin::DBI plugin's output in your mind). The first item in the arrayref represents the name of the key inside the {t} ZofCMS Template special key's hashref; the value of that key is the arrayref of hashrefs. All the following (one or more) items in the arrayref represent hashref keys that point to data to linkify.

Let's take a look at actual code examples. Let's imagine your {t} special key contains the following arrayref, say, put there by DBI plugin; this arrayref is referenced by a dbi_output key here. Also in the example, the dbi_output_single is set to a scalar, a string of text that we want to linkify:

    dbi_output => [
        { ex => 'foo', ex2 => 'bar' },
        { ex => 'ber', ex2 => 'beer' },
        { ex => 'baz', ex2 => 'craz' },
    ],
    dbi_output_single => 'some random text',

If you want to linkify all the texts inside dbi_output to which the ex keys point, you'd set text value as text => \[ qw/dbi_output ex/ ]. If you want to linkify the ex2 data as well, then you'd set text as text => \[ qw/dbi_output ex ex2/ ]. Can you guess what the code to linkify all the text in the example above will be? Here it is:

    # note that we are assigning a REF of an arrayref to the first `text`
    plug_linkify_text => {
        text    => \[
            'dbi_output',  # the key inside {t}
            'ex', 'ex2'    # keys of individual hashrefs that point to data
        ],
        text2   => 'dbi_output_single', # note that we didn't have to make this a ref
    }

    # here's an alternative version that does the same thing:
    plug_linkify_text => {
        text    => \\'dbi_output_single', # note that this is a ref of a ref
        text554 => [  # this now doesn't have to be a ref of a ref
            'dbi_output',  # the key inside {t}
            'ex', 'ex2'    # keys of individual hashrefs that point to data
        ],
    }

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>|;
    },

REPOSITORY

Fork this module on GitHub: https://github.com/zoffixznet/App-ZofCMS

BUGS

To report bugs or request features, please use https://github.com/zoffixznet/App-ZofCMS/issues

If you can't access GitHub, you can email your request to bug-App-ZofCMS at rt.cpan.org

AUTHOR

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

LICENSE

You can use and distribute this module under the same terms as Perl itself. See the LICENSE file included in this distribution for complete details.