view release on metacpan or  search on metacpan

lib/App/ZofCMS/Plugin/LinkifyText.pm  view on Meta::CPAN

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

Lastly, C<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 C<text> is set to a ref of a ref, the plugin enables the I<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 I<extra> C<text> keys (see below).
What I<inplace> edit mode means is that C<text> no longer contains direct
strings of text to linkify, but rather an address of where to find,
and edit, those strings.

When I<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 C<text> postfixed with a number (e.g. C<text4>; what
the actual number is does not matter, the key just needs to match
C<qr/^text\d+$/>). The values of all the B<extra> C<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
C<{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 L<App::ZofCMS::Plugin::DBI> plugin's
"single" retrieval mode.

The arrayrefs have different meaning. Their purpose is to process
B<arrayrefs of hashrefs> (this will probably conjure up
L<App::ZofCMS::Plugin::DBI> plugin's output in your mind). The first
item in the arrayref represents the name of the key inside the
C<{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 C<{t}>
special key contains the following arrayref, say, put there by DBI plugin;
this arrayref is referenced by a C<dbi_output> key here. Also in the
example, the C<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 C<dbi_output>
to which the C<ex> keys point, you'd set C<text> value as
C<< text => \[ qw/dbi_output  ex/ ] >>. If you want to linkify the C<ex2>
data as well, then you'd set C<text> as
C<< text => \[ qw/dbi_output  ex  ex2/ ] >>. Can you guess what the code
to linkify I<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
        ],
    }

=head3 C<encode_entities>

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

B<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. B<Defaults to:> C<1>

=head3 C<new_lines_as_br>

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

B<Optional>. Applies only when C<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 C</\r?\n/>
into HTML <br> element. B<Defaults to:> C<1>

=head3 C<cell>

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

B<Optional>. Takes a literal string as a value. Specifies the name
of the B<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 C<key> argument below as well.
B<Defaults to:> C<t>

=head3 C<key>

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