view release on metacpan or  search on metacpan

lib/Dancer2/Plugin/Menu.pm  view on Meta::CPAN

Dancer2::Plugin::Menu - Automatically generate an HTML menu for your Dancer2 app

=head1 VERSION

version 0.009

=head1 SYNOPSIS

In your app:

  use Dancer2;
  use Dancer2::Plugin::Menu;

  menu_item(
    { title => 'My Parent Item', weight => 3 },
    get 'path' => sub { template },
  );

  menu_item(
    { title => 'My Child1 Item', weight => 3 },
    get 'path/menu1' => sub { template },
  );

  menu_item(
    { title => 'My Child2 Item', weight => 4 },
    get 'path/menu2' => sub { template },
  );

In your template file:

  <% menu %>

This will generate a hierarchical menu that will look like this when the
C<path/menu1> route is visited:

  <ul><li class="active">Path
      <ul><li class="active">My Child1 Item</li>
          <li>My Child2 Item</li>
      </ul>
  </ul>

=head1 DESCRIPTION

This module generates HTML for routes wrapped in the C<menu_item> keyword. Menu
items will be injected into the template wherever the C<E<lt>% menu %E<gt>> tag
is located. Child menu items are wrapped in C<E<lt>liE<gt>> HTML tags which are
themselves wrapped in a C<E<lt>ulE<gt>> tag associated with the parent menu
item. Menu items within the current route are given the C<active> class so they
can be styled.

The module is in early development stages and currently has few options. It has
not been heavily tested and there are likely bugs especially with dynamic paths
which are completely untested at this time. The module should work and be
adequate for simple menu structures, however.

=head2 KEYWORDS

=head3 menu_item( { [title => $str], [weight => $num] }, C<ROUTE METHOD> C<REGEXP>, C<CODE>)

Wraps a conventional route handler preceded by a required hash reference
containing data that will be applied to the route's endpoint.

Two keys can be supplied in the hash reference: a C<title> for the menu item and
a C<weight>. The C<title> will be used as the content for the menu items. The
C<weight> will determine the order of the menu items. Heavier items (with larger
values) will "sink" to the bottom compared to sibling menu items. If two sibling
menu items have the same weight, the menu items will be ordered alphabetically.

Menu items that are not endpoints in the route or that don't have a C<title>,
will automatically generate a title according to the path segment's name. For
example, the route C</categories/fun food/desserts> is converted to a hierarchy
of menu items entitled C<Categories>, C<Fun food>, and C<Desserts>. Note that
capitalization is automatically added.  Automatic titles will be overridden with
endpoint specific titles if they are supplied in a later C<menu_item> call.

If the C<weight> is not supplied it will default to a value of C<5>.

=head1 CONFIGURATION

Add a C<E<lt>% menu %E<gt>> tag in the appropriate location within your Dancer2
template files. If desired, add css for C<E<lt>liE<gt>> tags in the C<active>
class.

=head1 REQUIRES

=over 4

=item * L<Dancer2::Core::Hook|Dancer2::Core::Hook>

=item * L<Dancer2::Plugin|Dancer2::Plugin>

=item * L<Data::Dumper|Data::Dumper>

=item * L<HTML::Element|HTML::Element>

=item * L<MooX::HandlesVia|MooX::HandlesVia>

=item * L<Storable|Storable>

=item * L<strict|strict>

=item * L<warnings|warnings>

=back

=for :stopwords cpan testmatrix url annocpan anno bugtracker rt cpants kwalitee diff irc mailto metadata placeholders metacpan

=head1 SUPPORT

=head2 Perldoc

You can find documentation for this module with the perldoc command.

  perldoc Dancer2::Plugin::Menu

=head2 Websites

The following websites have more information about this module, and may be of help to you. As always,
in addition to those websites please use your favorite search engine to discover more resources.

=over 4

=item *

MetaCPAN

A modern, open-source CPAN search engine, useful to view POD in HTML format.

L<https://metacpan.org/release/Dancer2-Plugin-Menu>

=back

=head2 Source Code