Newcomen

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

Index


NAME ^

Newcomen::Plugin::Blog::Feed::Lists - Creates the feeds for the list index pages.

DESCRIPTION ^

This plugin may be used to generate atom feeds for article indexes created by the plugin Newcomen::Plugin::Blog::Index::Lists.

The indexes to be processed can be freely configured, see OPTIONS. For hierarchical indexes, resulting in more than one index page (that depends on the configuration), one feed will be created for every index page.

Please read the documentation of Newcomen::Plugin::Blog::Index::Lists first!

Collections

For every index collection that should be processed a new collection will be created for the feed. The collection's ID will be set to 'Blog::Feed::Lists/<ID digest>/<element>' (please see the Newcomen::Plugin::Blog::Index::Lists documentation). The collection's creator will be set to 'Blog::Feed::Lists'. The index collection's meta data will be copied to the new collection, and all the sources from the index collection will be added to the feed collection. Sorting of the feed collection is independent from the index collection, see OPTIONS.

The meta data atom_url will be set for the original index collections of every list index. The value will be the page target of the associated feed (the URL of the feed).

Pages

One page will be created for every feed collection (see above). The page's creator will be set to 'Blog::Feed::Lists'. The target and the number of articles per feed will be set to the configured values, see OPTIONS. The page's collection attribute will be set to the source collection of the feed page. See META DATA for details on the meta data of the pages.

For every feed page an entry in the global URL map (see Newcomen::URL) will be created. The key will be set to ['Blog::Feed::Lists', <ID>, <element>] (this is similar to the URLs set by the Newcomen::Plugin::Blog::Index::Lists plugin, please see there for details).

OPTIONS ^

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

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

By default, no list feed will be created (blog/feed/lists is set to an empty hashref).

Example

To create a list feed for the categories list, the following configuration may be used (this requires the index ID in blog/index/lists being set to 'cats', as is the case in the example in the Newcomen::Plugin::Blog::Index::Lists documentation):

{
   'blog'                   => {
      'feed'                => {
         'lists'            => {
            'cats'          => {
               'url'        => '<list_path>/index.atom',
               'ascending'  => undef,
               'entries'    => undef,
               'formatters' => undef,
               'renderer'   => undef,
               'writer'     => undef,
               'feed_info'  => {
                  'title'   => 'Category: <list_item>',
               },
            },
         },
      },
   },
}

For every list feed that should be created, an entry in the blog/feed/lists hashref has to be created. The key must be the same key as used in the blog/index/lists hashref (please see Newcomen::Plugin::Blog::Index::Lists) for the list (in this documentation referred to as list ID). The value for each key must itself be a hashref, as shown in the example. The example above also lists every possible option recognized by this plugin.

The following options may be used:

url specifies the page target. Placeholders are supported, every key in the collection meta data may be used, see META DATA below. If the target is empty after all replacements, the page will not be created.

ascending sets the order of the articles in the feed. If set to a true value, articles will be in ascending order, i.e. oldest first. If this is undef (the default), the values of the options blog/feed/lists/defaults/ascending and blog/feed/defaults/ascending will be tried, in that order. If none of these are set, it defaults to false.

Note that the order is determined by the modification time, not the publication time as is used for the index pages!

entries specifies the number of articles per feed. If this is undef (the default), the values of the options blog/feed/lists/defaults/entries and blog/feed/defaults/entries will be tried. If none of these is set, it defaults to 5. If entries is set to 0, all articles for a list will be included in the feed.

The feed_info hashref may be used to set arbitrary data that will be included in the page's meta data. The data may contain placeholders (same as the url option). Everything set in this hashref will be included in the meta data, with the original keys being prefixed with 'atom_' (so for the example above the page will contain the atom_title key). Before being copied to the meta data, this hashref will be merged with the defaults set in the hashrefs specified by the blog/feed/lists/defaults/feed_info, blog/feed/defaults/feed_info, blog/defaults/page_info, with more specific data overriding less specific data if necessary.

Note that if there is no uuid key in the feed_info hashref (after merging as described above), an UUID will be created for every feed page, based on the list ID. For this to work, the setting blog/feed/defaults/uuid_ns has to be set, please see Newcomen::Plugin::Blog::Feed::Defaults for details. If this options is not set, and there is no UUID in the info hashref, this plugin will die().

Also, if there is no updated key in the info hashref, the atom_updated meta data will be set automatically based on the modification time information of the sources.

formatters, renderer and writer may be used to specify formatter backends for the feed content, and renderer/writer backends for feed 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 ^

Collections

{
   'order_ascending'  => <ascending configuration option>,
   'index_collection' => <original index collection>,
   'atom_url'         => <URL of the Atom feed (see description!)>,
}

The meta data of the index collection will be copied to the feed collection, please see Newcomen::Plugin::Blog::Index::Lists for details.

Additionally, the order_ascending configuration option (determined as described above, see OPTIONS) will be included, and index_collection will be set to the original index collection (created by the Newcomen::Plugin::Blog::Index::Lists plugin) the feed collection is created from.

The atom_url will be set to the feed URLs (page targets) for the list index collections (created by the Newcomen::Plugin::Blog::Index::Lists plugin), not the feed collections!

Pages

{
   'atom_uuid'    => <UUID for the Atom feed>,
   'atom_updated' => <last modification time>,
}

All meta data specified in the feed_info hashref (see OPTIONS) will be set for the pages, keys will be prefixed by 'atom_'. Additionally, even if the feed_info hashref does not contain the uuid and updated keys, atom_uuid and atom_updated will be set for every page (if these are included in the feed_info hashref, the configured values will be used).

HOOKS ^

This plugin implements the following hooks (with default priority unless stated otherwise): hook_build_collections() (priority 600), hook_build_pages(), hook_formatters(), hook_renderer(), hook_writer().

SEE ALSO ^

Newcomen::Plugin::Blog::Defaults, Newcomen::Plugin::Blog::Feed::Defaults, Newcomen::Plugin::Blog::Index::Lists, Newcomen::URL

VERSION ^

This is version 2014101201.

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