lib/Reaction/UI/ViewPort/Role/Actions.pm

   1 package Reaction::UI::ViewPort::Role::Actions;
   2
   3 use Reaction::Role;
   4 use Reaction::UI::ViewPort::URI;
   5
   6 use namespace::clean -except => [ qw(meta) ];
   7
   8 has actions => (
   9   is => 'ro',
  10   isa => 'ArrayRef',
  11   lazy_build => 1
  12 );
  13
  14 has action_order => (
  15   is => 'ro',
  16   isa => 'ArrayRef'
  17 );
  18
  19 has action_filter => (
  20   isa => 'CodeRef', is => 'ro',
  21 );
  22
  23 has action_prototypes => (
  24   is => 'ro',
  25   isa => 'HashRef',
  26   required => 1,
  27   default => sub{ {} }
  28 );
  29
  30 has computed_action_order => (
  31   is => 'ro',
  32   isa => 'ArrayRef',
  33   lazy_build => 1
  34 );
  35
  36 sub _filter_action_list {
  37     my $self = shift;
  38     my $actions = [keys %{$self->action_prototypes}];
  39     return $self->has_action_filter ?
  40         $self->action_filter->($actions, $self->model)
  41         : $actions;
  42 }
  43
  44 sub _build_computed_action_order {
  45   my $self = shift;
  46   my $ordered = $self->sort_by_spec(
  47     ($self->has_action_order ? $self->action_order : []),
  48     $self->_filter_action_list
  49   );
  50   return $ordered;
  51 }
  52
  53 sub _build_actions {
  54   my ($self) = @_;
  55   my (@act, $i);
  56   my $ctx = $self->ctx;
  57   my $loc = $self->location;
  58   my $target = $self->model;
  59
  60   foreach my $proto_name ( @{ $self->computed_action_order } ) {
  61     my $proto = $self->action_prototypes->{$proto_name};
  62     my $uri = $proto->{uri} or confess('uri is required in prototype action');
  63     my $label = exists $proto->{label} ? $proto->{label} : $proto_name;
  64     my $layout = exists $proto->{layout} ? $proto->{layout} : 'uri';
  65
  66     my $layout_args;
  67     if( exists $proto->{layout_args} ){
  68       if( ref($proto->{layout_args}) eq 'CODE' ){
  69         $layout_args = $proto->{layout_args}->($target, $ctx);
  70       } else {
  71         $layout_args = $proto->{layout_args};
  72       }
  73     }
  74
  75     my $action = Reaction::UI::ViewPort::URI->new(
  76       location => join ('-', $loc, 'action', $i++),
  77       uri => ( ref($uri) eq 'CODE' ? $uri->($target, $ctx) : $uri ),
  78       display => ( ref($label) eq 'CODE' ? $label->($target, $ctx) : $label ),
  79       layout => $layout,
  80       ( ref($layout_args) eq 'HASH' ? (layout_args => $layout_args) : () ),
  81     );
  82     push(@act, $action);
  83   }
  84   return \@act;
  85 }
  86
  87 1;
  88
  89 __END__;
  90
  91 =head1 NAME
  92
  93 Reaction::UI::ViewPort::Role::Actions
  94
  95 =head1 DESCRIPTION
  96
  97 A role to ease attaching actions to L<Reaction::InterfaceModel::Object>s
  98
  99 =head1 ATTRIBUTES
 100
 101 =head2 actions
 102
 103 Read-only, lazy-building ArrayRef of URI objects pointing to actions.
 104
 105 =head2 action_prototypes
 106
 107 A HashRef of prototypes for building the Action links. The prototypes should be
 108 composed like these:
 109
 110     my %action_prototypes = (
 111       example_action => { label => 'Example Action', uri => $uri_obj },
 112     );
 113
 114     #or you can get fancy and do something like what is below:
 115     sub make_label{
 116       my($im, $ctx) =  @_; #InterfaceModel::Object/Collection, Catalyst Context
 117       return 'label_text';
 118     }
 119     sub make_uri{
 120       my($im, $ctx) =  @_; #InterfaceModel::Object/Collection, Catalyst Context
 121       return return $ctx->uri_for('some_action');
 122     }
 123     my %action_prototypes = (
 124       example_action => { label => \&make_label, uri => \&make_uri },
 125     );
 126
 127 =head2 action_order
 128
 129 User-provided ArrayRef with how the actions should be ordered eg
 130
 131      action_order => [qw/view edit delete/]
 132
 133 =head2 computed_action_order
 134
 135 Read-only lazy-building ARRAY ref. The final computed action order. This may
 136 differ from the C<action_order> provided if you any actions were not included
 137 in that list.
 138
 139 =head1 METHODS
 140
 141 =head2 _build_actions
 142
 143 Cycle through the C<computed_action_order> and create a new
 144 L<ViewPort::URI|Reaction::UI::ViewPort::URI> object for each action using the
 145 provided prototypes.
 146
 147 =head2 _build_computed_action_order
 148
 149 Compute the final action ordering by using the provided C<action_order> as a
 150 spec to order all the present actions (the keys of C<action_prototypes>)
 151
 152 =head1 ACTION PROTOTYPES
 153
 154 Action prototypes are simply hashrefs that must contain a C<uri> key and may
 155 contain a C<label> key. The label can be anything that the display attribute of
 156 L<ViewPort::URI|Reaction::UI::ViewPort::URI> will accept, usually a scalar or a
 157 ViewPort. The value for C<uri> may be either a scalar, a L<URI> object (or
 158 anything that C<ISA URI>).
 159
 160 Additionally, both C<label> and C<uri> can be CODE refs. In this case, the code
 161 will be executed at C<_build_actions> time and will recieve two arguments, the
 162 value returned by C<model> and the value returned by C<ctx> in that order. Both
 163 of these methods should be implemented in the consuming class. By convention,
 164 model refers to the target of the action, an C<InterfaceModel::Object> in the
 165 case of a member action and an C<InterfaceModel::Collection> in the case of a
 166 Collection action. C<ctx> should be the current Catalyst context.
 167
 168 =head1 AUTHORS
 169
 170 See L<Reaction::Class> for authors.
 171
 172 =head1 LICENSE
 173
 174 See L<Reaction::Class> for the license.
 175
 176 =cut