view release on metacpan or  search on metacpan

lib/Catalyst/ActionRole/Tabs.pm  view on Meta::CPAN

package Catalyst::ActionRole::Tabs;

use Moose::Role;
use namespace::autoclean;

use Catalyst::Exception;

our $VERSION = '0.003000';

=head1 NAME

Catalyst::ActionRole::Tabs - Add tabs to Catalyst controller actions

=head1 SYNOPSIS

  package MyApp::Controller::Foo;

  use Moose::Role;
  use namespace::autoclean;

  BEGIN { extends 'Catalyst::Controller::ActionRole' }

  # view action has a tab
  sub view : Local Does(Tabs) Tab {
    ...
  }

  # edit action has a tab
  sub edit : Local Does(Tabs) Tab {
    ...
    $form->action($c->uri_for('update'));
    ...
  }

  # update action uses same tab as edit action
  sub update : Local Does(Tabs) TabAlias(edit) {
    ...
    if ($form->result->has_errors) {
      $stash->{template} = 'edit.tt2';
    }
    else {
      $c->response->redirect($c->uri_for('view'));
  }


  [% # Tab template %]
  [% # Assuming tab_navigation to be an array reference %]
  [% # See below under CALLBACK METHODS %]
  [% # For applicable CSS see below under SAMPLE CSS -%]
  <ul class="tabs">
  [% FOR tab IN tab_navigation %]
      <li[% IF tab.selected %] class="selected"[% END %]>
          <a href="[% tab.uri %]">[% tab.label %]</a>
      </li>
  [% END %]
  </ul>

=head1 DESCRIPTION

This module allows to add 'Tab' attributes to action endpoints, and it
will automatically build a data structure suitable for rendering 'tabs'
to switch between the methods that share the same tab structure.

Although this was originally built to help with making tabbed interfaces,
it isn't limited to creating tabs, as it simply collects the information
about the related actions.  Actions are considered to be related if they
share a namespace and the same captures from chained actions.

For examples of usage, please have a look in the test directory F<./t>
and its subdirectories.

=head1 ATTRIBUTES

=head2 Does

  Does(Tabs)

Activate C<Catalyst::ActionRole::Tabs> for the action.

=head2 Tab

  Tab
  Tab(Labeltext)

Assign a Tab to the action. The optional argument specifies the label text.
Without an explicite label text the action name is used, with the first
letter uppercased and the rest lowercased.

=head2 TabAlias

  TabAlias(Aliasaction)

In some cases it is usefull to assign one tab to many actions. E.g. an
action with a form to update some data, might be called initially as
action C<edit> where data is read from the database and filled into the
form fields and then point the form's action to C<update>, where the
actual input processing happens. In case of an error, the same form
(decorated with some error messages) would be shown again, but this time
under C<.../update>. With C<TabAlias> C<update> shows the same tab as
C<edit>:

  # action 'edit' has a Tab with label "Edit"
  sub edit : Local Does(Tabs) Tab { ... }

  # action 'update' has a Tab with label "Edit" too
  sub update : Local Does(Tabs) TabAlias(edit) { ... }

=head1 METHODS

Normaly you never have to touch the following two methods.
They are documented here to reveal their purpose.

=head2 BUILD

C<BUILD> is a standard L<Moose|Moose> method, that is called at the end of
the object construction process.

=over 2

=item * Asserts that not both C<Tab> and C<TabAlias> exist for the same action.