Dogcows Code - chaz/p5-Catalyst-Plugin-Sitemap/blob - lib/Catalyst/Plugin/Sitemap.pm

   1 package Catalyst::Plugin::Sitemap;
   2 BEGIN {
   3   $Catalyst::Plugin::Sitemap::VERSION = '0.0.1';
   4 }
   5 # ABSTRACT: Sitemap support for Catalyst.
   6
   7
   8 use strict;
   9 use warnings;
  10
  11 use Moose::Role;
  12
  13 no warnings qw/uninitialized/;
  14
  15 use Search::Sitemap;
  16 use List::Util qw/ first /;
  17
  18 sub sitemap {
  19     my $self = shift;
  20
  21     my $sitemap = Search::Sitemap->new;
  22     $sitemap->pretty(1);
  23
  24     for my $controller ( $self->controller(qr//) ) {
  25       ACTION:
  26         for my $a ( $controller->get_action_methods ) {
  27
  28             my $action = $controller->action_for( $a->name );
  29
  30             my $attr = $action->attributes->{Sitemap} or next ACTION;
  31
  32             die "more than one attribute 'Sitemap' for sub ",
  33               $a->fully_qualified_name
  34               if @$attr > 1;
  35
  36             my @attr = split /\s*(?:,|=>)\s*/, $attr->[0];
  37
  38             my %uri_params;
  39
  40             if ( @attr == 1 ) {
  41                 if ( $attr[0] eq '*' ) {
  42                     my $sitemap_method = $action->name . "_sitemap";
  43
  44                     if ( $controller->can($sitemap_method) ) {
  45                         $controller->$sitemap_method( $self, $sitemap );
  46                         next ACTION;
  47                     }
  48                 }
  49
  50                 if ( $attr[0] + 0 > 0 ) {
  51                     # it's a number
  52                     $uri_params{priority} = $attr[0];
  53                 }
  54
  55             }
  56             elsif ( @attr > 0 ) {
  57                 %uri_params = @attr;
  58             }
  59
  60             $uri_params{loc} = $self->uri_for_action( $action->private_path );
  61
  62             $sitemap->add( \%uri_params );
  63
  64             next ACTION;
  65         }
  66
  67     }
  68
  69     return $sitemap;
  70 }
  71
  72 1;
  73
  74
  75
  76 =pod
  77
  78 =head1 NAME
  79
  80 Catalyst::Plugin::Sitemap - Sitemap support for Catalyst.
  81
  82 =head1 VERSION
  83
  84 version 0.0.1
  85
  86 =head1 SYNOPSIS
  87
  88     # in MyApp.pm
  89
  90     use Catalyst qw/ Sitemap /;
  91
  92     # in the controller
  93
  94     sub alone :Local :Sitemap {
  95         ...
  96     }
  97
  98     sub with_priority :Local :Sitemap(0.75) {
  99         ...
 100     }
 101
 102     sub with_args :Local
 103             :Sitemap( lastmod => 2010-09-27, changefreq => daily ) {
 104         ...
 105     }
 106
 107     sub with_function :Local :Sitemap(*) {
 108         ...
 109     }
 110
 111     sub with_function_sitemap {
 112         $_[2]->add( 'http://localhost/with_function' );
 113     }
 114
 115     # and then...
 116
 117     sub sitemap : Path('/sitemap') {
 118         my ( $self, $c ) = @_;
 119
 120         $c->res->body( $c->sitemap->xml );
 121     }
 122
 123 =head1 DESCRIPTION
 124
 125 L<Catalyst::Plugin::Sitemap> provides a way to semi-automate the creation
 126 of the sitemap of a Catalyst application.
 127
 128 =head1 CONTEXT METHOD
 129
 130 =head2 sitemap()
 131
 132 Returns a L<Search::Sitemap> object. The sitemap object is populated by
 133 inspecting the controllers of the application for actions with the
 134 sub attribute C<:Sitemap>.
 135
 136 =head1 C<:Sitemap> Subroutine Attribute
 137
 138 The sitemap is populated by actions ear-marked with the <:Sitemap> sub
 139 attribute.  It can be invoked in different ways:
 140
 141 =over
 142
 143 =item C<:Sitemap>
 144
 145     sub alone :Local :Sitemap {
 146         ...
 147     }
 148
 149 Adds the url of the action to the sitemap.
 150
 151 If the action does not
 152 resolves in a single url, this will results in an error.
 153
 154 =item C<:Sitemap($priority)>
 155
 156     sub with_priority :Local :Sitemap(0.9) {
 157         ...
 158     }
 159
 160 Adds the url, with the given number, which has to be between 1 (inclusive)
 161 and 0 (exclusive), as its priority.
 162
 163 If the action does not
 164 resolves in a single url, this will results in an error.
 165
 166 =item C<:Sitemap( %attributes )>
 167
 168     sub with_args :Local
 169             :Sitemap( lastmod => 2010-09-27, changefreq => daily ) {
 170         ...
 171     }
 172
 173 Adds the url with the given entry attributes (as defined by C<Search::Sitemap>).
 174
 175 If the action does not
 176 resolves in a single url, this will results in an error.
 177
 178 =item C<:Sitemap(*)>
 179
 180     sub with_function :Local :Sitemap(*) { }
 181
 182     sub with_function_sitemap {
 183         my ( $self, $c, $sitemap ) = @_;
 184
 185         $sitemap->add( 'http://localhost/with_function' );
 186     }
 187
 188 Calls the function 'I<action>_sitemap', if it exists, and passes it the
 189 controller, context and sitemap objects.
 190
 191 This is currently the only way to invoke C<:Sitemap> on an action
 192 resolving to many urls.
 193
 194 =back
 195
 196 =head1 BUGS AND LIMITATIONS
 197
 198 Currently, each invocation of the method C<sitemap()> will
 199 re-generate the C<Search::Sitemap> object.  A future version
 200 of this module might offer a way to only compute the sitemap
 201 once.
 202
 203 =head1 SEE ALSO
 204
 205 =over
 206
 207 =item L<Search::Sitemap>
 208
 209 =item http://babyl.dyndns.org/techblog/entry/catalyst-plugin-sitemap
 210
 211 =back
 212
 213 =head1 AUTHOR
 214
 215   Yanick Champoux <yanick@babyl.dyndns.org>
 216
 217 =head1 COPYRIGHT AND LICENSE
 218
 219 This software is copyright (c) 2010 by Yanick Champoux.
 220
 221 This is free software; you can redistribute it and/or modify it under
 222 the same terms as the Perl 5 programming language system itself.
 223
 224 =cut
 225
 226
 227 __END__