File Coverage

blib/lib/Statocles/Plugin.pm
Criterion Covered Total %
statement 3 3 100.0
branch n/a
condition n/a
subroutine 1 1 100.0
pod n/a
total 4 4 100.0


line stmt bran cond sub pod time code
1             package Statocles::Plugin;
2             our $VERSION = '0.086';
3             # ABSTRACT: Base role for Statocles plugins
4              
5             #pod =head1 SYNOPSIS
6             #pod
7             #pod # lib/My/Plugin.pm
8             #pod package My::Plugin;
9             #pod use Moo; # or Moose
10             #pod with 'Statocles::Plugin';
11             #pod
12             #pod sub register {
13             #pod my ( $self, $site ) = @_;
14             #pod # Register things like event handlers and theme helpers
15             #pod }
16             #pod
17             #pod 1;
18             #pod
19             #pod # site.yml
20             #pod site:
21             #pod args:
22             #pod plugins:
23             #pod name:
24             #pod $class: My::Plugin
25             #pod
26             #pod =head1 DESCRIPTION
27             #pod
28             #pod Statocles Plugins are attached to sites and add features such as template helpers
29             #pod and event handlers.
30             #pod
31             #pod This is the base role that all plugins should consume.
32             #pod
33             #pod =cut
34              
35 5     5   14697 use Statocles::Base 'Role';
  5         13  
  5         39  
36              
37             #pod =method register
38             #pod
39             #pod $plugin->register( $site );
40             #pod
41             #pod Register this plugin with the given L<Statocles::Site
42             #pod object|Statocles::Site>. This is called automatically when the site is
43             #pod created.
44             #pod
45             #pod =cut
46              
47             requires 'register';
48              
49             1;
50              
51             __END__
52              
53             =pod
54              
55             =encoding UTF-8
56              
57             =head1 NAME
58              
59             Statocles::Plugin - Base role for Statocles plugins
60              
61             =head1 VERSION
62              
63             version 0.086
64              
65             =head1 SYNOPSIS
66              
67             # lib/My/Plugin.pm
68             package My::Plugin;
69             use Moo; # or Moose
70             with 'Statocles::Plugin';
71              
72             sub register {
73             my ( $self, $site ) = @_;
74             # Register things like event handlers and theme helpers
75             }
76              
77             1;
78              
79             # site.yml
80             site:
81             args:
82             plugins:
83             name:
84             $class: My::Plugin
85              
86             =head1 DESCRIPTION
87              
88             Statocles Plugins are attached to sites and add features such as template helpers
89             and event handlers.
90              
91             This is the base role that all plugins should consume.
92              
93             =head1 OVERVIEW
94              
95             =head2 CONFIGURATION
96              
97             Site-level configuration of a plugin can be placed in the configuration file,
98             usually C<site.yml> as arguments:
99              
100             # site.yml
101             site:
102             args:
103             plugins:
104             name:
105             $class: My::Plugin
106             $args:
107             myattr: 'value'
108              
109             The argument name and value type must match a declaration in the
110             plugin itself. For example,
111              
112             package My::Plugin {
113             use Statocles::Base 'Class';
114             with 'Statocles::Plugin';
115              
116             has myattr => (
117             is => 'ro',
118             isa => Str,
119             default => sub { 'a default value' },
120             )
121             ...
122              
123             =head2 EVENT HANDLERS
124              
125             Most plugins will want to attach to one or more Statocles event
126             handlers in their registration. This example creates a template helper
127             C<myplug> and also hooks into the C<before_build_write> event.
128              
129             sub plugger {
130             my ( $self, $args, @helper_args ) = @_;
131             ...
132             }
133              
134             sub _plugboard {
135             my ( $self, $pages, @args ) = @_;
136             ...
137             }
138              
139             sub register {
140             my ( $self, $site ) = @_;
141             # We register our event handlers and theme helpers:
142             $site->theme->helper( myplug => sub { $self->plugger( @_ ) } );
143             $site->on( before_build_write => sub { $self->_plugboard( @_ ) } );
144             return $self;
145             }
146              
147             The event handler itself, like C<_plugboard> above, receives arguments
148             from the event. For C<before_build_write> this is a
149             C<Statocles::Event::Pages> object.
150              
151             =head2 HELPER FUNCTIONS
152              
153             A helper function like C<plugger> above receives first the template
154             variables and then all the helper arguments supplied in the template
155             itself. In the example above (section "Event Handlers"), C<$args>
156             would be a hash with these keys:
157             =over
158              
159             =item *
160              
161             C<app> The current app, e.g., C<"Statocles::App::Basic">
162              
163             =item *
164              
165             C<doc> The current document, e.g., of class L<Statocles::Document>
166              
167             =item *
168              
169             C<page> The current page, e.g., of class L<Statocles::Page::Document>
170              
171             =item *
172              
173             C<site> The current site, e.g., of class L<Statocles::Site>
174              
175             =back
176              
177             =head1 METHODS
178              
179             =head2 register
180              
181             $plugin->register( $site );
182              
183             Register this plugin with the given L<Statocles::Site
184             object|Statocles::Site>. This is called automatically when the site is
185             created.
186              
187             =head1 BUNDLED PLUGINS
188              
189             These plugins come with Statocles. L<More plugins may be available from
190             CPAN|http://metacpan.org>.
191              
192             =over 4
193              
194             =item L<Statocles::Plugin::LinkCheck>
195              
196             Check your site for broken links and images.
197              
198             =item L<Statocles::Plugin::Highlight>
199              
200             Syntax highlighting for code and configuration.
201              
202             =item L<Statocles::Plugin::HTMLLint>
203              
204             Check your HTML for best practices.
205              
206             =back
207              
208             =head1 AUTHOR
209              
210             Doug Bell <preaction@cpan.org>
211              
212             =head1 COPYRIGHT AND LICENSE
213              
214             This software is copyright (c) 2016 by Doug Bell.
215              
216             This is free software; you can redistribute it and/or modify it under
217             the same terms as the Perl 5 programming language system itself.
218              
219             =cut