Newcomen

Description A static content generator.
Newcomen > Perl Modules > Newcomen::Page
Source

Index

NAME ^

Newcomen::Page - Represents a single output page of the project.

SYNOPSIS ^

use Newcomen::Page;

my $page = Newcomen::Page -> new (
   'creator'    => $creator,
   'target'     => $target,
   'content'    => $content,
   'collection' => $collection,
);

# Add a piece of content:
$page -> push ($content);

# Set some meta data:
$page -> set (['some', 'data'], 'value');

DESCRIPTION ^

An Newcomen::Page instance combines zero or more Newcomen::Content instances and meta data to a page. See the developer section in Newcomen::Manual for a description of how Newcomen works and how pages fit in.

Important: The handling of meta data of an Newcomen::Page instance differs from most other classes. Please see the Meta Data section below for details.

CLASS METHODS ^

new

my $page = Newcomen::Page -> new (
   'creator'    => $creator,
   'target'     => $target,
   'content'    => $content,
   'collection' => $collection,
);

Constructor.

The creator parameter identifies the plugin that creates the page. It is suggested, though not required, to use the module name or module basename (i.e. the module name without the 'Newcomen::Plugin::' prefix).

The target parameter identifies the page. Usually this is the relative target path of the file to be generated. This is not required, though some writers (see Newcomen::Writer) may expect it to be. If the page is added to the site (see Newcomen::Site), every page must have a unique target. The target will be rewritten when an instance is created, by calling the hook_rewrite_target() hook of all plugins implementing it. This can not be disabled on a per-page basis (though a rewrite plugin may be disabled globally). After that, the target can not be changed anymore. The final (rewritten) target must not be empty.

The target and creator parameters are required.

The optional content parameter may be used to set the initial list of content items. If provided, it must be an arrayref containing Newcomen::Content instances (or an empty arrayref).

The optional collection parameter may be used to reference the collection from which a page was created. If provided, it must be an Newcomen::Collection instance (or undef). This can not be changed later on.

INSTANCE METHODS ^

General

creator, target, collection

my $creator    = $page -> creator ();
my $target     = $page -> target ();
my $collection = $page -> collection ();

Returns the creator ID, the page target or the source collection from which the page was created, respectively. The values are set via the constructor (see new() above for a description), and can not be changed later on. Keep in mind that the page's target is subject to the rewrite hooks, thus target() may not return the same value that was passed to the constructor when creating the instance. The return value of the collection() method may be undef.

rel

Toggle source:   rel 

sub rel {

   my $self   = shift;
   my $path   = shift;

   return $path if $path =~ /^[a-z]+:/ai;

   my $tgt_path = Path::Class::file ('.', $self -> target ()) -> parent   ();
   my $rel_path = Path::Class::file ('.', $path             ) -> relative ($tgt_path);

   return $rel_path -> as_foreign ('Unix') -> stringify ();

}
my $rel_path = $page -> rel ($path);

Returns the path specified as the only (and required) parameter relative to the page's parent directory, as determined by the page target.

Both the page target and the supplied parameter have to be file names relative to a common parent directory (usually the output directory). For example, if the page target is 'foo/bar/page' and the path 'foo/baz/something' is specified as parameter to the rel() method, the return value will be '../baz/something'. Note that the two paths will always be interpreted as relative paths, even if they start with '/'.

The rel() method will use Path::Class to determine the relative path to return. It will always be returned in Unix format (i.e. using slashes as separators).

Note: There are is a built-in exception to the above rule. If the parameter looks like an URL, i.e. if it matches the pattern /^[a-z]+:/ai, it will be returned as is. This exception allows using the rel() method in HTML templates without checking for absolute URLs or, for example, mailto: or xmpp: etc. links in the template itself.

dir

Toggle source:   dir 

