NAME

Statocles::Plugin - Base role for Statocles plugins

VERSION

version 0.075

SYNOPSIS

# lib/My/Plugin.pm
package My::Plugin;
use Moo; # or Moose
with 'Statocles::Plugin';

sub register {
    my ( $self, $site ) = @_;
    # Register things like event handlers and theme helpers
}

1;

# site.yml
site:
    args:
        plugins:
            name:
                $class: My::Plugin

DESCRIPTION

Statocles Plugins are attached to sites and add features such as template helpers and event handlers.

This is the base role that all plugins should consume.

OVERVIEW

CONFIGURATION

Site-level configuration of a plugin can be placed in the configuration file, usually site.yml as arguments:

# site.yml
site:
    args:
        plugins:
            name:
                $class: My::Plugin
                $args:
                     myattr: 'value'

The argument name and value type must match a declaration in the plugin itself. For example,

package My::Plugin {
    use Statocles::Base 'Class';
    with 'Statocles::Plugin';

    has myattr => (
        is => 'ro',
        isa => Str,
        default => sub { 'a default value' },
    )
    ...

EVENT HANDLERS

Most plugins will want to attach to one or more Statocles event handlers in their registration. This example creates a template helper myplug and also hooks into the before_build_write event.

sub plugger {
    my ( $self, $args, @helper_args ) = @_;
    ...
}

sub _plugboard {
    my ( $self, $pages, @args ) = @_;
    ...
}

sub register {
    my ( $self, $site ) = @_;
    # We register our event handlers and theme helpers:
    $site->theme->helper( myplug => sub { $self->plugger( @_ ) } );
    $site->on( before_build_write => sub { $self->_plugboard( @_ ) } );
    return $self;
}

The event handler itself, like _plugboard above, receives arguments from the event. For before_build_write this is a Statocles::Event::Pages object.

HELPER FUNCTIONS

A helper function like plugger above receives first the template variables and then all the helper arguments supplied in the template itself. In the example above (section "Event Handlers"), $args would be a hash with these keys: =over

• app The current app, e.g., "Statocles::App::Basic"

• doc The current document, e.g., of class Statocles::Document

• page The current page, e.g., of class Statocles::Page::Document

• site The current site, e.g., of class Statocles::Site

METHODS

register

$plugin->register( $site );

Register this plugin with the given Statocles::Site object. This is called automatically when the site is created.

BUNDLED PLUGINS

These plugins come with Statocles. More plugins may be available from CPAN.

Statocles::Plugin::LinkCheck

Check your site for broken links and images.

Statocles::Plugin::Highlight

Syntax highlighting for code and configuration.

Statocles::Plugin::HTMLLint

Check your HTML for best practices.

AUTHOR

Doug Bell <preaction@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2016 by Doug Bell.

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

cpanm Statocles

perl -MCPAN -e shell
install Statocles