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

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>

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

    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 => {
        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 => '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 => '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 SYNOPSYS for examples. Defaults to: plug_basic_lwp (and the errors will be in plug_basic_lwp_error

    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 => 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 => 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 => [
        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,
    ],

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>

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

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

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

    perldoc App::ZofCMS::Plugin::BasicLWP

You can also look for information at:

* RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=App-ZofCMS-Plugin-BasicLWP

* AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/App-ZofCMS-Plugin-BasicLWP

* CPAN Ratings

http://cpanratings.perl.org/d/App-ZofCMS-Plugin-BasicLWP

* Search CPAN

http://search.cpan.org/dist/App-ZofCMS-Plugin-BasicLWP

Copyright 2008 'Zoffix, all rights reserved.

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