Catalyst-Plugin-Navigation
view release on metacpan or search on metacpan
lib/Catalyst/Plugin/Navigation.pm
lib/CatalystX/NavigationMenu.pm
lib/CatalystX/NavigationMenuItem.pm
Changes
t/02-pod-coverage.t
t/01-pod.t
t/03-perlcritic.t
t/01-pragmas.t
t/perlcriticrc
Makefile.PL
MANIFEST
README
META.yml Module meta-data (added by MakeMaker)
lib/Catalyst/Plugin/Navigation.pm view on Meta::CPAN
package Catalyst::Plugin::Navigation;
use strict;
use warnings;
use Moose::Role;
use CatalystX::NavigationMenu;
use namespace::autoclean;
use vars qw($VERSION);
$VERSION = '1.002';
after setup_finalize => sub {
my ($self, @args) = @_;
$self->mk_classdata('navigation');
$self->navigation(CatalystX::NavigationMenu->new());
$self->navigation->populate($self);
};
1;
__END__
=head1 NAME
Catalyst::Plugin::Navigation - A navigation plugin for Catalyst
lib/Catalyst/Plugin/Navigation.pm view on Meta::CPAN
use Catalyst(qw/
Navigation
/);
# When navigation needed.
my $menu = $c->navigation->get_navigation($c, {level => 0});
...
# When defining an action.
sub new_action : Local Menu('Menu Title') MenuTitle('Menu Mouse Over Title')
MenuParent('#Menu Parent') MenuArgs('$stash_arg') {
# Do action items.
...
}
=head1 DESCRIPTION
The Catalyst::Plugin::Navigation plugin provides a way to define the navigation elements
and hierarchy within the Catalyst controllers. By defining the menu structure from the
controller attributes a controller can then ask for any level of menu and be presented
with the current chain to the active page as well as all other visable menus from the
lib/Catalyst/Plugin/Navigation.pm view on Meta::CPAN
in an external source this can be done from the infomation available from the controllers
themselves.
=head1 METHODS
When using the Catalyst::Plugin::Navigation plugin the following methods are added to the
base Catalyst object.
=head2 navigation()
Returns the CatalystX::NavigationMenu object that relates to the existing menu structure
defined through the controller attributes. See the L(CatalystX::MenuNavigation) man page
for more details.
=head1 Attributes
The following attributes are understood by the Catalyst::Plugin::Navigation plugin. The
Menu() attribute is the only required attribute. Without this attribute the action element
will not be included in the navigation tree.
=head2 Menu('Label')
This provides the label to be used for the menu link. This is the actual text of the href.
This item is required in order to have the action appear in the menu navigation.
=head2 MenuParent('Path')
Provides the path to the parent item. If the parent doesn't exist then it will be created
in the tree structure so that the child can be accessed even if the parent is never
defined. For more information on the Path value that can be passed see the PATHS section
below.
=head2 MenuArgs('Arg')
Provides informaiton on what to use to populate arguments and URI placeholders for the current
action. If the current action is chained or requires arguments then these are used to populate
the URI accordingly. The arguments are passed in the order they appear in the attribute list.
More than one MenuArgs attribute can be attached to a single action. If the argument is preceeded
by a $ symbol then the name of the argument is pulled from the stash variable. Otherwise the
argument is included as plain text. For example the following entry MenuArgs('$stash_value') will
call out and get the stash value for the keyword 'stash_value' ($c->stash->{'stash_value'}).
URL arguments are also handled with the MenuArgs() attribute. These are defined by preceeding
the argument with the @ symbol. The same rules above apply, so the argument @$var will use the var
value from the stash as a URL argument and @var will use the literal string var as the URL
argument.
=head2 MenuCond('Cond')
In order for the menu item to be included in the navigation display the condition provided must
evaluate to a true value. The argument ('Cond') value passed in is evaluated in an eval, allowing
complex conditions to be executed. More than one condition can be passed as an attribute, in which
case all conditions must evaluate to true.
=head2 MenuOrder(int)
Defines the order in which the menu elements shoudl be displayed. If you would like your menu
items to show up in a particular order you can define that order using the MenuOrder attribute.
In the event that more than one action has the same order value then they are sorted alphabetically
by their Menu label value.
=head2 MenuRoles('Role')
If you are using the Authentication::Roles plugin then you can define which roles must be
provided in order to display the given action in the navigation tree. If more than one
MenuRoles are included in the attributes list all those roles must be found. If you want
to show the menu item depending on one of several roles then you can separate those roles
with a | character. So the following attribute: MenuRoles('role1|role2|role3') will allow
the action to be included in the navigation tree if the logged in user has a role of either
role1, role2 or role3.
=head2 MenuTitle('Title')
Provides the value to use for the title attribute of the a link.
=head1 PATHS
The Catalyst::Pugin::Navigation plugin defines the navigation menu structure using a path
system. This allows you to define a complex path to reach a particular action. There are
a few ways to define path elements. In most instances you will just want to use the
path to the controller item as the path to an action (ie; controller_name/action_name).
lib/Catalyst/Plugin/Navigation.pm view on Meta::CPAN
#Parent
#Child
/controller/entry
new_entry
When items are added into the navigation tree their defined by their namespace and action
name. This defines the private path to the entry. So future elements can be added into the
tree under an item by referring to the path of the entry it shoudl appear under.
There should be no need to include multiple path details in the MenuPath variable unless you
are defining Labels to be used. A Label can occur anywhere in the navigation entry. So both
of these paths are valid: #Label/path/to/action or /path/to/action/#Label.
=head1 DEPENDENCIES
L<Catalyst>
=head1 SEE ALSO
L<CatalystX::NavigationMenu>, L<CatalystX::NavigationMenuItem>
=head1 AUTHORS
Derek Wueppelmann <derek@roaringpenguin.com>
=head1 LICENSE AND COPYRIGHT
Copyright (c) 2011 Roaring Penguin Software, Inc.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
lib/CatalystX/NavigationMenu.pm view on Meta::CPAN
package CatalystX::NavigationMenu;
use strict;
use warnings;
use Moose;
use CatalystX::NavigationMenuItem;
use namespace::autoclean;
=head1 NAME
CatalystX::NavigationMenu
=head1 SYNOPSIS
my $nm = CatalystX::NavigationMenu->new();
$nm->popupate($c);
my $menu = $nm->get_navigation($c, {level => 0});
=head1 DESCRIPTION
CatalystX::NavigationMenu provides a menu object to be used when creating and
managing menus in Catalyst based on attribute data. For details of the Catalyst
attributes see the L(Catalyst::Plugin::Navigation) documentation.
=cut
has items => (
traits => ['Array'],
is => 'rw',
isa => 'ArrayRef[CatalystX::NavigationMenuItem]',
default => sub{[]},
handles => {
all_items => 'elements',
insert_item => 'push',
shift_item => 'shift',
find_item => 'first',
count_items => 'count',
has_items => 'is_empty',
sort_items => 'sort',
},
lib/CatalystX/NavigationMenu.pm view on Meta::CPAN
my $dispatcher = $c->dispatcher;
foreach my $c_name ($c->controllers(qr//)) {
my $controller = $c->controller($c_name);
my @actions = $dispatcher->get_containers($controller->action_namespace($c));
$c->log->debug("Looking at Controller $c_name for navigation entries") if $c->debug;
foreach my $ac (@actions) {
my $acts = $ac->actions;
foreach my $key (keys(%$acts)) {
my $action = $acts->{$key};
if ($action->attributes->{Menu}) {
# And get the menu to insert it into the right location.
$c->log->debug("Adding action item for path: " . ($action->namespace || '') . '/' . ($action->name || '') . " with parent: " .
($action->attributes->{MenuParent}->[0] || '') ) if $c->debug;
$self->add_action($action);
}
}
}
}
}
=head2 add_action($action)
Adds an element into the menu based on the Catalyst action provided.
=cut
sub add_action {
my ($self, $action) = @_;
# Create the items needed to build the item.
my $parent = $action->attributes->{MenuParent}->[0] || '';
my $action_args = $action->attributes->{MenuArgs} || [];
my $conditions = $action->attributes->{MenuCond} || [];
my $order = $action->attributes->{MenuOrder}->[0] || 0;
my $roles = $action->attributes->{MenuRoles} || [];
my $title = $action->attributes->{MenuTitle}->[0] || '';
my $item = CatalystX::NavigationMenuItem->new(
label => $action->attributes->{Menu}->[0],
title => $title,
action => $action,
path => $action->namespace . '/' . $action->name,
parent => $parent,
action_args => $action_args,
conditions => $conditions,
order => $order,
required_roles => $roles,
);
$self->add_item($item);
}
=head2 get_child_with_path($path)
Returns a child NavigationMenu item that contains the given path. If no child is found
then undef is returned.
=cut
sub get_child_with_path {
my ($self, $path) = @_;
return $self->find_item(sub {$_->contains_path($path)});
}
lib/CatalystX/NavigationMenu.pm view on Meta::CPAN
my $parent_path = shift(@path_parts);
# See if we can find the parent for the first part of the path.
$p_item = $self->get_child_with_path($parent_path);
if ($p_item) {
# We have a parent.
$item->_set_parent(join('', @path_parts));
}
else {
if ($parent_path =~ /^#/) {
# The parent path is just a label. so create a dummy item.
$p_item = CatalystX::NavigationMenuItem->new(
label => $', #The label is everything after the # in the path.
parent => '', # No parent item.
path => $parent_path,
);
}
else {
# We need to create a new container item
my $label = $path_parts[0];
$label =~ s/^#//;
$p_item = CatalystX::NavigationMenuItem->new(
label => $label,
parent => $parent_path,
path => $label,
);
}
$item->_set_parent(join('', @path_parts));
$self->add_item($p_item);
}
$p_item->add_item($item);
}
lib/CatalystX/NavigationMenu.pm view on Meta::CPAN
}
else {
$self->insert_item($child);
}
}
}
=head2 get_navigation($c, $attrs)
Returns an array reference to a menu entry. This will only show one level of a
menu. The values of the array are the values returned by the L(NavigationMenuItem)
nav_entry() method.
=cut
sub get_navigation {
my ($self, $c, $attrs) = @_;
my $nav = [];
# see if we need to get a particular level of menu or not.
lib/CatalystX/NavigationMenu.pm view on Meta::CPAN
1;
__END__
=head1 DEPENDENCIES
L<Catalyst>
=head1 SEE ALSO
L<CatalystX::NavigationMenuItem>
=head1 AUTHORS
Derek Wueppelmann <derek@roaringpenguin.com>
=head1 LICENSE AND COPYRIGHT
Copyright (c) 2011 Roaring Penguin Software, Inc.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
lib/CatalystX/NavigationMenuItem.pm view on Meta::CPAN
package CatalystX::NavigationMenuItem;
use strict;
use warnings;
use Moose;
use namespace::autoclean;
=head1 NAME
CatalystX::NavigationMenuItem
=head1 SYNOPSIS
my $mi = CatalystX::NavigationMenuItem->new(
...
);
my $entry = $mi->nav_entry($c);
my $link = $mi->get_link($c);
=head1 DESCRIPTION
CatalystX::NavigationMenuItem represents a menu item in a L(CatalystX::NavigationMenu).
This object does all the work of determining if the menu item can be displayed, what
link to use and if there are sub menus.
=cut
has label => (
is => 'rw',
isa => 'Str',
);
lib/CatalystX/NavigationMenuItem.pm view on Meta::CPAN
isa => 'ArrayRef[Str]',
default => sub{ [] },
handles => {
count_roles => 'count',
all_roles => 'elements',
},
);
has children => (
is => 'rw',
isa => 'CatalystX::NavigationMenu',
predicate => 'has_children'
);
=head1 METHODS
=head2 contains_path($path)
Returns true if this menu item or any of its children contain the given
path.
lib/CatalystX/NavigationMenuItem.pm view on Meta::CPAN
=head2 add_item($item)
Add the given item to the sub tree for this item. If no subtree exists create one.
=cut
sub add_item {
my ($self, $item) = @_;
if (!$self->has_children) {
$self->children(CatalystX::NavigationMenu->new());
}
if ($item->parent eq $self->path) {
$self->children->insert_item($item);
}
else {
$self->children->add_item($item);
}
}
=head2 get_link($c)
lib/CatalystX/NavigationMenuItem.pm view on Meta::CPAN
1;
__END__
=head1 DEPENDENCIES
L<Catalyst>
=head1 SEE ALSO
L<CatalystX::NavigationMenu>
=head1 AUTHORS
Derek Wueppelmann <derek@roaringpenguin.com>
=head1 LICENSE AND COPYRIGHT
Copyright (c) 2011 Roaring Penguin Software, Inc.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
( run in 0.275 second using v1.01-cache-2.11-cpan-26ccb49234f )