.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Template::View 3"
.TH Template::View 3 2023-07-25 "perl v5.38.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Template::View \- customised view of a template processing context
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 7
\&    # define a view
\&    [% VIEW view
\&            # some standard args
\&            prefix        => \*(Aqmy_\*(Aq,
\&            suffix        => \*(Aq.tt2\*(Aq,
\&            notfound      => \*(Aqno_such_file\*(Aq
\&            ...
\&
\&            # any other data
\&            title         => \*(AqMy View title\*(Aq
\&            other_item    => \*(AqJoe Random Data\*(Aq
\&            ...
\&    %]
\&       # add new data definitions, via \*(Aqmy\*(Aq self reference
\&       [% my.author = "$abw.name <$abw.email>" %]
\&       [% my.copy   = "&copy; Copyright 2000 $my.author" %]
\&
\&       # define a local block
\&       [% BLOCK header %]
\&       This is the header block, title: [% title or my.title %]
\&       [% END %]
\&
\&    [% END %]
\&
\&    # access data items for view
\&    [% view.title %]
\&    [% view.other_item %]
\&
\&    # access blocks directly (\*(Aqinclude_naked\*(Aq option, set by default)
\&    [% view.header %]
\&    [% view.header(title => \*(AqNew Title\*(Aq) %]
\&
\&    # non\-local templates have prefix/suffix attached
\&    [% view.footer %]           # => [% INCLUDE my_footer.tt2 %]
\&
\&    # more verbose form of block access
\&    [% view.include( \*(Aqheader\*(Aq, title => \*(AqThe Header Title\*(Aq ) %]
\&    [% view.include_header( title => \*(AqThe Header Title\*(Aq ) %]
\&
\&    # very short form of above (\*(Aqinclude_naked\*(Aq option, set by default)
\&    [% view.header( title => \*(AqThe Header Title\*(Aq ) %]
\&
\&    # non\-local templates have prefix/suffix attached
\&    [% view.footer %]           # => [% INCLUDE my_footer.tt2 %]
\&
\&    # fallback on the \*(Aqnotfound\*(Aq template (\*(Aqmy_no_such_file.tt2\*(Aq)
\&    # if template not found
\&    [% view.include(\*(Aqmissing\*(Aq) %]
\&    [% view.include_missing %]
\&    [% view.missing %]
\&
\&    # print() includes a template relevant to argument type
\&    [% view.print("some text") %]     # type=TEXT, template=\*(Aqtext\*(Aq
\&
\&    [% BLOCK my_text.tt2 %]           # \*(Aqtext\*(Aq with prefix/suffix
\&       Text: [% item %]
\&    [% END %]
\&
\&    # now print() a hash ref, mapped to \*(Aqhash\*(Aq template
\&    [% view.print(some_hash_ref) %]   # type=HASH, template=\*(Aqhash\*(Aq
\&
\&    [% BLOCK my_hash.tt2 %]           # \*(Aqhash\*(Aq with prefix/suffix
\&       hash keys: [% item.keys.sort.join(\*(Aq, \*(Aq)
\&    [% END %]
\&
\&    # now print() a list ref, mapped to \*(Aqlist\*(Aq template
\&    [% view.print(my_list_ref) %]     # type=ARRAY, template=\*(Aqlist\*(Aq
\&
\&    [% BLOCK my_list.tt2 %]           # \*(Aqlist\*(Aq with prefix/suffix
\&       list: [% item.join(\*(Aq, \*(Aq) %]
\&    [% END %]
\&
\&    # print() maps \*(AqMy::Object\*(Aq to \*(AqMy_Object\*(Aq
\&    [% view.print(myobj) %]
\&
\&    [% BLOCK my_My_Object.tt2 %]
\&       [% item.this %], [% item.that %]
\&    [% END %]
\&
\&    # update mapping table
\&    [% view.map.ARRAY = \*(Aqmy_list_template\*(Aq %]
\&    [% view.map.TEXT  = \*(Aqmy_text_block\*(Aq    %]
\&
\&
\&    # change prefix, suffix, item name, etc.
\&    [% view.prefix = \*(Aqyour_\*(Aq %]
\&    [% view.default = \*(Aqanyobj\*(Aq %]
\&    ...
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
TODO
.SH METHODS
.IX Header "METHODS"
.SS "new($context, \e%config)"
.IX Subsection "new($context, %config)"
Creates a new Template::View presenting a custom view of the specified
\&\f(CW$context\fR object.
.PP
A reference to a hash array of configuration options may be passed as the
second argument.
.IP prefix 4
.IX Item "prefix"
Prefix added to all template names.
.Sp
.Vb 2
\&    [% USE view(prefix => \*(Aqmy_\*(Aq) %]
\&    [% view.view(\*(Aqfoo\*(Aq, a => 20) %]     # => my_foo
.Ve
.IP suffix 4
.IX Item "suffix"
Suffix added to all template names.
.Sp
.Vb 2
\&    [% USE view(suffix => \*(Aq.tt2\*(Aq) %]
\&    [% view.view(\*(Aqfoo\*(Aq, a => 20) %]     # => foo.tt2
.Ve
.IP map 4
.IX Item "map"
Hash array mapping reference types to template names.  The \fBprint()\fR
method uses this to determine which template to use to present any
particular item.  The TEXT, HASH and ARRAY items default to 'test',
\&'hash' and 'list' appropriately.
.Sp
.Vb 3
\&    [% USE view(map => { ARRAY   => \*(Aqmy_list\*(Aq,
\&                         HASH    => \*(Aqyour_hash\*(Aq,
\&                         My::Foo => \*(Aqmy_foo\*(Aq, } ) %]
\&
\&    [% view.print(some_text) %]         # => text
\&    [% view.print(a_list) %]            # => my_list
\&    [% view.print(a_hash) %]            # => your_hash
\&    [% view.print(a_foo) %]             # => my_foo
\&
\&    [% BLOCK text %]
\&       Text: [% item %]
\&    [% END %]
\&
\&    [% BLOCK my_list %]
\&       list: [% item.join(\*(Aq, \*(Aq) %]
\&    [% END %]
\&
\&    [% BLOCK your_hash %]
\&       hash keys: [% item.keys.sort.join(\*(Aq, \*(Aq)
\&    [% END %]
\&
\&    [% BLOCK my_foo %]
\&       Foo: [% item.this %], [% item.that %]
\&    [% END %]
.Ve
.IP method 4
.IX Item "method"
Name of a method which objects passed to \fBprint()\fR may provide for presenting
themselves to the view.  If a specific map entry can't be found for an
object reference and it supports the method (default: 'present') then
the method will be called, passing the view as an argument.  The object
can then make callbacks against the view to present itself.
.Sp
.Vb 1
\&    package Foo;
\&
\&    sub present {
\&        my ($self, $view) = @_;
\&        return "a regular view of a Foo\en";
\&    }
\&
\&    sub debug {
\&        my ($self, $view) = @_;
\&        return "a debug view of a Foo\en";
\&    }
.Ve
.Sp
In a template:
.Sp
.Vb 2
\&    [% USE view %]
\&    [% view.print(my_foo_object) %]     # a regular view of a Foo
\&
\&    [% USE view(method => \*(Aqdebug\*(Aq) %]
\&    [% view.print(my_foo_object) %]     # a debug view of a Foo
.Ve
.IP default 4
.IX Item "default"
Default template to use if no specific map entry is found for an item.
.Sp
.Vb 1
\&    [% USE view(default => \*(Aqmy_object\*(Aq) %]
\&
\&    [% view.print(objref) %]            # => my_object
.Ve
.Sp
If no map entry or default is provided then the view will attempt to
construct a template name from the object class, substituting any
sequence of non-word characters to single underscores, e.g.
.Sp
.Vb 2
\&    # \*(Aqfubar\*(Aq is an object of class Foo::Bar
\&    [% view.print(fubar) %]             # => Foo_Bar
.Ve
.Sp
Any current prefix and suffix will be added to both the default template
name and any name constructed from the object class.
.IP notfound 4
.IX Item "notfound"
Fallback template to use if any other isn't found.
.IP item 4
.IX Item "item"
Name of the template variable to which the \fBprint()\fR method assigns the current
item.  Defaults to 'item'.
.Sp
.Vb 5
\&    [% USE view %]
\&    [% BLOCK list %]
\&       [% item.join(\*(Aq, \*(Aq) %]
\&    [% END %]
\&    [% view.print(a_list) %]
\&
\&    [% USE view(item => \*(Aqthing\*(Aq) %]
\&    [% BLOCK list %]
\&       [% thing.join(\*(Aq, \*(Aq) %]
\&    [% END %]
\&    [% view.print(a_list) %]
.Ve
.IP view_prefix 4
.IX Item "view_prefix"
Prefix of methods which should be mapped to \fBview()\fR by AUTOLOAD.  Defaults
to 'view_'.
.Sp
.Vb 2
\&    [% USE view %]
\&    [% view.view_header() %]                    # => view(\*(Aqheader\*(Aq)
\&
\&    [% USE view(view_prefix => \*(Aqshow_me_the_\*(Aq %]
\&    [% view.show_me_the_header() %]             # => view(\*(Aqheader\*(Aq)
.Ve
.IP view_naked 4
.IX Item "view_naked"
Flag to indicate if any attempt should be made to map method names to
template names where they don't match the view_prefix.  Defaults to 0.
.Sp
.Vb 1
\&    [% USE view(view_naked => 1) %]
\&
\&    [% view.header() %]                 # => view(\*(Aqheader\*(Aq)
.Ve
.ie n .SS "print( $obj1, $obj2, ... \e%config)"
.el .SS "print( \f(CW$obj1\fP, \f(CW$obj2\fP, ... \e%config)"
.IX Subsection "print( $obj1, $obj2, ... %config)"
TODO
.ie n .SS "view( $template, \e%vars, \e%config );"
.el .SS "view( \f(CW$template\fP, \e%vars, \e%config );"
.IX Subsection "view( $template, %vars, %config );"
TODO
.SH AUTHOR
.IX Header "AUTHOR"
Andy Wardley <abw@wardley.org> <http://wardley.org/>
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (C) 2000\-2022 Andy Wardley.  All Rights Reserved.
.PP
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Template::Plugin