Newcomen

Description A static content generator.
Newcomen > Perl Modules > Newcomen::Plugin::Blog::Menu::Item
Source

Index

NAME ^

Newcomen::Plugin::Blog::Menu::Item - An item in a menu.

SYNOPSIS ^

use Newcomen::Plugin::Blog::Menu::Item;

# Create a top-level item:
my $root = Newcomen::Plugin::Blog::Menu::Item -> new (
   'id' => 'root'
);

# Create a child item:
my $child = Newcomen::Plugin::Blog::Menu::Item -> new (
   'id'     => 'child',
   'parent' => $root,
);

# Set the URL of the child item:
$child -> url ('some URL');

# Set arbitrary meta data:
$child -> set (['name'], 'some name');

# Set the 'active' flags for an URL:
$root -> activate ('some  URL');

# Get an ordered list of the root's children:
my @children = $root -> sorted ();

DESCRIPTION ^

Newcomen::Plugin::Blog::Menu::Item represents an item in a menu.

An item itself may have an arbitrary number of child menu items. Each menu item is identified by an ID, and all direct children of a menu item must have unique IDs. Other properties of a menu item are its parent (another Newcomen::Plugin::Blog::Menu::Item instance, or undef if it is a top-level item), an URL (basically an arbitrary string, or undef), an order value used for sorting, an active indicator (see below), and arbitrary meta data.

CLASS METHODS ^

new

my $menu = Newcomen::Plugin::Blog::Menu::Item -> new (
   'id'     => $id,
   'parent' => $parent,
   'url'    => $url,
   'order'  => $order,
);

Constructor.

The id parameter is required. It must be unique among all the IDs of a parent's direct child menu items. If it is not unique, the constructor will die().

If a menu item should be added as a sub-menu to a parent, this parent has to be specified by the parent parameter. It must be another Newcomen::Plugin::Blog::Menu::Item instance (it may be set to undef for top-level menu items). The parent can only be set during construction, and it can not be changed or deleted later on. This also means that there is currently no way to remove a child menu item from its parent!

The parameters url and order may be used to set initial values for the url and order properties. These may be changed later on, see below.

INSTANCE METHODS ^

Properties

id

my $id = $menu -> id ();

Returns the ID of the menu item. The ID can only be set during construction, see new().

order

# Get the order value:
my $order = $menu -> order ();

# Set the value:
$menu -> order ($order);

Getter/setter for the order value. This value is used when requesting a sorted list of child menu items using the sorted() method. Standard string comparison is used to determine the menu item order, based on the order attribute. If the order attribute is not set, the menu item's ID will be used instead.

parent

my $parent = $menu -> parent ();

Returns the parent of the menu item. This is another Newcomen::Plugin::Blog::Menu::Item instance, or undef if the menu item has no parent. The parent can only be set during construction, see see new().

url

# Get the current URL:
my $url = $menu -> url ();

# Set a new URL for the item:
$menu -> url ($url);

Getter/setter for the URL attribute of a menu item. The URL may be set to any arbitrary string, or to undef to clear it.

activate

Toggle source:   activate 

