| 1 |
#============================================================= -*-Perl-*- |
| 2 |
# |
| 3 |
# Template::View |
| 4 |
# |
| 5 |
# DESCRIPTION |
| 6 |
# A custom view of a template processing context. Can be used to |
| 7 |
# implement custom "skins". |
| 8 |
# |
| 9 |
# AUTHOR |
| 10 |
# Andy Wardley <[email protected]> |
| 11 |
# |
| 12 |
# COPYRIGHT |
| 13 |
# Copyright (C) 2000 Andy Wardley. All Rights Reserved. |
| 14 |
# |
| 15 |
# This module is free software; you can redistribute it and/or |
| 16 |
# modify it under the same terms as Perl itself. |
| 17 |
# |
| 18 |
# TODO |
| 19 |
# * allowing print to have a hash ref as final args will cause problems |
| 20 |
# if you do this: [% view.print(hash1, hash2, hash3) %]. Current |
| 21 |
# work-around is to do [% view.print(hash1); view.print(hash2); |
| 22 |
# view.print(hash3) %] or [% view.print(hash1, hash2, hash3, { }) %] |
| 23 |
# |
| 24 |
#============================================================================ |
| 25 |
|
| 26 |
package Template::View; |
| 27 |
|
| 28 |
use strict; |
| 29 |
use warnings; |
| 30 |
use base 'Template::Base'; |
| 31 |
|
| 32 |
our $VERSION = 2.91; |
| 33 |
our $DEBUG = 0 unless defined $DEBUG; |
| 34 |
our @BASEARGS = qw( context ); |
| 35 |
our $AUTOLOAD; |
| 36 |
our $MAP = { |
| 37 |
HASH => 'hash', |
| 38 |
ARRAY => 'list', |
| 39 |
TEXT => 'text', |
| 40 |
default => '', |
| 41 |
}; |
| 42 |
|
| 43 |
|
| 44 |
#------------------------------------------------------------------------ |
| 45 |
# _init(\%config) |
| 46 |
# |
| 47 |
# Initialisation method called by the Template::Base class new() |
| 48 |
# constructor. $self->{ context } has already been set, by virtue of |
| 49 |
# being named in @BASEARGS. Remaining config arguments are presented |
| 50 |
# as a hash reference. |
| 51 |
#------------------------------------------------------------------------ |
| 52 |
|
| 53 |
sub _init { |
| 54 |
my ($self, $config) = @_; |
| 55 |
|
| 56 |
# move 'context' somewhere more private |
| 57 |
$self->{ _CONTEXT } = $self->{ context }; |
| 58 |
delete $self->{ context }; |
| 59 |
|
| 60 |
# generate table mapping object types to templates |
| 61 |
my $map = $config->{ map } || { }; |
| 62 |
$map->{ default } = $config->{ default } unless defined $map->{ default }; |
| 63 |
$self->{ map } = { |
| 64 |
%$MAP, |
| 65 |
%$map, |
| 66 |
}; |
| 67 |
|
| 68 |
# local BLOCKs definition table |
| 69 |
$self->{ _BLOCKS } = $config->{ blocks } || { }; |
| 70 |
|
| 71 |
# name of presentation method which printed objects might provide |
| 72 |
$self->{ method } = defined $config->{ method } |
| 73 |
? $config->{ method } : 'present'; |
| 74 |
|
| 75 |
# view is sealed by default preventing variable update after |
| 76 |
# definition, however we don't actually seal a view until the |
| 77 |
# END of the view definition |
| 78 |
my $sealed = $config->{ sealed }; |
| 79 |
$sealed = 1 unless defined $sealed; |
| 80 |
$self->{ sealed } = $sealed ? 1 : 0; |
| 81 |
|
| 82 |
# copy remaining config items from $config or set defaults |
| 83 |
foreach my $arg (qw( base prefix suffix notfound silent )) { |
| 84 |
$self->{ $arg } = $config->{ $arg } || ''; |
| 85 |
} |
| 86 |
|
| 87 |
# name of data item used by view() |
| 88 |
$self->{ item } = $config->{ item } || 'item'; |
| 89 |
|
| 90 |
# map methods of form ${include_prefix}_foobar() to include('foobar')? |
| 91 |
$self->{ include_prefix } = $config->{ include_prefix } || 'include_'; |
| 92 |
# what about mapping foobar() to include('foobar')? |
| 93 |
$self->{ include_naked } = defined $config->{ include_naked } |
| 94 |
? $config->{ include_naked } : 1; |
| 95 |
|
| 96 |
# map methods of form ${view_prefix}_foobar() to include('foobar')? |
| 97 |
$self->{ view_prefix } = $config->{ view_prefix } || 'view_'; |
| 98 |
# what about mapping foobar() to view('foobar')? |
| 99 |
$self->{ view_naked } = $config->{ view_naked } || 0; |
| 100 |
|
| 101 |
# the view is initially unsealed, allowing directives in the initial |
| 102 |
# view template to create data items via the AUTOLOAD; once sealed via |
| 103 |
# call to seal(), the AUTOLOAD will not update any internal items. |
| 104 |
delete @$config{ qw( base method map default prefix suffix notfound item |
| 105 |
include_prefix include_naked silent sealed |
| 106 |
view_prefix view_naked blocks ) }; |
| 107 |
$config = { %{ $self->{ base }->{ data } }, %$config } |
| 108 |
if $self->{ base }; |
| 109 |
$self->{ data } = $config; |
| 110 |
$self->{ SEALED } = 0; |
| 111 |
|
| 112 |
return $self; |
| 113 |
} |
| 114 |
|
| 115 |
|
| 116 |
#------------------------------------------------------------------------ |
| 117 |
# seal() |
| 118 |
# unseal() |
| 119 |
# |
| 120 |
# Seal or unseal the view to allow/prevent new datat items from being |
| 121 |
# automatically created by the AUTOLOAD method. |
| 122 |
#------------------------------------------------------------------------ |
| 123 |
|
| 124 |
sub seal { |
| 125 |
my $self = shift; |
| 126 |
$self->{ SEALED } = $self->{ sealed }; |
| 127 |
} |
| 128 |
|
| 129 |
sub unseal { |
| 130 |
my $self = shift; |
| 131 |
$self->{ SEALED } = 0; |
| 132 |
} |
| 133 |
|
| 134 |
|
| 135 |
#------------------------------------------------------------------------ |
| 136 |
# clone(\%config) |
| 137 |
# |
| 138 |
# Cloning method which takes a copy of $self and then applies to it any |
| 139 |
# modifications specified in the $config hash passed as an argument. |
| 140 |
# Configuration items may also be specified as a list of "name => $value" |
| 141 |
# arguments. Returns a reference to the cloned Template::View object. |
| 142 |
# |
| 143 |
# NOTE: may need to copy BLOCKS??? |
| 144 |
#------------------------------------------------------------------------ |
| 145 |
|
| 146 |
sub clone { |
| 147 |
my $self = shift; |
| 148 |
my $clone = bless { %$self }, ref $self; |
| 149 |
my $config = ref $_[0] eq 'HASH' ? shift : { @_ }; |
| 150 |
|
| 151 |
# merge maps |
| 152 |
$clone->{ map } = { |
| 153 |
%{ $self->{ map } }, |
| 154 |
%{ $config->{ map } || { } }, |
| 155 |
}; |
| 156 |
|
| 157 |
# "map => { default=>'xxx' }" can be specified as "default => 'xxx'" |
| 158 |
$clone->{ map }->{ default } = $config->{ default } |
| 159 |
if defined $config->{ default }; |
| 160 |
|
| 161 |
# update any remaining config items |
| 162 |
my @args = qw( base prefix suffix notfound item method include_prefix |
| 163 |
include_naked view_prefix view_naked ); |
| 164 |
foreach my $arg (@args) { |
| 165 |
$clone->{ $arg } = $config->{ $arg } if defined $config->{ $arg }; |
| 166 |
} |
| 167 |
push(@args, qw( default map )); |
| 168 |
delete @$config{ @args }; |
| 169 |
|
| 170 |
# anything left is data |
| 171 |
my $data = $clone->{ data } = { %{ $self->{ data } } }; |
| 172 |
@$data{ keys %$config } = values %$config; |
| 173 |
|
| 174 |
return $clone; |
| 175 |
} |
| 176 |
|
| 177 |
|
| 178 |
#------------------------------------------------------------------------ |
| 179 |
# print(@items, ..., \%config) |
| 180 |
# |
| 181 |
# Prints @items in turn by mapping each to an approriate template using |
| 182 |
# the internal 'map' hash. If an entry isn't found and the item is an |
| 183 |
# object that implements the method named in the internal 'method' item, |
| 184 |
# (default: 'present'), then the method will be called passing a reference |
| 185 |
# to $self, against which the presenter method may make callbacks (e.g. |
| 186 |
# to view_item()). If the presenter method isn't implemented, then the |
| 187 |
# 'default' map entry is consulted and used if defined. The final argument |
| 188 |
# may be a reference to a hash array providing local overrides to the internal |
| 189 |
# defaults for various items (prefix, suffix, etc). In the presence |
| 190 |
# of this parameter, a clone of the current object is first made, applying |
| 191 |
# any configuration updates, and control is then delegated to it. |
| 192 |
#------------------------------------------------------------------------ |
| 193 |
|
| 194 |
sub print { |
| 195 |
my $self = shift; |
| 196 |
|
| 197 |
# if final config hash is specified then create a clone and delegate to it |
| 198 |
# NOTE: potential problem when called print(\%data_hash1, \%data_hash2); |
| 199 |
if ((scalar @_ > 1) && (ref $_[-1] eq 'HASH')) { |
| 200 |
my $cfg = pop @_; |
| 201 |
my $clone = $self->clone($cfg) |
| 202 |
|| return; |
| 203 |
return $clone->print(@_) |
| 204 |
|| $self->error($clone->error()); |
| 205 |
} |
| 206 |
my ($item, $type, $template, $present); |
| 207 |
my $method = $self->{ method }; |
| 208 |
my $map = $self->{ map }; |
| 209 |
my $output = ''; |
| 210 |
|
| 211 |
# print each argument |
| 212 |
foreach $item (@_) { |
| 213 |
my $newtype; |
| 214 |
|
| 215 |
if (! ($type = ref $item)) { |
| 216 |
# non-references are TEXT |
| 217 |
$type = 'TEXT'; |
| 218 |
$template = $map->{ $type }; |
| 219 |
} |
| 220 |
elsif (! defined ($template = $map->{ $type })) { |
| 221 |
# no specific map entry for object, maybe it implements a |
| 222 |
# 'present' (or other) method? |
| 223 |
if ( $method && UNIVERSAL::can($item, $method) ) { |
| 224 |
$present = $item->$method($self); ## call item method |
| 225 |
# undef returned indicates error, note that we expect |
| 226 |
# $item to have called error() on the view |
| 227 |
return unless defined $present; |
| 228 |
$output .= $present; |
| 229 |
next; ## NEXT |
| 230 |
} |
| 231 |
elsif ( ref($item) eq 'HASH' |
| 232 |
&& defined($newtype = $item->{$method}) |
| 233 |
&& defined($template = $map->{"$method=>$newtype"})) { |
| 234 |
} |
| 235 |
elsif ( defined($newtype) |
| 236 |
&& defined($template = $map->{"$method=>*"}) ) { |
| 237 |
$template =~ s/\*/$newtype/; |
| 238 |
} |
| 239 |
elsif (! ($template = $map->{ default }) ) { |
| 240 |
# default not defined, so construct template name from type |
| 241 |
($template = $type) =~ s/\W+/_/g; |
| 242 |
} |
| 243 |
} |
| 244 |
# else { |
| 245 |
# $self->DEBUG("defined map type for $type: $template\n"); |
| 246 |
# } |
| 247 |
$self->DEBUG("printing view '", $template || '', "', $item\n") if $DEBUG; |
| 248 |
$output .= $self->view($template, $item) |
| 249 |
if $template; |
| 250 |
} |
| 251 |
return $output; |
| 252 |
} |
| 253 |
|
| 254 |
|
| 255 |
#------------------------------------------------------------------------ |
| 256 |
# view($template, $item, \%vars) |
| 257 |
# |
| 258 |
# Wrapper around include() which expects a template name, $template, |
| 259 |
# followed by a data item, $item, and optionally, a further hash array |
| 260 |
# of template variables. The $item is added as an entry to the $vars |
| 261 |
# hash (which is created empty if not passed as an argument) under the |
| 262 |
# name specified by the internal 'item' member, which is appropriately |
| 263 |
# 'item' by default. Thus an external object present() method can |
| 264 |
# callback against this object method, simply passing a data item to |
| 265 |
# be displayed. The external object doesn't have to know what the |
| 266 |
# view expects the item to be called in the $vars hash. |
| 267 |
#------------------------------------------------------------------------ |
| 268 |
|
| 269 |
sub view { |
| 270 |
my ($self, $template, $item) = splice(@_, 0, 3); |
| 271 |
my $vars = ref $_[0] eq 'HASH' ? shift : { @_ }; |
| 272 |
$vars->{ $self->{ item } } = $item if defined $item; |
| 273 |
$self->include($template, $vars); |
| 274 |
} |
| 275 |
|
| 276 |
|
| 277 |
#------------------------------------------------------------------------ |
| 278 |
# include($template, \%vars) |
| 279 |
# |
| 280 |
# INCLUDE a template, $template, mapped according to the current prefix, |
| 281 |
# suffix, default, etc., where $vars is an optional hash reference |
| 282 |
# containing template variable definitions. If the template isn't found |
| 283 |
# then the method will default to any 'notfound' template, if defined |
| 284 |
# as an internal item. |
| 285 |
#------------------------------------------------------------------------ |
| 286 |
|
| 287 |
sub include { |
| 288 |
my ($self, $template, $vars) = @_; |
| 289 |
my $context = $self->{ _CONTEXT }; |
| 290 |
|
| 291 |
$template = $self->template($template); |
| 292 |
|
| 293 |
$vars = { } unless ref $vars eq 'HASH'; |
| 294 |
$vars->{ view } ||= $self; |
| 295 |
|
| 296 |
$context->include( $template, $vars ); |
| 297 |
|
| 298 |
# DEBUGGING |
| 299 |
# my $out = $context->include( $template, $vars ); |
| 300 |
# print STDERR "VIEW return [$out]\n"; |
| 301 |
# return $out; |
| 302 |
} |
| 303 |
|
| 304 |
|
| 305 |
#------------------------------------------------------------------------ |
| 306 |
# template($template) |
| 307 |
# |
| 308 |
# Returns a compiled template for the specified template name, according |
| 309 |
# to the current configuration parameters. |
| 310 |
#------------------------------------------------------------------------ |
| 311 |
|
| 312 |
sub template { |
| 313 |
my ($self, $name) = @_; |
| 314 |
my $context = $self->{ _CONTEXT }; |
| 315 |
return $context->throw(Template::Constants::ERROR_VIEW, |
| 316 |
"no view template specified") |
| 317 |
unless $name; |
| 318 |
|
| 319 |
my $notfound = $self->{ notfound }; |
| 320 |
my $base = $self->{ base }; |
| 321 |
my ($template, $block, $error); |
| 322 |
|
| 323 |
return $block |
| 324 |
if ($block = $self->{ _BLOCKS }->{ $name }); |
| 325 |
|
| 326 |
# try the named template |
| 327 |
$template = $self->template_name($name); |
| 328 |
$self->DEBUG("looking for $template\n") if $DEBUG; |
| 329 |
eval { $template = $context->template($template) }; |
| 330 |
|
| 331 |
# try asking the base view if not found |
| 332 |
if (($error = $@) && $base) { |
| 333 |
$self->DEBUG("asking base for $name\n") if $DEBUG; |
| 334 |
eval { $template = $base->template($name) }; |
| 335 |
} |
| 336 |
|
| 337 |
# try the 'notfound' template (if defined) if that failed |
| 338 |
if (($error = $@) && $notfound) { |
| 339 |
unless ($template = $self->{ _BLOCKS }->{ $notfound }) { |
| 340 |
$notfound = $self->template_name($notfound); |
| 341 |
$self->DEBUG("not found, looking for $notfound\n") if $DEBUG; |
| 342 |
eval { $template = $context->template($notfound) }; |
| 343 |
|
| 344 |
return $context->throw(Template::Constants::ERROR_VIEW, $error) |
| 345 |
if $@; # return first error |
| 346 |
} |
| 347 |
} |
| 348 |
elsif ($error) { |
| 349 |
$self->DEBUG("no 'notfound'\n") |
| 350 |
if $DEBUG; |
| 351 |
return $context->throw(Template::Constants::ERROR_VIEW, $error); |
| 352 |
} |
| 353 |
return $template; |
| 354 |
} |
| 355 |
|
| 356 |
|
| 357 |
#------------------------------------------------------------------------ |
| 358 |
# template_name($template) |
| 359 |
# |
| 360 |
# Returns the name of the specified template with any appropriate prefix |
| 361 |
# and/or suffix added. |
| 362 |
#------------------------------------------------------------------------ |
| 363 |
|
| 364 |
sub template_name { |
| 365 |
my ($self, $template) = @_; |
| 366 |
$template = $self->{ prefix } . $template . $self->{ suffix } |
| 367 |
if $template; |
| 368 |
|
| 369 |
$self->DEBUG("template name: $template\n") if $DEBUG; |
| 370 |
return $template; |
| 371 |
} |
| 372 |
|
| 373 |
|
| 374 |
#------------------------------------------------------------------------ |
| 375 |
# default($val) |
| 376 |
# |
| 377 |
# Special case accessor to retrieve/update 'default' as an alias for |
| 378 |
# '$map->{ default }'. |
| 379 |
#------------------------------------------------------------------------ |
| 380 |
|
| 381 |
sub default { |
| 382 |
my $self = shift; |
| 383 |
return @_ ? ($self->{ map }->{ default } = shift) |
| 384 |
: $self->{ map }->{ default }; |
| 385 |
} |
| 386 |
|
| 387 |
|
| 388 |
#------------------------------------------------------------------------ |
| 389 |
# AUTOLOAD |
| 390 |
# |
| 391 |
|
| 392 |
# Returns/updates public internal data items (i.e. not prefixed '_' or |
| 393 |
# '.') or presents a view if the method matches the view_prefix item, |
| 394 |
# e.g. view_foo(...) => view('foo', ...). Similarly, the |
| 395 |
# include_prefix is used, if defined, to map include_foo(...) to |
| 396 |
# include('foo', ...). If that fails then the entire method name will |
| 397 |
# be used as the name of a template to include iff the include_named |
| 398 |
# parameter is set (default: 1). Last attempt is to match the entire |
| 399 |
# method name to a view() call, iff view_naked is set. Otherwise, a |
| 400 |
# 'view' exception is raised reporting the error "no such view member: |
| 401 |
# $method". |
| 402 |
#------------------------------------------------------------------------ |
| 403 |
|
| 404 |
sub AUTOLOAD { |
| 405 |
my $self = shift; |
| 406 |
my $item = $AUTOLOAD; |
| 407 |
$item =~ s/.*:://; |
| 408 |
return if $item eq 'DESTROY'; |
| 409 |
|
| 410 |
if ($item =~ /^[\._]/) { |
| 411 |
return $self->{ _CONTEXT }->throw(Template::Constants::ERROR_VIEW, |
| 412 |
"attempt to view private member: $item"); |
| 413 |
} |
| 414 |
elsif (exists $self->{ $item }) { |
| 415 |
# update existing config item (e.g. 'prefix') if unsealed |
| 416 |
return $self->{ _CONTEXT }->throw(Template::Constants::ERROR_VIEW, |
| 417 |
"cannot update config item in sealed view: $item") |
| 418 |
if @_ && $self->{ SEALED }; |
| 419 |
$self->DEBUG("accessing item: $item\n") if $DEBUG; |
| 420 |
return @_ ? ($self->{ $item } = shift) : $self->{ $item }; |
| 421 |
} |
| 422 |
elsif (exists $self->{ data }->{ $item }) { |
| 423 |
# get/update existing data item (must be unsealed to update) |
| 424 |
if (@_ && $self->{ SEALED }) { |
| 425 |
return $self->{ _CONTEXT }->throw(Template::Constants::ERROR_VIEW, |
| 426 |
"cannot update item in sealed view: $item") |
| 427 |
unless $self->{ silent }; |
| 428 |
# ignore args if silent |
| 429 |
@_ = (); |
| 430 |
} |
| 431 |
$self->DEBUG(@_ ? "updating data item: $item <= $_[0]\n" |
| 432 |
: "returning data item: $item\n") if $DEBUG; |
| 433 |
return @_ ? ($self->{ data }->{ $item } = shift) |
| 434 |
: $self->{ data }->{ $item }; |
| 435 |
} |
| 436 |
elsif (@_ && ! $self->{ SEALED }) { |
| 437 |
# set data item if unsealed |
| 438 |
$self->DEBUG("setting unsealed data: $item => @_\n") if $DEBUG; |
| 439 |
$self->{ data }->{ $item } = shift; |
| 440 |
} |
| 441 |
elsif ($item =~ s/^$self->{ view_prefix }//) { |
| 442 |
$self->DEBUG("returning view($item)\n") if $DEBUG; |
| 443 |
return $self->view($item, @_); |
| 444 |
} |
| 445 |
elsif ($item =~ s/^$self->{ include_prefix }//) { |
| 446 |
$self->DEBUG("returning include($item)\n") if $DEBUG; |
| 447 |
return $self->include($item, @_); |
| 448 |
} |
| 449 |
elsif ($self->{ include_naked }) { |
| 450 |
$self->DEBUG("returning naked include($item)\n") if $DEBUG; |
| 451 |
return $self->include($item, @_); |
| 452 |
} |
| 453 |
elsif ($self->{ view_naked }) { |
| 454 |
$self->DEBUG("returning naked view($item)\n") if $DEBUG; |
| 455 |
return $self->view($item, @_); |
| 456 |
} |
| 457 |
else { |
| 458 |
return $self->{ _CONTEXT }->throw(Template::Constants::ERROR_VIEW, |
| 459 |
"no such view member: $item"); |
| 460 |
} |
| 461 |
} |
| 462 |
|
| 463 |
|
| 464 |
1; |
| 465 |
|
| 466 |
|
| 467 |
__END__ |
| 468 |
|
| 469 |
=head1 NAME |
| 470 |
|
| 471 |
Template::View - customised view of a template processing context |
| 472 |
|
| 473 |
=head1 SYNOPSIS |
| 474 |
|
| 475 |
# define a view |
| 476 |
[% VIEW view |
| 477 |
# some standard args |
| 478 |
prefix => 'my_', |
| 479 |
suffix => '.tt2', |
| 480 |
notfound => 'no_such_file' |
| 481 |
... |
| 482 |
|
| 483 |
# any other data |
| 484 |
title => 'My View title' |
| 485 |
other_item => 'Joe Random Data' |
| 486 |
... |
| 487 |
%] |
| 488 |
# add new data definitions, via 'my' self reference |
| 489 |
[% my.author = "$abw.name <$abw.email>" %] |
| 490 |
[% my.copy = "© Copyright 2000 $my.author" %] |
| 491 |
|
| 492 |
# define a local block |
| 493 |
[% BLOCK header %] |
| 494 |
This is the header block, title: [% title or my.title %] |
| 495 |
[% END %] |
| 496 |
|
| 497 |
[% END %] |
| 498 |
|
| 499 |
# access data items for view |
| 500 |
[% view.title %] |
| 501 |
[% view.other_item %] |
| 502 |
|
| 503 |
# access blocks directly ('include_naked' option, set by default) |
| 504 |
[% view.header %] |
| 505 |
[% view.header(title => 'New Title') %] |
| 506 |
|
| 507 |
# non-local templates have prefix/suffix attached |
| 508 |
[% view.footer %] # => [% INCLUDE my_footer.tt2 %] |
| 509 |
|
| 510 |
# more verbose form of block access |
| 511 |
[% view.include( 'header', title => 'The Header Title' ) %] |
| 512 |
[% view.include_header( title => 'The Header Title' ) %] |
| 513 |
|
| 514 |
# very short form of above ('include_naked' option, set by default) |
| 515 |
[% view.header( title => 'The Header Title' ) %] |
| 516 |
|
| 517 |
# non-local templates have prefix/suffix attached |
| 518 |
[% view.footer %] # => [% INCLUDE my_footer.tt2 %] |
| 519 |
|
| 520 |
# fallback on the 'notfound' template ('my_no_such_file.tt2') |
| 521 |
# if template not found |
| 522 |
[% view.include('missing') %] |
| 523 |
[% view.include_missing %] |
| 524 |
[% view.missing %] |
| 525 |
|
| 526 |
# print() includes a template relevant to argument type |
| 527 |
[% view.print("some text") %] # type=TEXT, template='text' |
| 528 |
|
| 529 |
[% BLOCK my_text.tt2 %] # 'text' with prefix/suffix |
| 530 |
Text: [% item %] |
| 531 |
[% END %] |
| 532 |
|
| 533 |
# now print() a hash ref, mapped to 'hash' template |
| 534 |
[% view.print(some_hash_ref) %] # type=HASH, template='hash' |
| 535 |
|
| 536 |
[% BLOCK my_hash.tt2 %] # 'hash' with prefix/suffix |
| 537 |
hash keys: [% item.keys.sort.join(', ') |
| 538 |
[% END %] |
| 539 |
|
| 540 |
# now print() a list ref, mapped to 'list' template |
| 541 |
[% view.print(my_list_ref) %] # type=ARRAY, template='list' |
| 542 |
|
| 543 |
[% BLOCK my_list.tt2 %] # 'list' with prefix/suffix |
| 544 |
list: [% item.join(', ') %] |
| 545 |
[% END %] |
| 546 |
|
| 547 |
# print() maps 'My::Object' to 'My_Object' |
| 548 |
[% view.print(myobj) %] |
| 549 |
|
| 550 |
[% BLOCK my_My_Object.tt2 %] |
| 551 |
[% item.this %], [% item.that %] |
| 552 |
[% END %] |
| 553 |
|
| 554 |
# update mapping table |
| 555 |
[% view.map.ARRAY = 'my_list_template' %] |
| 556 |
[% view.map.TEXT = 'my_text_block' %] |
| 557 |
|
| 558 |
|
| 559 |
# change prefix, suffix, item name, etc. |
| 560 |
[% view.prefix = 'your_' %] |
| 561 |
[% view.default = 'anyobj' %] |
| 562 |
... |
| 563 |
|
| 564 |
=head1 DESCRIPTION |
| 565 |
|
| 566 |
TODO |
| 567 |
|
| 568 |
=head1 METHODS |
| 569 |
|
| 570 |
=head2 new($context, \%config) |
| 571 |
|
| 572 |
Creates a new Template::View presenting a custom view of the specified |
| 573 |
$context object. |
| 574 |
|
| 575 |
A reference to a hash array of configuration options may be passed as the |
| 576 |
second argument. |
| 577 |
|
| 578 |
=over 4 |
| 579 |
|
| 580 |
=item prefix |
| 581 |
|
| 582 |
Prefix added to all template names. |
| 583 |
|
| 584 |
[% USE view(prefix => 'my_') %] |
| 585 |
[% view.view('foo', a => 20) %] # => my_foo |
| 586 |
|
| 587 |
=item suffix |
| 588 |
|
| 589 |
Suffix added to all template names. |
| 590 |
|
| 591 |
[% USE view(suffix => '.tt2') %] |
| 592 |
[% view.view('foo', a => 20) %] # => foo.tt2 |
| 593 |
|
| 594 |
=item map |
| 595 |
|
| 596 |
Hash array mapping reference types to template names. The print() |
| 597 |
method uses this to determine which template to use to present any |
| 598 |
particular item. The TEXT, HASH and ARRAY items default to 'test', |
| 599 |
'hash' and 'list' appropriately. |
| 600 |
|
| 601 |
[% USE view(map => { ARRAY => 'my_list', |
| 602 |
HASH => 'your_hash', |
| 603 |
My::Foo => 'my_foo', } ) %] |
| 604 |
|
| 605 |
[% view.print(some_text) %] # => text |
| 606 |
[% view.print(a_list) %] # => my_list |
| 607 |
[% view.print(a_hash) %] # => your_hash |
| 608 |
[% view.print(a_foo) %] # => my_foo |
| 609 |
|
| 610 |
[% BLOCK text %] |
| 611 |
Text: [% item %] |
| 612 |
[% END %] |
| 613 |
|
| 614 |
[% BLOCK my_list %] |
| 615 |
list: [% item.join(', ') %] |
| 616 |
[% END %] |
| 617 |
|
| 618 |
[% BLOCK your_hash %] |
| 619 |
hash keys: [% item.keys.sort.join(', ') |
| 620 |
[% END %] |
| 621 |
|
| 622 |
[% BLOCK my_foo %] |
| 623 |
Foo: [% item.this %], [% item.that %] |
| 624 |
[% END %] |
| 625 |
|
| 626 |
=item method |
| 627 |
|
| 628 |
Name of a method which objects passed to print() may provide for presenting |
| 629 |
themselves to the view. If a specific map entry can't be found for an |
| 630 |
object reference and it supports the method (default: 'present') then |
| 631 |
the method will be called, passing the view as an argument. The object |
| 632 |
can then make callbacks against the view to present itself. |
| 633 |
|
| 634 |
package Foo; |
| 635 |
|
| 636 |
sub present { |
| 637 |
my ($self, $view) = @_; |
| 638 |
return "a regular view of a Foo\n"; |
| 639 |
} |
| 640 |
|
| 641 |
sub debug { |
| 642 |
my ($self, $view) = @_; |
| 643 |
return "a debug view of a Foo\n"; |
| 644 |
} |
| 645 |
|
| 646 |
In a template: |
| 647 |
|
| 648 |
[% USE view %] |
| 649 |
[% view.print(my_foo_object) %] # a regular view of a Foo |
| 650 |
|
| 651 |
[% USE view(method => 'debug') %] |
| 652 |
[% view.print(my_foo_object) %] # a debug view of a Foo |
| 653 |
|
| 654 |
=item default |
| 655 |
|
| 656 |
Default template to use if no specific map entry is found for an item. |
| 657 |
|
| 658 |
[% USE view(default => 'my_object') %] |
| 659 |
|
| 660 |
[% view.print(objref) %] # => my_object |
| 661 |
|
| 662 |
If no map entry or default is provided then the view will attempt to |
| 663 |
construct a template name from the object class, substituting any |
| 664 |
sequence of non-word characters to single underscores, e.g. |
| 665 |
|
| 666 |
# 'fubar' is an object of class Foo::Bar |
| 667 |
[% view.print(fubar) %] # => Foo_Bar |
| 668 |
|
| 669 |
Any current prefix and suffix will be added to both the default template |
| 670 |
name and any name constructed from the object class. |
| 671 |
|
| 672 |
=item notfound |
| 673 |
|
| 674 |
Fallback template to use if any other isn't found. |
| 675 |
|
| 676 |
=item item |
| 677 |
|
| 678 |
Name of the template variable to which the print() method assigns the current |
| 679 |
item. Defaults to 'item'. |
| 680 |
|
| 681 |
[% USE view %] |
| 682 |
[% BLOCK list %] |
| 683 |
[% item.join(', ') %] |
| 684 |
[% END %] |
| 685 |
[% view.print(a_list) %] |
| 686 |
|
| 687 |
[% USE view(item => 'thing') %] |
| 688 |
[% BLOCK list %] |
| 689 |
[% thing.join(', ') %] |
| 690 |
[% END %] |
| 691 |
[% view.print(a_list) %] |
| 692 |
|
| 693 |
=item view_prefix |
| 694 |
|
| 695 |
Prefix of methods which should be mapped to view() by AUTOLOAD. Defaults |
| 696 |
to 'view_'. |
| 697 |
|
| 698 |
[% USE view %] |
| 699 |
[% view.view_header() %] # => view('header') |
| 700 |
|
| 701 |
[% USE view(view_prefix => 'show_me_the_' %] |
| 702 |
[% view.show_me_the_header() %] # => view('header') |
| 703 |
|
| 704 |
=item view_naked |
| 705 |
|
| 706 |
Flag to indcate if any attempt should be made to map method names to |
| 707 |
template names where they don't match the view_prefix. Defaults to 0. |
| 708 |
|
| 709 |
[% USE view(view_naked => 1) %] |
| 710 |
|
| 711 |
[% view.header() %] # => view('header') |
| 712 |
|
| 713 |
=back |
| 714 |
|
| 715 |
=head2 print( $obj1, $obj2, ... \%config) |
| 716 |
|
| 717 |
TODO |
| 718 |
|
| 719 |
=head2 view( $template, \%vars, \%config ); |
| 720 |
|
| 721 |
TODO |
| 722 |
|
| 723 |
=head1 AUTHOR |
| 724 |
|
| 725 |
Andy Wardley E<lt>[email protected]<gt> L<http://wardley.org/> |
| 726 |
|
| 727 |
=head1 COPYRIGHT |
| 728 |
|
| 729 |
Copyright (C) 2000-2007 Andy Wardley. All Rights Reserved. |
| 730 |
|
| 731 |
This module is free software; you can redistribute it and/or |
| 732 |
modify it under the same terms as Perl itself. |
| 733 |
|
| 734 |
=head1 SEE ALSO |
| 735 |
|
| 736 |
L<Template::Plugin> |
| 737 |
|
| 738 |
=cut |
| 739 |
|
| 740 |
|
| 741 |
|
| 742 |
|
| 743 |
|