| 1 | package Catalyst::TraitFor::Controller::Breadcrumb::Followed; | ||||||||||
| 2 | |||||||||||
| 3 | 1 | ▶ | use 5.008; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 4 | |||||||||||
| 5 | 1 | our $VERSION = '0.02'; | |||||||||
| 6 | 1 | $VERSION = eval $VERSION; | |||||||||
| 7 | |||||||||||
| 8 | 1 | ▶ | use Moose::Role; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 9 | |||||||||||
| 10 | 1 | ▶ | use namespace::autoclean; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 11 | |||||||||||
| 12 | 1 | ▶ | sub breadcrumb_start { | ||||||||
|
Subroutine
breadcrumb_start: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||
| 13 | 1 | my ($self, $c, $title) = @_; | |||||||||
| 14 | |||||||||||
| 15 | 1 | my $session_name = $self->_session_name($c); | |||||||||
| 16 | |||||||||||
| 17 | 1 | $c->session->{$session_name} = []; | |||||||||
| 18 | 1 | $self->breadcrumb_add($c, $title); | |||||||||
| 19 | } | ||||||||||
| 20 | |||||||||||
| 21 | 4 | ▶ | sub breadcrumb_add { | ||||||||
|
Subroutine
breadcrumb_add: called CC=5 SCAR=16.1
Pod
documented
| |||||||||||
| 22 | 4 | my ($self, $c, $title) = @_; | |||||||||
| 23 | |||||||||||
| 24 | 4 | my $session_name = $self->_session_name($c); | |||||||||
| 25 | |||||||||||
| 26 | 4 | my $uri = $c->uri_for($c->action) . '/' . join('/', @{$c->req->arguments}); | |||||||||
| 27 | 4 | my $crumb = { | |||||||||
| 28 | class => 'current', | ||||||||||
| 29 | title => $title, | ||||||||||
| 30 | uri => $uri, | ||||||||||
| 31 | }; | ||||||||||
| 32 | |||||||||||
| 33 | # See if the URI is already in the breadcrumb trail | ||||||||||
| 34 | 4 | my $breadcrumb_len = 0; | |||||||||
| 35 | 4 | ▶ | if ($c->session->{$session_name}) { | ||||||||
|
Branch: 1 branch
| |||||||||||
| 36 | 4 | $breadcrumb_len = scalar(@{$c->session->{$session_name}}); | |||||||||
| 37 | } | ||||||||||
| 38 | BREADCRUMB: | ||||||||||
| 39 | 4 | for my $i (0..$breadcrumb_len-1) { | |||||||||
| 40 | # we may as well set the class to 'done' while we are here | ||||||||||
| 41 | 5 | $c->session->{$session_name}[$i]{class} = 'done'; | |||||||||
| 42 | 5 | ▶ | if ($uri eq $c->session->{$session_name}[$i]{uri}) { | ||||||||
|
Branch: 1 branch
| |||||||||||
| 43 | # Found so truncate the breadcrumb trail to this item | ||||||||||
| 44 | 1 | splice(@{$c->session->{$session_name}},$i); | |||||||||
| 45 | 1 | last BREADCRUMB; | |||||||||
| 46 | } | ||||||||||
| 47 | } | ||||||||||
| 48 | 4 | push(@{$c->session->{$session_name}}, $crumb); | |||||||||
| 49 | 4 | $breadcrumb_len = scalar(@{$c->session->{$session_name}}); | |||||||||
| 50 | |||||||||||
| 51 | # Make penultimate class 'lastDone' | ||||||||||
| 52 | 4 | ▶ | if ($breadcrumb_len > 1) { | ||||||||
|
Branch: 1 branch
| |||||||||||
| 53 | 3 | $c->session->{$session_name}[$breadcrumb_len - 2]{class} = 'lastDone'; | |||||||||
| 54 | } | ||||||||||
| 55 | } | ||||||||||
| 56 | |||||||||||
| 57 | 5 | ▶ | sub _session_name { | ||||||||
|
Subroutine
_session_name: called CC=2 SCAR=7.1
| |||||||||||
| 58 | 5 | my ($self, $c) = @_; | |||||||||
| 59 | |||||||||||
| 60 | 5 | my $config = $c->config->{'Catalyst::TraitFor::Controller::Breadcrumb::Followed'}; | |||||||||
| 61 | 5 | my $session_name; | |||||||||
| 62 | |||||||||||
| 63 | 5 | ▶ | if ($config) { | ||||||||
|
Branch: 1 branch
| |||||||||||
| 64 | 0 | $session_name = $config->{session_name}; | |||||||||
| 65 | } | ||||||||||
| 66 | else { | ||||||||||
| 67 | 5 | $session_name = 'breadcrumb'; | |||||||||
| 68 | } | ||||||||||
| 69 | |||||||||||
| 70 | 5 | return $session_name; | |||||||||
| 71 | } | ||||||||||
| 72 | |||||||||||
| 73 | =pod | ||||||||||
| 74 | |||||||||||
| 75 | =head1 NAME | ||||||||||
| 76 | |||||||||||
| 77 | Catalyst::TraitFor::Controller::Breadcrumb::Followed - Breadcrumb navigation using Moose Roles | ||||||||||
| 78 | |||||||||||
| 79 | =head1 SYNOPSIS | ||||||||||
| 80 | |||||||||||
| 81 | This keeps a Breadcrumb trail of pages that have been visited allowing the user | ||||||||||
| 82 | to go back to any earlier page directly. | ||||||||||
| 83 | |||||||||||
| 84 | Note that this is different from a Breadcrumb which shows you where you are in a site | ||||||||||
| 85 | navigation hierarchy. | ||||||||||
| 86 | |||||||||||
| 87 | In your Catalyst Controller. | ||||||||||
| 88 | |||||||||||
| 89 | package MyApp::Web::Controller::Root; | ||||||||||
| 90 | |||||||||||
| 91 | use Moose; | ||||||||||
| 92 | use namespace::autoclean; | ||||||||||
| 93 | |||||||||||
| 94 | with 'Catalyst::TraitFor::Controller::BreadCrumb::Followed'; | ||||||||||
| 95 | |||||||||||
| 96 | Then later on in your controllers you can do | ||||||||||
| 97 | |||||||||||
| 98 | sub foo : Local { | ||||||||||
| 99 | my ($self, $c) = @_; | ||||||||||
| 100 | |||||||||||
| 101 | $self->breadcrumb_start($c, 'Foo Text'); | ||||||||||
| 102 | ... | ||||||||||
| 103 | } | ||||||||||
| 104 | |||||||||||
| 105 | sub bar : Local { | ||||||||||
| 106 | my ($self, $c) = @_; | ||||||||||
| 107 | |||||||||||
| 108 | $self->breadcrumb_add($c, 'Bar Text'); | ||||||||||
| 109 | ... | ||||||||||
| 110 | } | ||||||||||
| 111 | |||||||||||
| 112 | =head1 DESCRIPTION | ||||||||||
| 113 | |||||||||||
| 114 | This implementation of Breadcrumb navigation is of the type that shows | ||||||||||
| 115 | the user where she has navigated. For example, she may start at a list | ||||||||||
| 116 | of Artists, clicking on one of the Artists displays a list of CDs by that | ||||||||||
| 117 | Artist. Clicking on a CD displays a list of Tracks on that CD. | ||||||||||
| 118 | |||||||||||
| 119 | The Breadcrumb would hold the route taken (Artists -> Artist -> CD -> Track) and | ||||||||||
| 120 | retain that information in session data. | ||||||||||
| 121 | |||||||||||
| 122 | The session data holds a data structure that can be used in a Template | ||||||||||
| 123 | to build a list of the visited pages together with navigation links and | ||||||||||
| 124 | rendered with suitable CSS. | ||||||||||
| 125 | |||||||||||
| 126 | The class keeps track of which pages have been visited so if a URL that | ||||||||||
| 127 | is in the list of Breadcrumbs is re-visited then the Breadcrumb trail is | ||||||||||
| 128 | truncated to the first instance. | ||||||||||
| 129 | |||||||||||
| 130 | Whenever the B<breadcrumb_start> method is called, any existing Breadcrumb | ||||||||||
| 131 | trail is truncated and a new one is started. | ||||||||||
| 132 | |||||||||||
| 133 | =head1 METHODS | ||||||||||
| 134 | |||||||||||
| 135 | =head2 breadcrumb_start | ||||||||||
| 136 | |||||||||||
| 137 | Start a new breadcrumb trail. | ||||||||||
| 138 | |||||||||||
| 139 | sub artists : Local { | ||||||||||
| 140 | my ($self, $c) = @_; | ||||||||||
| 141 | |||||||||||
| 142 | $self->breadcrumb_start($c, 'All Artists'); | ||||||||||
| 143 | ... | ||||||||||
| 144 | } | ||||||||||
| 145 | |||||||||||
| 146 | Calling breadcrumb_start removes any existing breadcrumb trail and starts a new | ||||||||||
| 147 | one. | ||||||||||
| 148 | |||||||||||
| 149 | The method takes two parameters, the $c catalyst object and the title to be shown | ||||||||||
| 150 | in the breadcrumb trail. | ||||||||||
| 151 | |||||||||||
| 152 | =head2 breadcrumb_add | ||||||||||
| 153 | |||||||||||
| 154 | Append to the end of an existing breadcrumb trail. | ||||||||||
| 155 | |||||||||||
| 156 | sub cds : Local { | ||||||||||
| 157 | my ($self, $c) = @_; | ||||||||||
| 158 | |||||||||||
| 159 | $self->breadcrumb_add($c, $artist_name); | ||||||||||
| 160 | ... | ||||||||||
| 161 | } | ||||||||||
| 162 | |||||||||||
| 163 | This appends to the existing breadcrumb trail (as started by breadcrumb_start) | ||||||||||
| 164 | and adds the current URI to it. | ||||||||||
| 165 | |||||||||||
| 166 | In the event of the user navigating so that she navigates back to a URI she has | ||||||||||
| 167 | already visited in the breadcrumb trail, the trail is truncated back to the first | ||||||||||
| 168 | instance of that URI. | ||||||||||
| 169 | |||||||||||
| 170 | =head1 session data | ||||||||||
| 171 | |||||||||||
| 172 | The Breadcrumb trail is held in the session data, by default it is held in | ||||||||||
| 173 | $c->session->{breadcrumb} but this can be configured (see below). | ||||||||||
| 174 | |||||||||||
| 175 | The session data is build up into an array of hashes representing each | ||||||||||
| 176 | part of the breadcrumb trail. e.g | ||||||||||
| 177 | |||||||||||
| 178 | $c->session->{breadcrumb} = [ | ||||||||||
| 179 | { | ||||||||||
| 180 | class => 'done', | ||||||||||
| 181 | uri => '/artists', | ||||||||||
| 182 | title => 'All Artists', | ||||||||||
| 183 | }, | ||||||||||
| 184 | { | ||||||||||
| 185 | class => 'done', | ||||||||||
| 186 | uri => '/artist/3', | ||||||||||
| 187 | title => 'David Bowie', | ||||||||||
| 188 | }, | ||||||||||
| 189 | { | ||||||||||
| 190 | class => 'lastDone', | ||||||||||
| 191 | uri => '/artist/3/cd/4', | ||||||||||
| 192 | title => 'Diamond Dogs', | ||||||||||
| 193 | } | ||||||||||
| 194 | class => 'current', | ||||||||||
| 195 | uri => '/artist/3/cd/4/track/6', | ||||||||||
| 196 | title => 'Rebel Rebel', | ||||||||||
| 197 | } | ||||||||||
| 198 | ]; | ||||||||||
| 199 | |||||||||||
| 200 | This session data can then be used to create HTML in a Template. One example is | ||||||||||
| 201 | as follows. | ||||||||||
| 202 | |||||||||||
| 203 | <div class="navigation"> | ||||||||||
| 204 | <ul id="mainNav" class="breadcrumb"> | ||||||||||
| 205 | [% FOREACH crumb IN c.session.breadcrumb %] | ||||||||||
| 206 | <li class="[% crumb.class %]"> | ||||||||||
| 207 | [% IF crumb.class=='lastDone' || crumb.class=='done' %] | ||||||||||
| 208 | [% back_uri = crumb.uri %] | ||||||||||
| 209 | <a href="[% crumb.uri %]">[% crumb.title %]</a> | ||||||||||
| 210 | [% ELSE %] | ||||||||||
| 211 | [% crumb.title %] | ||||||||||
| 212 | [% END %] | ||||||||||
| 213 | </li> | ||||||||||
| 214 | [% END %] | ||||||||||
| 215 | </ul> | ||||||||||
| 216 | |||||||||||
| 217 | [% IF back_uri %] | ||||||||||
| 218 | <div class="navigation_buttons"> | ||||||||||
| 219 | <button class="button_previous" onClick="parent.location='[% back_uri %]'"> Back </button> | ||||||||||
| 220 | </div> | ||||||||||
| 221 | [% END %] | ||||||||||
| 222 | </div> | ||||||||||
| 223 | |||||||||||
| 224 | The use of suitable CSS can be used to display this in whatever form you wish. | ||||||||||
| 225 | |||||||||||
| 226 | =head1 configuration | ||||||||||
| 227 | |||||||||||
| 228 | By default the breadcrumb is held in $c->session->{breadcrumb} but you can change this in | ||||||||||
| 229 | your configuration in your application. | ||||||||||
| 230 | |||||||||||
| 231 | package MyApp::Web; | ||||||||||
| 232 | |||||||||||
| 233 | ... | ||||||||||
| 234 | |||||||||||
| 235 | __PACKAGE__->config->{'Catalyst::TraitFor::Controller::Breadcrumb::Followed'} = { | ||||||||||
| 236 | session_name => 'my_breadcrumb_trail', | ||||||||||
| 237 | }; | ||||||||||
| 238 | |||||||||||
| 239 | |||||||||||
| 240 | =head1 AUTHOR | ||||||||||
| 241 | |||||||||||
| 242 | Ian Docherty pause@icydee.com | ||||||||||
| 243 | |||||||||||
| 244 | =head1 COPYRIGHT & LICENSE | ||||||||||
| 245 | |||||||||||
| 246 | Copyright (c) 2010 the aforementioned authors. All rights | ||||||||||
| 247 | reserved. This program is free software; you can redistribute | ||||||||||
| 248 | it and/or modify it under the same terms as Perl itself. | ||||||||||
| 249 | |||||||||||
| 250 | =cut | ||||||||||
| 251 | 1 | 1; | |||||||||