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