NAME

App::ZofCMS::Plugin::BasicLWP - very basic "uri-to-content" style LWP plugin for ZofCMS.

SYNOPSIS

In your ZofCMS Template or Main Config File:

    plugins => [ qw/BasicLWP/ ],
    plug_basic_lwp => {
        t_key   => 't',
        uri     => 'http://zofdesign.com/'
    },

In your HTML::Template template:

    <div id="funky_iframe">
        <tmpl_if name='plug_basic_lwp_error'>
            <p>Error fetching content: <tmpl_var name='plug_basic_lwp_error'></p>
        <tmpl_else>
            <tmpl_var name='plug_basic_lwp'>
        </tmpl_if>
    </div>

DESCRIPTION

The module is a plugin for App::ZofCMS. It provides basic functionality to fetch a random URI with LWP::UserAgent and stick the content into ZofCMS Template hashref.

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

MAIN CONFIG FILE AND ZofCMS TEMPLATE FIRST-LEVEL KEYS

plugins

    plugins => [ qw/BasicLWP/ ],

You need to add the plugin to the list of plugins to execute. Since you are likely to work on the fetched data, make sure to set correct priorities.

plug_basic_lwp

    plug_basic_lwp => {
        uri     => 'http://zofdesign.com/', # everything but 'uri' is optional
        t_name  => 'plug_basic_lwp',
        t_key   => 'd',
        decoded => 0,
        fix_uri => 0,
        ua_args => [
            agent   => 'Opera 9.2',
            timeout => 30,
        ],
    }

The plugin won't run unless plug_basic_lwp first-level key is present either in Main Config File or ZofCMS Template. Takes a hashref or a subref as a value. If subref is specified, its return value will be assigned to plug_basic_lwp 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. If the same keys are specified in both Main Config File and ZofCMS Template, then the value set in ZofCMS template will take precedence. The possible keys/values of that hashref are as follows:

uri

    uri => 'http://zofdesign.com/',

    uri => sub {
        my ( $template, $query, $config ) = @_;
        return $query->{uri_to_fetch};
    }

    uri => URI->new('http://zofdesign.com/');

Mandatory. Takes a string, subref or URI object as a value. Specifies the URI to fetch. When value is a subref that subref will be executed and its return value will be given to uri argument. Subref's @_ will contain the following (in that order): ZofCMS Template hashref, hashref of query parameters and App::ZofCMS::Config object. Plugin will stop if the uri is undefined; that also means that you can return an undef from your subref to stop processing.

t_name

    t_name => 'plug_basic_lwp',

Optional. See also t_key parameter below. Takes a string as a value. This string represents the name of the key in ZofCMS Template where to put the fetched content (or error). Note: the errors will be indicated by $t_name . '_error' HTML::Template variable, where $t_name is the value of t_name argument. See SYNOPSIS for examples. Defaults to: plug_basic_lwp (and the errors will be in plug_basic_lwp_error

t_key

    t_key => 'd',

Optional. Takes a string as a value. Specifies the name of first-level key in ZofCMS Template hashref in which to create the t_name key (see above). Defaults to: d

decoded

    decoded => 0,

Optional. Takes either true or false values as a value. When set to a true value, the content will be given us with decoded_content(). When set to a false value, the content will be given us with content() method. See HTTP::Response for description of those two methods. Defaults to: 0 (use content())

fix_uri

    fix_uri => 0,

Optional. Takes either true or false values as a value. When set to a true value, the plugin will try to "fix" URIs that would cause LWP to crap out with "URI must be absolute" errors. When set to a false value, will attempt to fetch the URI as it is. Defaults to: 0 (fixing is disabled)

Note: the "fixer" is not that smart, here's the code; feel free not to use it :)

    $uri = "http://$uri"
        unless $uri =~ m{^(ht|f)tp://}i;

ua_args

    ua_args => [
        agent   => 'Opera 9.2',
        timeout => 30,
    ],

Optional. Takes an arrayref as a value. This arrayref will be directly dereference into LWP::UserAgent contructor. See LWP::UserAgent's documentation for possible values. Defaults to:

    [
        agent   => 'Opera 9.2',
        timeout => 30,
    ],

HTML::Template VARIABLES

The code below assumes default values for t_name and t_key arguments (see plug_basic_lwp hashref keys' description).

    <tmpl_if name='plug_basic_lwp_error'>
        <p>Error fetching content: <tmpl_var name='plug_basic_lwp_error'></p>
    <tmpl_else>
        <tmpl_var name='plug_basic_lwp'>
    </tmpl_if>

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.

cpanm App::ZofCMS

perl -MCPAN -e shell
install App::ZofCMS