lib/Catalyst/TraitFor/Controller/Breadcrumb/Followed.pm

filter: Statementstmt 97.6% 42 / 43 Branchbran 75.0% 6 / 8 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 6 / 6 Podpod 100% 2 / 2 totaltotal 94.9% 56 / 59 CC 6 SCAR 11.0
CC
6
Cov
94%
breadcrumb_add
5.0
_session_name
2.0
BEGIN
1.0
CRAP 3.0
↑ Summary
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
BranchTrueFalseTotal
if ($c->session->{$session_name}) 4 0 4
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
BranchTrueFalseTotal
if ($uri eq $c->session->{$session_name}[$i]{"uri"}) 1 4 5
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
BranchTrueFalseTotal
if ($breadcrumb_len > 1) 3 1 4
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
BranchTrueFalseTotal
if ($config) { } 0 5 5
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;
↑ Summary