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

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