sub dir {

   my $self = shift;

   my $path = Path::Class::file ('.', $self -> target ()) -> parent () -> as_foreign ('Unix');

   if ($path eq '.') {
      $path = '';
   }
   else {
      $path =~ s!^/*!!;
      $path .= '/' unless $path =~ m!/$!;
   }

   return $path;

}
my $dir = $page -> dir ();

Returns the parent directory of the page's target, in Unix format. This obviously only works if the page target is a path (or something path-like). No assumption is made about the format of the page target, it may not work if it is not specified in the platform's native path format.

Path::Class is used to get the parent directory. If the target does not have any parent directory (i.e. if it is set to only a file name), this method will return an empty string. Otherwise it will be a relative path in Unix format: it will never begin with a slash (i.e. even if the page target starts with a slash, it will be removed from the result of this method), but it will always end with a slash.

rendered

# Get the rendered content:
my $rendered = $page -> rendered ();

# Set the rendered content:
$page -> rendered ($rendered);

Getter/setter for the page's rendered content. This will be set by Newcomen::Renderer during the rendering stage. In general, plugins should not set it directly. Some writers may expect this to be the content that will be written to disk, see the individual writer backends for details. The parameter for the setter may be any string, or undef.

Content

Newcomen::Page uses an arrayref to store the content instances as an ordered list. It uses the array methods of Newcomen::Util::Traits, with the following additions:

Please see Newcomen::Util::Traits for a complete list of methods and more details.

Meta Data

get, set, exists, delete

# Set meta data:
$page -> set (['some', 'data'], 'value');

# Retrieve and delete it, if it exists:
my $value = 'some default value';
if ($page -> exists (['some', 'data'])) {
   $value = $page -> get (['some', 'data']);
   $page -> delete (['some', 'data']);
}

Meta data of an Newcomen::Page instance consists of two parts: The meta data of the collection item referenced by the page (if there is one), and the page's own meta data.

The methods exists() and get() will operate on the page's meta data if it exists for a given key. If it does not exist, they will operate on the collection's meta data for that key. Note that the current implementation uses the merged data (see below), which will always be cloned. So any references will not point to the original data!

The methods delete() and set() on the other hand will only operate on the page's meta data.

The methods get(), set(), delete() and exists() are mapped to the Newcomen::Data methods of the same name. Please see there for details on the parameters.

meta

my $merged = $page -> meta ();

The Newcomen::Data instance returned by the meta() method contains both items' meta data merged (with page meta data overriding collection meta data if necessary) at the time of the call. Merging will be done before or after (as appropriate) every call to get(), set(), exists(), delete(), meta() or page_meta(). Once retrieved, the instance will not be updated (a new instance is created on every merge)! Any changes to the Newcomen::Data instance returned by meta() will be lost on the next call to one of the aforementioned methods. It is recommended to only use meta() to read the meta data (mostly used in the templates). The meta() method exists only to provide an interface consistent with the other classes.

page_meta

my $page_meta = $page -> page_meta ();

The Newcomen::Data instance returned by page_meta() contains the page's own meta data, without any collection meta data. If access to page meta data only is required, without falling back to the collection meta data, this method may be used to access the Newcomen::Data instance. After every call to page_meta() meta data merging occurs, so changes in the page's meta data will be visible when using meta().

Rendering And Writing Backends

One rendering and one writing backend may be assigned to a page using the following methods:

renderer, writer

# Get current renderer backend settings:
my $renderer_spec = $page -> renderer ();

# Set new writer backend:
$page -> writer ($writer_spec);

Get or set the renderer or writer specification for the page. The return value of the getter as well as the parameter for the setter is either an Newcomen::Renderer::Specification instance or an Newcomen::Writer::Specification instance, respectively. Both may also be set to undef if required.

set_renderer, set_writer

Toggle sources:   set_renderer   set_writer 

sub set_renderer {

   my $self    = shift;
   my $spec    = shift;
   my $creator = shift;

   $self -> _set_backend ($spec, $creator, 'renderer', 'Newcomen::Renderer::Specification');

}
sub set_writer {

   my $self    = shift;
   my $spec    = shift;
   my $creator = shift;

   $self -> _set_backend ($spec, $creator, 'writer', 'Newcomen::Writer::Specification');

}
# Set renderer by name:
$page -> set_renderer ($name, qr/^Some::Plugin::/);

# Set renderer (name and options):
$page -> set_renderer (
   {'name' => $name, 'options' => $options},
   $creator
);

These methods will set the renderer (or writer), but only if the following conditions are both true:

Both methods will do nothing if one of these conditions is not met.

The first parameter must be either undef, a string, or a hashref. If it is undef (or another value that evaluates to false), these methods will do nothing. If it is a string, the renderer (or writer) of the page will be set to a backend specification using this name, with empty options. If it is a hashref, it must contain the key 'name' (the value will be used as the backend name), and it may contain the key 'options' (the value must be a hashref itself and will be used as backend options). Other keys will be ignored. See above for an example.

If no second parameter is supplied, the pages creator must match the caller's basename (i.e. the caller's module name without the 'Newcomen::Plugin::' prefix). In this case, you must not use these methods from within modules that are not in the Newcomen::Plugin namespace! If the second parameter is supplied, it must be a regular expression (qr//, see the example above), and the page's creator will be matched against it.

Formatting, Rendering, Writing

format

Toggle source:   format 

sub format {

   my $self = shift;

   return unless $self -> count ();

   for my $index (0 .. $self -> count () - 1) {
      my $content = $self -> content ($index);
      $self -> _formatter () -> format_content ($content, $self, $index);
   }

}
$page -> format ();

This method will format all the content items on the page, according to their formatter settings. It will simply iterate over the Newcomen::Content instances and call the format_content() method of the main Newcomen::Formatter instance for each content item.

render, write

Toggle sources:   render   write 

sub render { $_ [0] -> _renderer () -> render_page ($_ [0]) }
sub write  { $_ [0] -> _writer   () -> write_page  ($_ [0]) }
$page -> render ();
$page -> write  ();

These two methods will render and write the page, respectively. They are simple wrappers for the respective methods of the main renderer and writer instances: render_page() (of Newcomen::Renderer) and write_page() (of Newcomen::Writer). The two method calls above are effectively the same as

$renderer -> render_page ($page);
$writer   -> write_page  ($page);

With $renderer and $writer being the renderer and writer instances provided by the core (see Newcomen::Core).

SEE ALSO ^

Path::Class, Newcomen::Collection, Newcomen::Content, Newcomen::Core, Newcomen::Data, Newcomen::Formatter, Newcomen::Manual, Newcomen::Renderer, Newcomen::Renderer::Specification, Newcomen::Site, Newcomen::Util::Traits, Newcomen::Writer, Newcomen::Writer::Specification

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

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