/ 
App-ZofCMS-Plugin-BasicLWP-0.0103
/ App::ZofCMS::Plugin::BasicLWP

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 SYNOPSYS 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>

AUTHOR

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

BUGS

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.

SUPPORT

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

perldoc App::ZofCMS::Plugin::BasicLWP

You can also look for information at:

COPYRIGHT & LICENSE

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.