Newcomen

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

Index

NAME ^

Newcomen::Plugin::Blog::Index::List - Creates custom index pages.

DESCRIPTION ^

This plugin may be used to create index pages for arbitrary meta data lists of the source items, for example category index pages or tag index pages. The meta data to create an index page from has to be an arrayref, for every item in the arrayref one or more index pages will be created. Both hierarchical (e.g. categories and subcategories) and non-hierarchical (e.g. tags) items are supported. For hierarchical data there is a configuration option whether sub-items should be included on the pages or not (e.g. whether to include category/subcategory items on the category index pages). For hierarchical items the slash ('/') is used as a separator.

Please see the OPTIONS for details on how to specify the data used to build the index pages.

Sources

For hierarchical data, the source lists in the Newcomen::Source instances' meta data will be cleaned up: for every source list element, multiple consecutive slashes will be replaced by one, and slashes at the beginning and end of an element will be removed. Non-hierarchical data will not be altered. If the specified source list is not an arrayref, it will be ignored. All source items with the creator ID 'Blog::Crawler' will be processed.

Collections

For every index page to be created one collection will be created. For non-hierarchical data, this means that every item in one of the source lists will result in one collection. For hierarchical data the same applies if the exclude_children option is set. If not, one element in the source list will create a collection for every part in its hierarchy (e.g. given the element category/subcategory, one collection will be created for category/subcategory and one for category). The collection ID will be set to 'Blog::Index::Lists/<ID digest>/<element>', with <ID digest> being the hexadecimal representation of the SHA-1 digest of the index ID (see OPTIONS, usually the index ID is the same as the meta data key of the source list), and <element> the element in the list for which the collection is created. The creator ID will be 'Blog::Index::Lists'.

Pages

For every collection created (as described above) one or more pages will be created (depending on the per_page option, see below). Note that this plugin keeps an internal list of all the collections it created, and only those will be processed. Collections may still be deleted to prevent pages from being created, but no collection added by another plugin to the catalog will be used by this plugin. Page targets will be set according to the configuration. The creator ID will be set to 'Blog::Index::Lists'. The page's collection attribute will reference the source collection.

The page targets will be stored in the global URL map (see Newcomen::URL) with the key ['Blog::Index::Lists', <ID>, <element>, <page>]. <ID> is the index ID (please see the OPTIONS for details) and <element> the element in the list for which the page was created. <page> specifies the page number (starting at one). It is recommended to always use the arrayref access for this key, since both <ID> and <element> may contain slashes.

OPTIONS ^

{
   'blog'        => {
      'index'    => {
         'lists' => {},
      },
   },
}

This data structure is defined by this plugin by default. It doesn't really contain any options. The user configuration may add options as required. If so, the values in the blog/index/lists hashref must themselves be hashrefs.

The following example will add index pages for categories and tags:

{
   'blog'                         => {
      'index'                     => {
         'lists'                  => {
            'cats'                => {
               'ascending'        => 0,
               'exclude_children' => 0,
               'hierarchical'     => 1,
               'per_page'         => 5,
               'source_list'      => 'categories'
               'page_info'        => {
                  'title'         => 'A Category Listing',
               },
               'index'            => {
                  'url'           => '<list_path>/index.html',
               },
               'pages'            => {
                  'url'           => '<list_path>/page-<page>/index.html',
               },
            },
            'tags'                => {
               'hierarchical'     => 0,
               'index'            => {
                  'page_info'     => {
                     'title'      => 'Tag: <list_name>',
                  },
                  'url'           => 'tag/<list_path>/index.html',
               },
               'pages'            => {
                  'page_info'     => {
                     'title'      => 'Tag: <list_name>, Page <page> of <pages>',
                  },
                  'url'           => 'tag/<list_path>/page-<page>/index.html',
               },
            },
         },
      },
   },
}

The keys in the blog/index/lists hashref are the index ID ('cats' and 'tags' in the example above). These index IDs will be used to look up the source lists in the Newcomen::Source instances' meta data, i.e. the lists key has to match the index ID. Nested meta data is supported using slashes as separators. To override the meta data key, the source_list option in an item's hashref may be used (in the example: blog/index/lists/cats/source_list is set, so the list in the source meta data is called 'categories', instead of 'cats', which would be used by default).

In the source items meta data the specified list has to be an arrayref, if not, or if it doesn't exist, the source item will not be included on the index page.

Note: The index ID defaults is reserved and must not be used for user configuration!

The blog/index/lists/<index ID> hashrefs may contain the following options (the following names are all relative to these hashrefs, unless they start with blog/):

META DATA ^

Collections

{
   'list_id'           => $list_id,
   'list_id_sha1'      => $list_id_sha1,
   'list_source'       => $list_source,
   'list_item'         => $list_item,
   'list_path'         => $list_path,
   'list_hierarchical' => $list_hierarchical,
   'list_no_children'  => $list_no_children,
}

Pages

{
   'page'        => $cur_page,
   'pages'       => $pages,
   'posts_total' => $count,
   'posts_from'  => $posts_from,
   'posts_to'    => $posts_to,
   'prev_page'   => $prev_page,
   'next_page'   => $next_page,
   'type'        => 'multiple'
}

The meta data of the collection the page is created from may be accessed through the page's meta data, see Newcomen::Page for details.

type will always be set to 'multiple'. The other keys are the same as described in Newcomen::Plugin::Blog::Index::Main, please see there for details.

Additionally, all meta data specified in the page_info hashref(s) (see OPTIONS) will be set for the pages, keys will be prefixed by 'info_'.

HOOKS ^

This plugin implements the following hooks: hook_process_source(), hook_build_collections(), hook_post_build_collections(), hook_build_pages(), hook_formatters(), hook_renderer() and hook_writer() (all with default priority).

SEE ALSO ^

Newcomen::Collection, Newcomen::Page, Newcomen::Plugin::Blog::Defaults, Newcomen::Plugin::Blog::Index::Lists::Defaults, Newcomen::Plugin::Blog::Index::Main, Newcomen::Source, Newcomen::URL

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