Newcomen

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

Index

NAME ^

Newcomen::Plugin::Blog::Single - Creates single article pages.

DESCRIPTION ^

This plugin is responsible for creating the blog's single article pages.

Sources

This plugin will process all Newcomen::Source instances with the crawler ID 'Blog::Crawler'. The meta data of the source items may include the key single_url. It may be used to override the global setting blog/single/url on a per-article basis, see OPTIONS. If a page is created for a source item, the single_url meta data will be set (i.e. created, or overridden if it did already exist).

Collections

This plugin will create one Newcomen::Collection instance. Its creator ID and its collection ID will both be set to 'Blog::Single'. The collection will include all source items with the crawler ID 'Blog::Crawler'. It may be empty if there are no such source items. No meta data will be set.

Content

An Newcomen::Content instance will be created for every page, referencing the single blog source of the page. See below. No meta data will be set for the content instances.

Pages

One page will be created for every Newcomen::Source instance in the collection with the ID 'Blog::Single' (see above). This will be the single article page for the respective source item. The page will contain exactly one Newcomen::Content instance, referencing this source item. The page target, the meta data title, content formatters, page renderer and writer will all be set according to the configuration, see OPTIONS. The creator ID of the page will be 'Blog::Single'. The page's collection attribute will be set to the collection described above. Another piece of meta data will be set: the key page_type, the value will always be 'single'.

An entry will be created in the global URL map (see Newcomen::URL) for every page. The key will be ['Blog::Single', <source ID>], with <source ID> being the ID of the Newcomen::Source instance belonging to the page.

OPTIONS ^

{
   'blog'             => {
      'single'        => {
         'page_info'  => {},
         'url'        => undef,
         'formatters' => undef,
         'renderer'   => undef,
         'writer'     => undef,
      },
   },
}

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

url specifies the URL for single article pages, this will be used as the target file name. It must be specified relative to the output directory. This option may contain placeholders in the format <name>. name must be a key in the source item's meta data. All occurrences of placeholders will be replaced by the meta data value for the specified keys. Nested data structures (both hashes and arrays) are supported using slashes (/) as separators. If a key does not exist in the page's source item's meta data, it will be replaced by an empty string. Replacement is done recursively, i.e. the replacement values may again contain placeholders (beware of infinite recursion, there is no check to avoid this). If the URL is empty after all replacements, the page will not be created, the same applies if the url configuration setting is undef (the default).

For example, to set the URL's path to the first category (with categories being an arrayref in the meta data and categories/0 being the first element of that array), and the file name to the source's slug value with a '.html' extension, the following setting could be used:

{
   'blog'      => {
      'single' => {
         'url' => => '<categories/0>/<slug>.html',
      },
   },
}

Note that the category list may be empty, in which case the file would be placed in the root (i.e. the file will be created directly in the output directory).

Note that in addition to the source item's actual meta data, the keys year, month and day are available for replacement. These will be set to time/published/year, time/published/Month and time/published/Day (i.e. they are just shortcuts for other meta information), respectively, unless the key is actually already present in the meta data, in which case the original value will be available for replacement.

The blog/single/page_info hashref may be used to set arbitrary data that will be included in the page's meta data. Before processing, this hashref and the hashref of the blog/defaults/page_info option (see Newcomen::Plugin::Blog::Defaults) will be merged, with blog/single/page_info data overriding blog/defaults/page_info data if required. The data may contain placeholders (same as for the url option, see above), these will be replaced (recursively). All data set in this hashref (and/or the defaults hashref) will be included in the page's meta data, with the original keys being prefixed with 'info_'.

The options blog/single/formatters, blog/single/renderer and blog/single/writer may be used to specify formatter backends for single page content, and renderer/writer backends for single 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 (probably Newcomen::Plugin::Blog::Defaults).

META DATA ^

Sources

{
   'single_url' => $single_url,
}

Before a page is created, a source's single_url meta data may be used to override the global setting blog/single/url (for that source's page only). The format is the same as for the option blog/single/url, see OPTIONS above.

After the page is created, single_url will be set to the page target (i.e. the page's URL), overriding the initial value if it was set.

Pages

{
   'page_type' => 'single',
}

The page_type will always be set to 'single' for single article pages. Additionally, all values set in the page_info configuration hashref (see OPTIONS) will be included, with their keys being prefixed with 'info_'.

HOOKS ^

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

SEE ALSO ^

Newcomen::Collection, Newcomen::Content, Newcomen::Plugin::Blog::Crawler, Newcomen::Plugin::Blog::Defaults, 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/>.

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