Index

NAME
SYNOPSIS
DESCRIPTION
CLASS METHODS
- new
INSTANCE METHODS
- General
- Meta Data
SEE ALSO
VERSION
AUTHOR
COPYRIGHT AND LICENSE

NAME

Newcomen::Content - Represents a piece of content on a page.

SYNOPSIS

use Newcomen::Content;

my $content = Newcomen::Content -> new ('source' => $source);

# Set the actual content (text):
$content -> content ($text);

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

# Access the associated source item:
my $source = $content -> source ();

DESCRIPTION

An Newcomen::Content instance is basically a container for an Newcomen::Source instance, and related meta data. It is used to keep the source item's content separated from its formatted content. Any source item may be referenced by an arbitrary number of content items (and thus different formatters may be applied to the content), and every content item references exactly zero or one source item. The Newcomen::Content instances also keep a list of formatter specifications (see Newcomen::Formatter::Specification::List), and the content of the instance will be formatted according to the formatter specifications in this list (if the content item is added to a page, see Newcomen::Page).

Content items are used by the pages (see Newcomen::Page), and every item usually represents a piece of content on a page (created from the associated source item). See the developer section in Newcomen::Manual for a description of how Newcomen works and how these content items fit in.

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

CLASS METHODS

new

my $content = Newcomen::Content -> new ('source' => $source);

Constructor. The source parameter is optional. If specified, it must either be the Newcomen::Source instance that should be associated with the new content item, or undef (which is basically the same as not specifying a source parameter). The source item can not be changed later on.

INSTANCE METHODS

General

content

# Get the current content:
my $text = $content -> content ();

# Set the content:
$content -> content ($text);

Get and set the content. As a setter, the first (and only) parameter must be a string, or undef. The initial value is the value of the source item's content (if one is set, else undef), it will be set on first access (not during construction). Note that the setter's parameter may be any string, i.e. it may also be a binary format if this is required for some reason.

source

my $source = $content -> source ();

Returns the Newcomen::Source instance associated with the Newcomen::Content instance (if any). The source can only be set by the constructor (see new()). If no source item is set, this method will return undef.

formatters

my $formatters = $content -> formatters ();

# To add formatter specifications:
$content -> formatters () -> add ([$spec_1, $spec_2]);

Returns the Newcomen::Formatter::Specification::List instance associated with the content item. The list will be empty initially.

Meta Data

get, set, exists, delete

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

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

Meta data of an Newcomen::Content instance consists of two parts: The meta data of the source item referenced by the content (if any), and the content item's own meta data.

The methods exists() and get() will operate on the content's meta data if it exists for a given key. If it does not exist, they will operate on the source item'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 content'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.

content_meta

my $content_meta = $content -> content_meta ();

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

VERSION

This is version 2014052501.

AUTHOR

Stefan Goebel - newcomen {at} subtype {dot} de

COPYRIGHT AND LICENSE

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

Newcomen