NAME

Statocles::Plugin - Base role for Statocles plugins

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:

• 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.