Newcomen

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

Index


NAME ^

Newcomen::Plugin::Blog::Menu - Manages a site menu.

DESCRIPTION ^

This plugin allows the user to define a menu structure, which can then be used in the templates to display a menu.

Menu items can be defined in the configuration file, as well as in the article sources' meta data. See OPTIONS and META DATA for details. The menu items defined in the user configuration will be processed first, menu items defined in article sources will be processed after that.

The menu structure is stored using Newcomen::Plugin::Blog::Menu::Item instances, please see the documentation of this module for more details on the instance attributes, methods etc.

Before a page is rendered, the activate() method of the root menu item will be called with the page target as parameter, so for a page that is included in the menu the active attributes of the items will be set appropriately.

OPTIONS ^

{
   'blog'    => {
      'menu' => {},
   },
}

These are the default options set by this plugin. They may be overridden by user configuration.

The blog/menu option must be a hashref. The keys specify menu item paths, the values must themselves be hashrefs, containing the data for the menu item to be created.

Path Processing

The path of a menu item specifies the item's position in the menu hierarchy. The path consists of one or more menu IDs, separated by slashes ('/'). The menu IDs uniquely identify a menu item at a specific level in the menu hierarchy. Intermediate items in the hierarchy will automatically be created if required. The properties of these intermediate items will be derived from the path. The path is split at the separator, resulting in one or more path components, each one relating to one menu item in the menu hierarchy.

In general, a path component specifies the menu ID for the item. If this string starts with at least one digit, followed by an underscore, followed by at least one other character, the original value will be used as the order property of the menu item, and the ID will be the original value with the leading digit(s) and underscore removed. If a path component does not start with the aforementioned pattern, the order value of the item will be set to undef. In any case, the menu item's meta data title and text will be set to the same value as the ID for intermediate items (see below on details how to override these for the leafs). For automatically created intermediate items, the meta data will also include the key auto, with its value set to 1.

The final element in the path (the leaf) specifies the actual menu item for which the hashref contains the menu data. The hashref may include any of the following keys:

Overriding Menu Items

Once a menu item has been created, it can not be overridden, with the exception of automatically created (intermediate) items. More precisely, any item with the auto meta data set to a true value can be overridden. Any such item will only be overridden by explicitly creating it, i.e. it will not be changed if it appears again as an intermediate item. If any such item is overridden, the auto flag will be deleted from the meta data (before copying the new meta data, so if this new meta data should contain another auto value, this new value will be preserved).

Example

The following is an example of a valid menu configuration. Note that not all data provided in the example is required, and some data may be derived from the path as described above.

{
   'blog'                 => {
      'menu'              => {
         '999_Meta/About' => {
            'id'          => 'about',
            'url'         => '/about.html',
            'text'        => 'About This Site',
            'title'       => 'About',
            'anchor'      => '#top',
            'order'       => '500_About',
            'color'       => 'red',
         }
      },
   },
}

In this example the path is set to '999_Meta/About'.

One intermediate menu item is created for the '999_Meta' path automatically as described above, unless it already exists. Its ID (as well as its text and title meta data) will be set to 'Meta', and its order attribute to '999_Meta'.

The actual leaf menu item will be created as a child of the 'Meta' item. Its properties would be derived from the path, if they were not specified in the item's hashref. See the section Menu Item Data for a description.

META DATA ^

Sources

{
   'menu'       => <menu specification>,
   'single_url' => <used as URL unless overridden>,
}

Menu entries may be specified in a source's meta data, the key to specify one or more entries is menu. The single_url meta data will be used as URL value for a menu item, unless another value is set explicitly. See Newcomen::Plugin::Blog::Single for details on single_url.

The <menu specification> may be:

For a menu entry created from a source's meta data, the menu item's meta data will contain a key source, referencing the Newcomen::Source instance in which the menu entry was defined (only for the leaf, it will not be set for the automatically created intermediate items). This will later be used to automatically set the menu item's URL: once the pages have been created, for menu items with the source meta data set, the value of single_url in the source's meta data will be used as URL for the menu item. If an URL is set explicitly (only possible for the hashref method, not for single strings), it will not be overridden, though. The single_url meta data is usually set by the Newcomen::Plugin::Blog::Single plugin for the source items.

For the single string method (either a single value or an arrayref containing multiple strings), the strings are processed as menu item paths, as described above. However, there is one addition: If the string starts with a plus sign ('+'), followed by at least one word character (/\w/), followed by at least one space character (/\s/), followed by at least one other character, the first part of the string up to the space will be used as anchor value, with the plus sign replaced by a '#', and the last part of the string (everything after the first space(s)) will be used as path. The anchor value will be set in the meta data of the menu item.

For example, the string '+chapter2 Some/Menu/Entry' would create a menu structure with the two intermediate items for 'Some' and 'Menu' (as described under OPTIONS), and for the last menu item, 'Entry', the anchor value will be set to '#chapter2'.

Note: When using the hashref method to specify menu items, the hashref's keys are used as paths without further processing (the same as for the configuration). An anchor has to be set explicitly in the menu data in this case.

GLOBAL DATA ^

{
   'blog'    => {
      'menu' => <menu root element>,
   },
}

This is the global data (see Newcomen::Core) set by this plugin.

blog/menu is the Newcomen::Plugin::Blog::Menu::Item instance representing the root element of the menu. Its ID is 'root', other properties are not set for the root item.

INSTANCE METHODS ^

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

Returns the Newcomen::Plugin::Blog::Menu::Item instance representing the root element of the menu. Basically the same as accessing the blog/menu global value (see above).

HOOKS ^

This plugin implements the following hooks (with default priority unless mentioned otherwise): hook_init(), hook_process_source(), hook_post_build_pages(), hook_renderer().

SEE ALSO ^

Newcomen::Core, Newcomen::Plugin::Blog::Menu::Item, Newcomen::Plugin::Blog::Single, Newcomen::Source

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/>.