---
name: "Template::View"
section: "3pm"
platform: "linux"
package: "perl-template-toolkit"
version: "3.106-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/Template::View"
---

# Template::View(3pm)

customised view of a template processing context

## NAME

Template::View - customised view of a template processing context

## SYNOPSIS

```
    # define a view
    [% VIEW view
            # some standard args
            prefix        => 'my_',
            suffix        => '.tt2',
            notfound      => 'no_such_file'
            ...
            # any other data
            title         => 'My View title'
            other_item    => 'Joe Random Data'
            ...
    %]
       # add new data definitions, via 'my' 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 ('include_naked' option, set by default)
    [% view.header %]
    [% view.header(title => 'New Title') %]
    # non-local templates have prefix/suffix attached
    [% view.footer %]           # => [% INCLUDE my_footer.tt2 %]
    # more verbose form of block access
    [% view.include( 'header', title => 'The Header Title' ) %]
    [% view.include_header( title => 'The Header Title' ) %]
    # very short form of above ('include_naked' option, set by default)
    [% view.header( title => 'The Header Title' ) %]
    # non-local templates have prefix/suffix attached
    [% view.footer %]           # => [% INCLUDE my_footer.tt2 %]
    # fallback on the 'notfound' template ('my_no_such_file.tt2')
    # if template not found
    [% view.include('missing') %]
    [% view.include_missing %]
    [% view.missing %]
    # print() includes a template relevant to argument type
    [% view.print("some text") %]     # type=TEXT, template='text'
    [% BLOCK my_text.tt2 %]           # 'text' with prefix/suffix
       Text: [% item %]
    [% END %]
    # now print() a hash ref, mapped to 'hash' template
    [% view.print(some_hash_ref) %]   # type=HASH, template='hash'
    [% BLOCK my_hash.tt2 %]           # 'hash' with prefix/suffix
       hash keys: [% item.keys.sort.join(', ')
    [% END %]
    # now print() a list ref, mapped to 'list' template
    [% view.print(my_list_ref) %]     # type=ARRAY, template='list'
    [% BLOCK my_list.tt2 %]           # 'list' with prefix/suffix
       list: [% item.join(', ') %]
    [% END %]
    # print() maps 'My::Object' to 'My_Object'
    [% view.print(myobj) %]
    [% BLOCK my_My_Object.tt2 %]
       [% item.this %], [% item.that %]
    [% END %]
    # update mapping table
    [% view.map.ARRAY = 'my_list_template' %]
    [% view.map.TEXT  = 'my_text_block'    %]
    # change prefix, suffix, item name, etc.
    [% view.prefix = 'your_' %]
    [% view.default = 'anyobj' %]
    ...
```

## DESCRIPTION

TODO

## METHODS

### new($context, \\%config)

Creates a new Template::View presenting a custom view of the specified `$context` object.

A reference to a hash array of configuration options may be passed as the second argument.

- prefix

  Prefix added to all template names.

  ```
      [% USE view(prefix => 'my_') %]
      [% view.view('foo', a => 20) %]     # => my_foo
  ```

- suffix

  Suffix added to all template names.

  ```
      [% USE view(suffix => '.tt2') %]
      [% view.view('foo', a => 20) %]     # => foo.tt2
  ```

- map

  Hash array mapping reference types to template names.  The **print()** 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.

  ```
      [% USE view(map => { ARRAY   => 'my_list',
                           HASH    => 'your_hash',
                           My::Foo => 'my_foo', } ) %]
      [% 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(', ') %]
      [% END %]
      [% BLOCK your_hash %]
         hash keys: [% item.keys.sort.join(', ')
      [% END %]
      [% BLOCK my_foo %]
         Foo: [% item.this %], [% item.that %]
      [% END %]
  ```

- method

  Name of a method which objects passed to **print()** 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.

  ```
      package Foo;
      sub present {
          my ($self, $view) = @_;
          return "a regular view of a Foo\n";
      }
      sub debug {
          my ($self, $view) = @_;
          return "a debug view of a Foo\n";
      }
  ```

  In a template:

  ```
      [% USE view %]
      [% view.print(my_foo_object) %]     # a regular view of a Foo
      [% USE view(method => 'debug') %]
      [% view.print(my_foo_object) %]     # a debug view of a Foo
  ```

- default

  Default template to use if no specific map entry is found for an item.

  ```
      [% USE view(default => 'my_object') %]
      [% view.print(objref) %]            # => my_object
  ```

  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.

  ```
      # 'fubar' is an object of class Foo::Bar
      [% view.print(fubar) %]             # => Foo_Bar
  ```

  Any current prefix and suffix will be added to both the default template name and any name constructed from the object class.

- notfound

  Fallback template to use if any other isn't found.

- item

  Name of the template variable to which the **print()** method assigns the current item.  Defaults to 'item'.

  ```
      [% USE view %]
      [% BLOCK list %]
         [% item.join(', ') %]
      [% END %]
      [% view.print(a_list) %]
      [% USE view(item => 'thing') %]
      [% BLOCK list %]
         [% thing.join(', ') %]
      [% END %]
      [% view.print(a_list) %]
  ```

- view\_prefix

  Prefix of methods which should be mapped to **view()** by AUTOLOAD.  Defaults to 'view\_'.

  ```
      [% USE view %]
      [% view.view_header() %]                    # => view('header')
      [% USE view(view_prefix => 'show_me_the_' %]
      [% view.show_me_the_header() %]             # => view('header')
  ```

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

  ```
      [% USE view(view_naked => 1) %]
      [% view.header() %]                 # => view('header')
  ```

### print( $obj1, $obj2, ... \\%config)

TODO

### view( $template, \\%vars, \\%config );

TODO

## AUTHOR

Andy Wardley \<abw@wardley.org\> \<http://wardley.org/\>

## COPYRIGHT

Copyright (C) 2000-2022 Andy Wardley.  All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

## SEE ALSO

Template::Plugin