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