local-lib5/man/man3/Template::Context.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Template::Context 3"
 132 .TH Template::Context 3 "2009-05-20" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Template::Context \- Runtime context in which templates are processed
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&    use Template::Context;
 139 .Ve
 140 .PP
 141 .Vb 3
 142 \&    # constructor
 143 \&    $context = Template::Context\->new(\e%config)
 144 \&        || die $Template::Context::ERROR;
 145 .Ve
 146 .PP
 147 .Vb 2
 148 \&    # fetch (load and compile) a template
 149 \&    $template = $context\->template($template_name);
 150 .Ve
 151 .PP
 152 .Vb 2
 153 \&    # fetch (load and instantiate) a plugin object
 154 \&    $plugin = $context\->plugin($name, \e@args);
 155 .Ve
 156 .PP
 157 .Vb 2
 158 \&    # fetch (return or create) a filter subroutine
 159 \&    $filter = $context\->filter($name, \e@args, $alias);
 160 .Ve
 161 .PP
 162 .Vb 3
 163 \&    # process/include a template, errors are thrown via die()
 164 \&    $output = $context\->process($template, \e%vars);
 165 \&    $output = $context\->include($template, \e%vars);
 166 .Ve
 167 .PP
 168 .Vb 2
 169 \&    # raise an exception via die()
 170 \&    $context\->throw($error_type, $error_message, \e$output_buffer);
 171 .Ve
 172 .PP
 173 .Vb 2
 174 \&    # catch an exception, clean it up and fix output buffer
 175 \&    $exception = $context\->catch($exception, \e$output_buffer);
 176 .Ve
 177 .PP
 178 .Vb 3
 179 \&    # save/restore the stash to effect variable localisation
 180 \&    $new_stash = $context\->localise(\e%vars);
 181 \&    $old_stash = $context\->delocalise();
 182 .Ve
 183 .PP
 184 .Vb 3
 185 \&    # add new BLOCK or FILTER definitions
 186 \&    $context\->define_block($name, $block);
 187 \&    $context\->define_filter($name, \e&filtersub, $is_dynamic);
 188 .Ve
 189 .PP
 190 .Vb 2
 191 \&    # reset context, clearing any imported BLOCK definitions
 192 \&    $context\->reset();
 193 .Ve
 194 .PP
 195 .Vb 8
 196 \&    # methods for accessing internal items
 197 \&    $stash     = $context\->stash();
 198 \&    $tflag     = $context\->trim();
 199 \&    $epflag    = $context\->eval_perl();
 200 \&    $providers = $context\->templates();
 201 \&    $providers = $context\->plugins();
 202 \&    $providers = $context\->filters();
 203 \&    ...
 204 .Ve
 205 .SH "DESCRIPTION"
 206 .IX Header "DESCRIPTION"
 207 The \f(CW\*(C`Template::Context\*(C'\fR module defines an object class for representing
 208 a runtime context in which templates are processed.  It provides an
 209 interface to the fundamental operations of the Template Toolkit
 210 processing engine through which compiled templates (i.e. Perl code
 211 constructed from the template source) can process templates, load
 212 plugins and filters, raise exceptions and so on.
 213 .PP
 214 A default \f(CW\*(C`Template::Context\*(C'\fR object is created by the Template module.
 215 Any \f(CW\*(C`Template::Context\*(C'\fR options may be passed to the Template
 216 \&\fInew()\fR constructor method and will be forwarded to the
 217 \&\f(CW\*(C`Template::Context\*(C'\fR constructor.
 218 .PP
 219 .Vb 1
 220 \&    use Template;
 221 .Ve
 222 .PP
 223 .Vb 8
 224 \&    my $template = Template\->new({
 225 \&        TRIM      => 1,
 226 \&        EVAL_PERL => 1,
 227 \&        BLOCKS    => {
 228 \&            header => 'This is the header',
 229 \&            footer => 'This is the footer',
 230 \&        },
 231 \&    });
 232 .Ve
 233 .PP
 234 Similarly, the \f(CW\*(C`Template::Context\*(C'\fR constructor will forward all configuration
 235 parameters onto other default objects (e.g. Template::Provider,
 236 Template::Plugins, Template::Filters, etc.) that it may need to
 237 instantiate.
 238 .PP
 239 .Vb 4
 240 \&    $context = Template::Context\->new({
 241 \&        INCLUDE_PATH => '/home/abw/templates', # provider option
 242 \&        TAG_STYLE    => 'html',                # parser option
 243 \&    });
 244 .Ve
 245 .PP
 246 A \f(CW\*(C`Template::Context\*(C'\fR object (or subclass) can be explicitly instantiated and
 247 passed to the Template \fInew()\fR constructor method as the
 248 \&\f(CW\*(C`CONTEXT\*(C'\fR configuration item.
 249 .PP
 250 .Vb 2
 251 \&    use Template;
 252 \&    use Template::Context;
 253 .Ve
 254 .PP
 255 .Vb 2
 256 \&    my $context  = Template::Context\->new({ TRIM => 1 });
 257 \&    my $template = Template\->new({ CONTEXT => $context });
 258 .Ve
 259 .PP
 260 The Template module uses the Template::Config
 261 \&\fIcontext()\fR factory method to create a default
 262 context object when required. The \f(CW$Template::Config::CONTEXT\fR package
 263 variable may be set to specify an alternate context module. This will be
 264 loaded automatically and its \fInew()\fR constructor method called by the
 265 \&\fIcontext()\fR factory method when a default context
 266 object is required.
 267 .PP
 268 .Vb 1
 269 \&    use Template;
 270 .Ve
 271 .PP
 272 .Vb 1
 273 \&    $Template::Config::CONTEXT = 'MyOrg::Template::Context';
 274 .Ve
 275 .PP
 276 .Vb 5
 277 \&    my $template = Template\->new({
 278 \&        EVAL_PERL   => 1,
 279 \&        EXTRA_MAGIC => 'red hot',  # your extra config items
 280 \&        ...
 281 \&    });
 282 .Ve
 283 .SH "METHODS"
 284 .IX Header "METHODS"
 285 .Sh "new(\e%params)"
 286 .IX Subsection "new(%params)"
 287 The \f(CW\*(C`new()\*(C'\fR constructor method is called to instantiate a
 288 \&\f(CW\*(C`Template::Context\*(C'\fR object. Configuration parameters may be specified as a
 289 \&\s-1HASH\s0 reference or as a list of \f(CW\*(C`name => value\*(C'\fR pairs.
 290 .PP
 291 .Vb 4
 292 \&    my $context = Template::Context\->new({
 293 \&        INCLUDE_PATH => 'header',
 294 \&        POST_PROCESS => 'footer',
 295 \&    });
 296 .Ve
 297 .PP
 298 .Vb 1
 299 \&    my $context = Template::Context\->new( EVAL_PERL => 1 );
 300 .Ve
 301 .PP
 302 The \f(CW\*(C`new()\*(C'\fR method returns a \f(CW\*(C`Template::Context\*(C'\fR object or \f(CW\*(C`undef\*(C'\fR on
 303 error. In the latter case, a relevant error message can be retrieved by the
 304 \&\fIerror()\fR class method or directly from the
 305 \&\f(CW$Template::Context::ERROR\fR package variable.
 306 .PP
 307 .Vb 2
 308 \&    my $context = Template::Context\->new(\e%config)
 309 \&        || die Template::Context\->error();
 310 .Ve
 311 .PP
 312 .Vb 2
 313 \&    my $context = Template::Context\->new(\e%config)
 314 \&        || die $Template::Context::ERROR;
 315 .Ve
 316 .PP
 317 The following configuration items may be specified.  Please see
 318 Template::Manual::Config for further details.
 319 .PP
 320 \fI\s-1VARIABLES\s0\fR
 321 .IX Subsection "VARIABLES"
 322 .PP
 323 The \s-1VARIABLES\s0 option can be used to
 324 specify a hash array of template variables.
 325 .PP
 326 .Vb 7
 327 \&    my $context = Template::Context\->new({
 328 \&        VARIABLES => {
 329 \&            title   => 'A Demo Page',
 330 \&            author  => 'Joe Random Hacker',
 331 \&            version => 3.14,
 332 \&        },
 333 \&    };
 334 .Ve
 335 .PP
 336 \fI\s-1BLOCKS\s0\fR
 337 .IX Subsection "BLOCKS"
 338 .PP
 339 The \s-1BLOCKS\s0 option can be used to pre-define
 340 a default set of template blocks.
 341 .PP
 342 .Vb 7
 343 \&    my $context = Template::Context\->new({
 344 \&        BLOCKS => {
 345 \&            header  => 'The Header.  [% title %]',
 346 \&            footer  => sub { return $some_output_text },
 347 \&            another => Template::Document\->new({ ... }),
 348 \&        },
 349 \&    });
 350 .Ve
 351 .PP
 352 \fI\s-1VIEWS\s0\fR
 353 .IX Subsection "VIEWS"
 354 .PP
 355 The \s-1VIEWS\s0 option can be used to pre-define
 356 one or more Template::View objects.
 357 .PP
 358 .Vb 7
 359 \&    my $context = Template::Context\->new({
 360 \&        VIEWS => [
 361 \&            bottom => { prefix => 'bottom/' },
 362 \&            middle => { prefix => 'middle/', base => 'bottom' },
 363 \&            top    => { prefix => 'top/',    base => 'middle' },
 364 \&        ],
 365 \&    });
 366 .Ve
 367 .PP
 368 \fI\s-1TRIM\s0\fR
 369 .IX Subsection "TRIM"
 370 .PP
 371 The \s-1TRIM\s0 option can be set to have any
 372 leading and trailing whitespace automatically removed from the output of all
 373 template files and \f(CW\*(C`BLOCK\*(C'\fRs.
 374 .PP
 375 example:
 376 .PP
 377 .Vb 1
 378 \&    [% BLOCK foo %]
 379 .Ve
 380 .PP
 381 .Vb 1
 382 \&    Line 1 of foo
 383 .Ve
 384 .PP
 385 .Vb 1
 386 \&    [% END %]
 387 .Ve
 388 .PP
 389 .Vb 3
 390 \&    before
 391 \&    [% INCLUDE foo %]
 392 \&    after
 393 .Ve
 394 .PP
 395 output:
 396 .PP
 397 .Vb 3
 398 \&    before
 399 \&    Line 1 of foo
 400 \&    after
 401 .Ve
 402 .PP
 403 \fI\s-1EVAL_PERL\s0\fR
 404 .IX Subsection "EVAL_PERL"
 405 .PP
 406 The \s-1EVAL_PERL\s0 is used to indicate if
 407 \&\f(CW\*(C`PERL\*(C'\fR and/or \f(CW\*(C`RAWPERL\*(C'\fR blocks should be evaluated. It is disabled by
 408 default.
 409 .PP
 410 \fI\s-1RECURSION\s0\fR
 411 .IX Subsection "RECURSION"
 412 .PP
 413 The \s-1RECURSION\s0 can be set to
 414 allow templates to recursively process themselves, either directly
 415 (e.g. template \f(CW\*(C`foo\*(C'\fR calls \f(CW\*(C`INCLUDE foo\*(C'\fR) or indirectly (e.g.
 416 \&\f(CW\*(C`foo\*(C'\fR calls \f(CW\*(C`INCLUDE bar\*(C'\fR which calls \f(CW\*(C`INCLUDE foo\*(C'\fR).
 417 .PP
 418 \fI\s-1LOAD_TEMPLATES\s0\fR
 419 .IX Subsection "LOAD_TEMPLATES"
 420 .PP
 421 The \s-1LOAD_TEMPLATES\s0 option can be
 422 used to provide a reference to a list of Template::Provider objects or
 423 sub-classes thereof which will take responsibility for loading and compiling
 424 templates.
 425 .PP
 426 .Vb 6
 427 \&    my $context = Template::Context\->new({
 428 \&        LOAD_TEMPLATES => [
 429 \&            MyOrg::Template::Provider\->new({ ... }),
 430 \&            Template::Provider\->new({ ... }),
 431 \&        ],
 432 \&    });
 433 .Ve
 434 .PP
 435 \fI\s-1LOAD_PLUGINS\s0\fR
 436 .IX Subsection "LOAD_PLUGINS"
 437 .PP
 438 The \s-1LOAD_PLUGINS\s0 options can be used
 439 to specify a list of provider objects responsible for loading and
 440 instantiating template plugin objects.
 441 .PP
 442 .Vb 6
 443 \&    my $context = Template::Context\->new({
 444 \&        LOAD_PLUGINS => [
 445 \&            MyOrg::Template::Plugins\->new({ ... }),
 446 \&            Template::Plugins\->new({ ... }),
 447 \&        ],
 448 \&    });
 449 .Ve
 450 .PP
 451 \fI\s-1LOAD_FILTERS\s0\fR
 452 .IX Subsection "LOAD_FILTERS"
 453 .PP
 454 The \s-1LOAD_FILTERS\s0 option can be used
 455 to specify a list of provider objects for returning and/or creating filter
 456 subroutines.
 457 .PP
 458 .Vb 6
 459 \&    my $context = Template::Context\->new({
 460 \&        LOAD_FILTERS => [
 461 \&            MyTemplate::Filters\->new(),
 462 \&            Template::Filters\->new(),
 463 \&        ],
 464 \&    });
 465 .Ve
 466 .PP
 467 \fI\s-1STASH\s0\fR
 468 .IX Subsection "STASH"
 469 .PP
 470 The \s-1STASH\s0 option can be used to
 471 specify a Template::Stash object or sub-class which will take
 472 responsibility for managing template variables.
 473 .PP
 474 .Vb 4
 475 \&    my $stash = MyOrg::Template::Stash\->new({ ... });
 476 \&    my $context = Template::Context\->new({
 477 \&        STASH => $stash,
 478 \&    });
 479 .Ve
 480 .PP
 481 \fI\s-1DEBUG\s0\fR
 482 .IX Subsection "DEBUG"
 483 .PP
 484 The \s-1DEBUG\s0 option can be used to enable
 485 various debugging features of the Template::Context module.
 486 .PP
 487 .Vb 1
 488 \&    use Template::Constants qw( :debug );
 489 .Ve
 490 .PP
 491 .Vb 3
 492 \&    my $template = Template\->new({
 493 \&        DEBUG => DEBUG_CONTEXT | DEBUG_DIRS,
 494 \&    });
 495 .Ve
 496 .Sh "template($name)"
 497 .IX Subsection "template($name)"
 498 Returns a compiled template by querying each of the \s-1LOAD_TEMPLATES\s0 providers
 499 (instances of Template::Provider, or sub\-class) in turn.
 500 .PP
 501 .Vb 1
 502 \&    $template = $context\->template('header');
 503 .Ve
 504 .PP
 505 On error, a Template::Exception object of type '\f(CW\*(C`file\*(C'\fR' is thrown via
 506 \&\f(CW\*(C`die()\*(C'\fR.  This can be caught by enclosing the call to \f(CW\*(C`template()\*(C'\fR in an
 507 \&\f(CW\*(C`eval\*(C'\fR block and examining \f(CW$@\fR.
 508 .PP
 509 .Vb 4
 510 \&    eval { $template = $context\->template('header') };
 511 \&    if ($@) {
 512 \&        print "failed to fetch template: $@\en";
 513 \&    }
 514 .Ve
 515 .Sh "plugin($name, \e@args)"
 516 .IX Subsection "plugin($name, @args)"
 517 Instantiates a plugin object by querying each of the \s-1LOAD_PLUGINS\s0
 518 providers. The default \s-1LOAD_PLUGINS\s0 provider is a Template::Plugins
 519 object which attempts to load plugin modules, according the various
 520 configuration items such as \s-1PLUGIN_BASE\s0,
 521 \&\s-1LOAD_PERL\s0, etc., and then instantiate an object
 522 via \fInew()\fR. A reference to a list of constructor
 523 arguments may be passed as the second parameter. These are forwarded to the
 524 plugin constructor.
 525 .PP
 526 Returns a reference to a plugin (which is generally an object, but
 527 doesn't have to be).  Errors are thrown as Template::Exception objects
 528 with the type set to '\f(CW\*(C`plugin\*(C'\fR'.
 529 .PP
 530 .Vb 1
 531 \&    $plugin = $context\->plugin('DBI', 'dbi:msql:mydbname');
 532 .Ve
 533 .ie n .Sh "filter($name, \e@args, $alias)"
 534 .el .Sh "filter($name, \e@args, \f(CW$alias\fP)"
 535 .IX Subsection "filter($name, @args, $alias)"
 536 Instantiates a filter subroutine by querying the \s-1LOAD_FILTERS\s0 providers.
 537 The default \s-1LOAD_FILTERS\s0 provider is a Template::Filters object.
 538 .PP
 539 Additional arguments may be passed by list reference along with an optional
 540 alias under which the filter will be cached for subsequent use. The filter is
 541 cached under its own \f(CW$name\fR if \f(CW$alias\fR is undefined. Subsequent calls to
 542 \&\f(CW\*(C`filter($name)\*(C'\fR will return the cached entry, if defined. Specifying arguments
 543 bypasses the caching mechanism and always creates a new filter. Errors are
 544 thrown as Template::Exception objects with the type set to '\f(CW\*(C`filter\*(C'\fR'.
 545 .PP
 546 .Vb 2
 547 \&    # static filter (no args)
 548 \&    $filter = $context\->filter('html');
 549 .Ve
 550 .PP
 551 .Vb 2
 552 \&    # dynamic filter (args) aliased to 'padright'
 553 \&    $filter = $context\->filter('format', '%60s', 'padright');
 554 .Ve
 555 .PP
 556 .Vb 2
 557 \&    # retrieve previous filter via 'padright' alias
 558 \&    $filter = $context\->filter('padright');
 559 .Ve
 560 .Sh "process($template, \e%vars)"
 561 .IX Subsection "process($template, %vars)"
 562 Processes a template named or referenced by the first parameter and returns
 563 the output generated.  An optional reference to a hash array may be passed
 564 as the second parameter, containing variable definitions which will be set
 565 before the template is processed.  The template is processed in the current
 566 context, with no localisation of variables performed.   Errors are thrown
 567 as Template::Exception objects via \f(CW\*(C`die()\*(C'\fR.
 568 .PP
 569 .Vb 1
 570 \&    $output = $context\->process('header', { title => 'Hello World' });
 571 .Ve
 572 .Sh "include($template, \e%vars)"
 573 .IX Subsection "include($template, %vars)"
 574 Similar to \fIprocess()\fR, but using localised variables.  Changes made to
 575 any variables will only persist until the \f(CW\*(C`include()\*(C'\fR method completes.
 576 .PP
 577 .Vb 1
 578 \&    $output = $context\->include('header', { title => 'Hello World' });
 579 .Ve
 580 .ie n .Sh "throw($error_type, $error_message, \e$output)"
 581 .el .Sh "throw($error_type, \f(CW$error_message\fP, \e$output)"
 582 .IX Subsection "throw($error_type, $error_message, $output)"
 583 Raises an exception in the form of a Template::Exception object by calling
 584 \&\f(CW\*(C`die()\*(C'\fR. This method may be passed a reference to an existing
 585 Template::Exception object; a single value containing an error message
 586 which is used to instantiate a Template::Exception of type '\f(CW\*(C`undef\*(C'\fR'; or a
 587 pair of values representing the exception \f(CW\*(C`type\*(C'\fR and \f(CW\*(C`info\*(C'\fR from which a
 588 Template::Exception object is instantiated. e.g.
 589 .PP
 590 .Vb 3
 591 \&    $context\->throw($exception);
 592 \&    $context\->throw("I'm sorry Dave, I can't do that");
 593 \&    $context\->throw('denied', "I'm sorry Dave, I can't do that");
 594 .Ve
 595 .PP
 596 The optional third parameter may be a reference to the current output
 597 buffer.  This is then stored in the exception object when created,
 598 allowing the catcher to examine and use the output up to the point at
 599 which the exception was raised.
 600 .PP
 601 .Vb 3
 602 \&    $output .= 'blah blah blah';
 603 \&    $output .= 'more rhubarb';
 604 \&    $context\->throw('yack', 'Too much yacking', \e$output);
 605 .Ve
 606 .Sh "catch($exception, \e$output)"
 607 .IX Subsection "catch($exception, $output)"
 608 Catches an exception thrown, either as a reference to a Template::Exception
 609 object or some other value. In the latter case, the error string is promoted
 610 to a Template::Exception object of '\f(CW\*(C`undef\*(C'\fR' type. This method also
 611 accepts a reference to the current output buffer which is passed to the
 612 Template::Exception constructor, or is appended to the output buffer stored
 613 in an existing Template::Exception object, if unique (i.e. not the same
 614 reference). By this process, the correct state of the output buffer can be
 615 reconstructed for simple or nested throws.
 616 .ie n .Sh "define_block($name, $block)"
 617 .el .Sh "define_block($name, \f(CW$block\fP)"
 618 .IX Subsection "define_block($name, $block)"
 619 Adds a new block definition to the internal \s-1BLOCKS\s0 cache.  The first
 620 argument should contain the name of the block and the second a reference
 621 to a Template::Document object or template sub\-routine, or template text
 622 which is automatically compiled into a template sub\-routine.
 623 .PP
 624 Returns a true value (the sub-routine or Template::Document reference) on
 625 success or undef on failure. The relevant error message can be retrieved by
 626 calling the \fIerror()\fR method.
 627 .ie n .Sh "define_filter($name, \e&filter, $is_dynamic)"
 628 .el .Sh "define_filter($name, \e&filter, \f(CW$is_dynamic\fP)"
 629 .IX Subsection "define_filter($name, &filter, $is_dynamic)"
 630 Adds a new filter definition by calling the
 631 \&\fIstore()\fR method on each of the \s-1LOAD_FILTERS\s0
 632 providers until accepted (in the usual case, this is accepted straight away by
 633 the one and only Template::Filters provider). The first argument should
 634 contain the name of the filter and the second a reference to a filter
 635 subroutine. The optional third argument can be set to any true value to
 636 indicate that the subroutine is a dynamic filter factory.
 637 .PP
 638 Returns a true value or throws a '\f(CW\*(C`filter\*(C'\fR' exception on error.
 639 .Sh "define_view($name, \e%params)"
 640 .IX Subsection "define_view($name, %params)"
 641 This method allows you to define a named view.
 642 .PP
 643 .Vb 5
 644 \&    $context\->define_view(
 645 \&        my_view => {
 646 \&            prefix => 'my_templates/'
 647 \&        }
 648 \&    );
 649 .Ve
 650 .PP
 651 The view is then accessible as a template variable.
 652 .PP
 653 .Vb 1
 654 \&    [% my_view.print(some_data) %]
 655 .Ve
 656 .Sh "define_views($views)"
 657 .IX Subsection "define_views($views)"
 658 This method allows you to define multiple named views.
 659 A reference to a hash array or list reference should be passed as an argument.
 660 .PP
 661 .Vb 8
 662 \&    $context\->define_view({     # hash reference
 663 \&        my_view_one => {
 664 \&            prefix => 'my_templates_one/'
 665 \&        },
 666 \&        my_view_two => {
 667 \&            prefix => 'my_templates_two/'
 668 \&        }
 669 \&    });
 670 .Ve
 671 .PP
 672 If you're defining multiple views of which one or more are based on other
 673 views in the same definition then you should pass them as a list reference.
 674 This ensures that they get created in the right order (Perl does not preserve
 675 the order of items defined in a hash reference so you can't guarantee that
 676 your base class view will be defined before your subclass view).
 677 .PP
 678 .Vb 9
 679 \&    $context\->define_view([     # list referenence
 680 \&        my_view_one => {
 681 \&            prefix => 'my_templates_one/'
 682 \&        },
 683 \&        my_view_two => {
 684 \&            prefix => 'my_templates_two/' ,
 685 \&            base   => 'my_view_one',
 686 \&        }
 687 \&    ]);
 688 .Ve
 689 .PP
 690 The views are then accessible as template variables.
 691 .PP
 692 .Vb 2
 693 \&    [% my_view_one.print(some_data) %]
 694 \&    [% my_view_two.print(some_data) %]
 695 .Ve
 696 .PP
 697 See also the \s-1VIEWS\s0 option.
 698 .Sh "localise(\e%vars)"
 699 .IX Subsection "localise(%vars)"
 700 Clones the stash to create a context with localised variables.  Returns a
 701 reference to the newly cloned stash object which is also stored
 702 internally.
 703 .PP
 704 .Vb 1
 705 \&    $stash = $context\->localise();
 706 .Ve
 707 .Sh "\fIdelocalise()\fP"
 708 .IX Subsection "delocalise()"
 709 Restore the stash to its state prior to localisation.
 710 .PP
 711 .Vb 1
 712 \&    $stash = $context\->delocalise();
 713 .Ve
 714 .Sh "visit(\e%blocks)"
 715 .IX Subsection "visit(%blocks)"
 716 This method is called by Template::Document objects immediately before
 717 they process their content.  It is called to register any local \f(CW\*(C`BLOCK\*(C'\fR
 718 definitions with the context object so that they may be subsequently
 719 delivered on request.
 720 .Sh "\fIleave()\fP"
 721 .IX Subsection "leave()"
 722 Compliment to the \fIvisit()\fR method. Called by Template::Document objects
 723 immediately after they process their content.
 724 .Sh "\fIreset()\fP"
 725 .IX Subsection "reset()"
 726 Clears the local \s-1BLOCKS\s0 cache of any \f(CW\*(C`BLOCK\*(C'\fR definitions.  Any initial set of
 727 \&\s-1BLOCKS\s0 specified as a configuration item to the constructor will be reinstated.
 728 .Sh "\s-1AUTOLOAD\s0"
 729 .IX Subsection "AUTOLOAD"
 730 An \f(CW\*(C`AUTOLOAD\*(C'\fR method provides access to context configuration items.
 731 .PP
 732 .Vb 4
 733 \&    $stash     = $context\->stash();
 734 \&    $tflag     = $context\->trim();
 735 \&    $epflag    = $context\->eval_perl();
 736 \&    ...
 737 .Ve
 738 .SH "AUTHOR"
 739 .IX Header "AUTHOR"
 740 Andy Wardley <abw@wardley.org> <http://wardley.org/>
 741 .SH "COPYRIGHT"
 742 .IX Header "COPYRIGHT"
 743 Copyright (C) 1996\-2007 Andy Wardley.  All Rights Reserved.
 744 .PP
 745 This module is free software; you can redistribute it and/or
 746 modify it under the same terms as Perl itself.
 747 .SH "SEE ALSO"
 748 .IX Header "SEE ALSO"
 749 Template, Template::Document, Template::Exception,
 750 Template::Filters, Template::Plugins, Template::Provider,
 751 Template::Service, Template::Stash