/ 
Positron-v0.1.3
River stage zero No dependents
/ Positron::Handler::ArrayRef

NAME

Positron::Handler::ArrayRef - a DOM interface for ArrayRefs

VERSION

version v0.1.3

SYNOPSIS

my $engine = Positron::Template->new();

my $template = [
  'a',
  { href => "/"},
  [ 'b', "Now: " ],
  "next page",
];
my $data   = { foo => 'bar', baz => [ 1, 2, 3 ] };
my $result = $engine->parse($template, $data);

DESCRIPTION

This module allows Positron::Template to work with a simple DOM representation: ArrayRefs. This module can also be used as a blueprint for writing more handlers; the documentation of the methods is therefore extra deep.

ArrayRef representation

In ArrayRef representation, a DOM element is simply a reference to an array with at least one element: the node tag, an optional hash (reference) with attributes, and any children the node might have. Pure text is represented by simple strings. Comments, processing instructions or similar have no intrinsic representation; at best they can be represented as simple nodes with special tag names.

An example:

[
  'a',
  { href => "/"},
  [ 'b', "Now: " ],
  "next page >>",
  ['br'],
];

This corresponds to the HTML representation of:

<a href="/"><b>Now: </b>next page &gt;&gt;<br /></a>

Note the plain >> in the ArrayRef representation: text does not need to be encoded in HTML entities. Note also that the attributes, if present, need to occupy the second slot of the array reference. A missing attribute hash reference corresponds to no attributes.

CONSTRUCTOR

new

$handler = Positron::Handler::ArrayRef->new();

The constructor has no parameters; this is a very basic class. Normally, the template engine will automatically call the constructor of the correct handler for whatever it is handed as template.

METHODS

The following methods are part of the "handler interface". The point of a handler is to present a unified interface for all DOM operations that Positron::Template needs to do. So even though these methods are quite simple, even trivial, given the ArrayRef representation, they must be fully implemented.

shallow_clone

$new_node = $handler->shallow_clone($orig_node);

This method returns a clone of the given node. This clone has the same attributes as the original, but no children. The clone is never identical to the original, even if it could be (i.e. the original has no children).

Text nodes, which are simple strings, are cloned to copies of themselves.

get_attribute

$value = $handler->get_attribute($node, $attr_name);

Gets the value of a named attribute of the node. If the node does not have an attribute of this name, or it is a text node (which has no attributes), undef is returned.

set_attribute

$handler->set_attribute($node, $attr_name => $new_value);

Sets the named attribute to the new value. Setting an attribute to undef will delete the attribute. It is not an error to try to set an attribute on a text node, but nothing will happen.

Returns the new value (or undef as needed), though Positron::Template does not use the return value.

list_attributes

@attr_names = $handler->list_attributes($node);

Lists the names of all (defined) attributes on the node. Text nodes have no attributes and generate an empty list.

push_contents

$handler->push_contents($node, $child_1, $child_2, $child_3);

Push the passed nodes, in the given order, onto the end of the child list of the first argument. Text nodes, again, ignore this method silently.

list_contents

@child_nodes = $handler->list_contents($node);

Lists the contents, i.e. the child nodes, of the given node. These are not cloned nodes, but the actual children. Text nodes, of course, have none.

parse_file

$root_node = $handler->parse_file($filename);

Reads and parses a file with the given filename. It is recommended to pass an absolute filename, unless you can be sure about your current directory. Normally, this method would not be necessary (since the template engine works on already-parsed DOM trees by design), but there are template constructs that include files via filename.

If $filename ends in .json or .js, the file is assumed to be in JSON format, and will be parsed with a freshly required JSON module.

Otherwise, it is assumed to be an array reference serialized with the Storable module.

AUTHOR

Ben Deutsch, <ben at bendeutsch.de>

BUGS

None known so far, though keep in mind that this is alpha software.

Please report any bugs or feature requests to bug-positron at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Positron. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

This module is part of the Positron distribution.

You can find documentation for this distribution with the perldoc command.

perldoc Positron

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright 2013 Ben Deutsch. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://dev.perl.org/licenses/ for more information.