sub activate {

   my $self = shift;
   my $url  = shift;

   if (my $current = $self -> _current ()) {
      return if $url and $url eq $current;
      for my $root (@{ $self -> _urls_get ($current) // [] }) {
         my $menu = $root;
         while ($menu) {
            $menu -> active (0);
            $menu = $menu -> parent ();
         }
      }
   }

   if ($url) {
      for my $root (@{ $self -> _urls_get ($url) // [] }) {
         my $menu = $root;
         $menu -> active (2);
         while ($menu = $menu -> parent ()) {
            $menu -> active (1);
         }
      }
   }

   $self -> _current ($url);

}
$menu -> activate ($url);

The activate() method expects one parameter, which must be a string specifying an URL. The URL will be looked up in the menu structure (to an arbitrary depth), and if the URL attribute of one or more menu items in the structure is set to the specified value, all intermediate menu items (from the menu's root item to the item with the specified URL) will be marked active. The active attribute of intermediate items will be set to 1, the active attribute of the actual menu item with the specified URL will be set to 2. If the specified URL is set for more than one item in the menu structure, multiple paths in the hierarchy may be marked active. The order in which paths are marked active is not defined, so if multiple items on one path refer to the specified URL, then items referring to the URL that are also intermediate items may be set either to 2 or 1, which one it is is not defined. The user should try to avoid this situation. All items not in any path as described above will be marked as inactive by setting the active attribute to 0.

Note that if the parameter is omitted or set to undef all active flags will be set to 0.

active

my $active = $menu -> active ();

Get the current setting of the active flag. The flag is usually set using the activate() method, see above. However, if required, the active() method may also be used as a setter. In that case the active attribute can be set to any integer value.

Children

Any menu item may have an arbitrary number of (direct) child items. The children are identified by their ID, which must be unique for all direct child items (menu items in one menu structure may have the same ID as long as they do not have the same parent).

child

my $child = $menu -> child ($id);

Returns the child item (another Newcomen::Plugin::Blog::Menu::Item instance) by the specified ID, or undef if no item with the specified ID exists.

ids

my @ids = $menu -> ids ();

Returns the IDs of all direct children of the menu item. The list may be empty if there are no children.

children

my @children = $menu -> children ();

Returns all direct children of the menu item (Newcomen::Plugin::Blog::Menu::Item instances). The list may be empty if there are no children. The order of the items returned is not defined.

count

my $count = $menu -> count ();

Returns the number of direct children of the menu item.

sorted

Toggle source:   sorted 

sub sorted {

   my $self = shift;

   my @ids = sort {
      ($self -> child ($a) -> order () // $self -> child ($a) -> id ())
      cmp
      ($self -> child ($b) -> order () // $self -> child ($b) -> id ())
   } $self -> ids ();

   return map { $self -> child ($_) } @ids;

}
my @children = $menu -> sorted ();

Like children(), but the list returned is sorted. Standard string comparison is used to determine the menu item order, based on the order attribute. If this is not set, the menu item's ID will be used instead.

Meta Data

Meta data is stored in an Newcomen::Data instance.

delete, exists, get, set

The methods delete(), exists(), get() and set() are mapped to the Newcomen::Data methods of the same name, see there for details.

meta

my $meta = $menu -> meta ();

Returns the Newcomen::Data instance storing the menu item's meta data.

Miscellaneous

add_child, update_url

Toggle sources:   add_child   update_url 

sub add_child {

   my $self  = shift;
   my $child = shift;

   confess 'Parent/child mismatch' unless refaddr ($self) == refaddr ($child -> parent ());
   confess 'Menu ID not unique'    if     $self -> child ($child -> id ());

   $self -> _set ($child -> id (), $child);

}
sub update_url {

   my $self = shift;
   my $item = shift;
   my $old  = shift;
   my $new  = shift;

   if ($old) {
      my @list  = @{ $self -> _urls_get ($old) };
      my $index = 0;
      for (@list) {
         last if refaddr ($_) == refaddr ($item);
         ++ $index;
      }
      splice @list, $index, 1;
      $self -> _urls_set ($old, \@list);
   }

   if ($new) {
      my @list = @{ $self -> _urls_get ($new) // [] };
      push @list, $item;
      $self -> _urls_set ($new, \@list);
   }

   $self -> parent () -> update_url ($item, $old, $new) if $self -> parent ();

}

These methods are called automatically if required and should not be called directly!

SEE ALSO ^

Newcomen::Data, Newcomen::Plugin::Blog::Menu

VERSION ^

This is version 2014052501.

AUTHOR ^

Stefan Goebel - newcomen {at} subtype {dot} de

COPYRIGHT AND LICENSE ^

Copyright 2013-2014 Stefan Goebel.

This file is part of Newcomen.

Newcomen is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the license, or (at your option) any later version.

Newcomen is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Newcomen. If not, see <http://www.gnu.org/licenses/>.

generated by (a slightly patched) Pod::ProjectDocs 0.41