Newcomen

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

Index


NAME ^

Newcomen::Plugin::Blog::Index::Main - Creates the blog's main index pages.

DESCRIPTION ^

This plugin will create the main index page(s), i.e. the index page(s) containing all blog articles, usually used as a blog's start page. Posts will be sorted by publication time.

Collections

One collection will be created with both the collection ID and the creator ID set to 'Blog::Index::Main'. All source items with the creator ID 'Blog::Crawler' will be included. The sources in the collection will be sorted by publication time, in descending order by default (this can be changed in the configuration). For this to work a source's meta data must contain the time/published/epoch key (set by the plugin Newcomen::Plugin::Blog::Source::Time by default). Sources without this key (or an invalid value for the key) will not be included. No meta data will be set for the collection.

Content

Newcomen::Content instances will be created for all sources on the final pages. No meta data will be set for the content items.

Pages

The source instances in the collection (see Collections) will be distributed to the individual pages, the number of articles per page can be configured by the user (it defaults to 5 if not set, see OPTIONS below). See META DATA for the page's meta data set by this plugin. The page target will be set according to the configuration, see below.

An entry will be created in the global URL map (see Newcomen::URL) for every page. The key will be Blog::Index::Main/<page>, with <page> being the number of the page, starting with 1.

OPTIONS ^

{
   'blog'                  => {
      'index'              => {
         'main'            => {
            'ascending'    => undef,
            'per_page'     => undef,
            'page_info'    => {},
            'formatters'   => undef,
            'renderer'     => undef,
            'writer'       => undef,
            'index'        => {
               'page_info' => {},
               'url'       => undef,
            },
            'pages'        => {
               'page_info' => {},
               'url'       => undef,
            }
         },
      },
   },
}

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

blog/index/main/ascending may be set to a true value if the articles should be sorted by publication time in ascending order (i.e. oldest articles first). If this is undef, the value of blog/index/defaults/ascending will be used, if this, too, is undef, it defaults to 0.

blog/index/main/per_page specifies the maximum number of articles on one index page. It must be an integer greater or equal to zero. If it is set to zero, all articles will be put on one index page. If it is undef (the default), the value of blog/index/defaults/per_page will be used. If this, too, is undef, the value 5 will be used.

blog/index/main/index and blog/index/main/pages are both hashrefs with the keys page_info and url. The blog/index/main/index hashref contains the page info and URL settings for the first index page (page one), the blog/index/main/pages hashref contains the page info and URL settings for all other pages (page two and all subsequent pages).

The page_info hashrefs may be used to set arbitrary data that will be included in the page's meta data. The data may contain placeholders (same as for the url option, see below). Everything set in these hashrefs will be included in the meta data, with the original keys being prefixed with 'info_'. The blog/index/main/index/page_info and blog/index/main/pages/page_info hashrefs will be merged with the following default options (in that order): blog/index/main/page_info, blog/index/defaults/page_info and blog/defaults/page_info. More specific data will override less specific (default) data if necessary. (Also see Newcomen::Plugin::Blog::Index::Defaults and Newcomen::Plugin::Blog::Defaults.)

The page_info data and the url option may contain placeholders for replacement, as described in the documentation of Newcomen::Plugin::Blog::Single's options, please see there for details. The meta data available for replacement is the meta data of the index collection (see Collections), which is usually empty. Additionally, the following data is available:

{
   'page'        => <current page>,
   'pages'       => <total number of pages>,
   'posts_total' => <total number of posts in the collection>,
   'posts_from'  => <number of first post on the page>,
   'posts_to'    => <number of last post on the page>,
}

All numbers start at one. If after replacement the URL should be empty, the page will not be created.

The options blog/index/main/formatters, blog/index/main/renderer and blog/index/main/writer may be used to specify formatter backends for the index page content, and renderer/writer backends for index pages. The format is the same as described for the options in Newcomen::Plugin::Blog::Defaults, please see there for details. If these are undef (the default), no backends will be set, and another plugin may set these.

META DATA ^

Pages

{
   'page'        => <current page>,
   'pages'       => <total number of pages>,
   'posts_total' => <total number of posts in the collection>,
   'posts_from'  => <number of first post on the page>,
   'posts_to'    => <number of last post on the page>,
   'prev_page'   => <URL of previous page>,
   'next_page'   => <URL of next page>,
   'page_type'   => 'multiple',
}

title will be the title of the page, as configured. page_type will always be set to 'multiple'. prev_page and next_page will be set to the URL of the previous and/or next page, if there is a previous and/or next page. The other keys are explained above, see OPTIONS.

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

HOOKS ^

This plugin implements the following hooks: hook_build_collections() (priority 400), hook_build_pages(), hook_formatters(), hook_renderer() and hook_writer() (default priority).

SEE ALSO ^

Newcomen::Collection, Newcomen::Content, Newcomen::Page, Newcomen::Plugin::Blog::Defaults, Newcomen::Plugin::Blog::Index::Defaults, Newcomen::Plugin::Blog::Single, Newcomen::Plugin::Blog::Source::Time, 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/>.