/ 
Blosxom-Plugin-0.02004
River stage zero No dependents
/ Blosxom::Plugin

NAME

Blosxom::Plugin - Base class for Blosxom plugins

SYNOPSIS

package my_plugin;
use strict;
use warnings;
use parent 'Blosxom::Plugin';

# generates a class attribute called foo()
__PACKAGE__->mk_accessors( 'foo' );

# does Blosxom::Plugin::DataSection
__PACKAGE__->load_components( 'DataSection' );

sub start {
    my $pkg = shift;

    $pkg->foo( 'bar' );
    my $value = $pkg->foo; # => "bar"

    my $template = $pkg->get_data_section( 'my_plugin.html' );
    # <!DOCTYPE html>
    # ...

    # merge __DATA__ into Blosxom default templates
    $pkg->merge_data_section_into( \%blosxom::template );

    return 1;
}

1;

__DATA__

@@ my_plugin.html

<!DOCTYPE html>
<html>
<head>
  <title>My Plugin</title>
</head>
<body>
<h1>Hello, world</h1>
</body>
</html>

DESCRIPTION

This module enables Blosxom plugins to create class attributes and load additional components.

Blosxom never creates instances of plugins, and so they can't have instance attributes. This module creates class attributes instead, and always undefines them after all output has been processed.

Components will abstract routines from Blosxom plugins. It's intended that they will be shared on CPAN.

METHODS

$class->mk_accessors( @fields )
$class->mk_accessors({ $field => \&default, ... })

This creates class attributes for each named field given in @fields.

__PACKAGE__->mk_accesssors(qw/foo bar car/);

Attributes can have default values which is not generated until the field is read. &default is called as a method on the class with no additional parameters.

use Path::Class::File;

__PACKAGE__->mk_accessors({
    'path' => undef,
    'file' => sub {
        my $pkg = shift; # => "my_plugin"
        Path::Class::File->new( $pkg->path );
    },
});

sub start {
    my $pkg = shift;

    $pkg->path( '/path/to/entry.txt' );
    my $path = $pkg->path; # => "/path/to/entry.txt"

    # file() is a Path::Class::File object
    my $basename = $pkg->file->basename; # => "entry.txt"

    return 1;
}
$class->load_components( @components )
$class->load_components( $component => \%configuration, ... )

Loads the given components into the current module. Components can be configured by the loaders. If a module begins with a + character, it is taken to be a fully qualified class name, otherwise Blosxom::Plugin is prepended to it.

__PACKAGE__->load_components( '+MyComponent' => \%config );

This method calls init() method of each component. init() is called as follows:

MyComponent->init( 'my_plugin', \%config )

If multiple components are loaded in a single call, then if any of their provided methods clash, an exception is raised unless the class provides the method.

$class->add_method( $method_name => $coderef )

This method takes a method name and a subroutine reference, and adds the method to the class. Available while loading components. If a method is already defined on the class, that method will not be added.

package MyComponent;

sub init {
    my ( $class, $caller, $config ) = @_;
    $caller->add_method( 'foo' => sub { ... } );
}
$class->add_attribute( $attribute_name )
$class->add_attribute( $attribute_name, \&default )

This method takes an attribute name, and adds the attribute to the class. Available while loading components. Attributes can have default values which is not generated until the attribute is read. &default is called as a method on the class with no additional arguments.

sub init {
    my ( $class, $caller ) = @_;
    $caller->add_attribute( 'foo' );
    $caller->add_attribute( 'bar' => sub { ... } );
}
$class->add_component( $component )
$class->add_component( $component => \%configuration )

This adds the component to the list of components to be loaded while loading components.

sub init {
    my ( $class, $caller ) = @_;
    $caller->add_component( 'DataSection' );
}
$bool = $class->has_method( $method_name )

Returns a Boolean value telling whether or not the class defines the named method. It does not include methods inherited from parent classes.

$class->end

Undefines class attributes generated by mk_accessors() or add_attribute(). Since end() is one of recognized hooks, it's guaranteed that Blosxom always invokes this method.

sub end {
    my $class = shift;
    # do something
    $class->SUPER::end;
}
$class->dump( $max_depth )

This method uses Data::Dumper to dump the class attributes. You can pass an optional maximum depth, which will set $Data::Dumper::Maxdepth. The default maximum depth is 1.

DEPENDENCIES

Blosxom 2.0.0 or higher.

SEE ALSO

Blosxom::Plugin::Web, Amon2, Moose::Manual::Roles, MooseX::Role::Parameterized::Tutorial

ACKNOWLEDGEMENT

Blosxom was originally written by Rael Dohnfest. The Blosxom Development Team succeeded to the maintenance.

BUGS AND LIMITATIONS

There are no known bug in this module. Please report problems to ANAZAWA (anazawa@cpan.org). Patches are welcome.

AUTHOR

Ryo Anazawa <anazawa@cpan.org>

LICENSE AND COPYRIGHT

Copyright (c) 2012 Ryo Anzawa. All rights reserved.

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

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.