$_[1]->{page_title}= "Document."; $_[1]->{amazon_max_disp}= 28;

#

## Contents

- NAME
- SYNOPSIS
- DESCRIPTION
  - <tmpl_ex> ... </tmpl_ex>
  - <tmpl_set name='...' value='...'>
  - <tmpl_var name='env_*[ Environment variable name. ]'>
- METHOD
  - new
  - charset
  - other
- NOTES
- WARNING
- BUGS
- SEEALSO
- COPYRIGHT
- AUTHOR

## NAME

HTML::Template::Ex - The Perl code is executed in HTML::Template.

## SYNOPSIS

    package MyProject;
    use CGI;
    use Jcode;
    use HTML::Template::Ex;

    my $cgi = CGI->new;
    my $self= bless { cgi=> cgi }, __PACKAGE__;

    my $template= <
    <head><title><tmpl_var name="title"></title></head>
    <body>
    <tmpl_set name="title" value="HTML::Template::Ex">

    <h1><tmpl_var name="page_title"></h1>

    <div style="margin:10; background:#DDD;">
    <tmpl_ex>
    	my($self, $param)= @_;
    	$param->{page_title}= 'My Page Title';
    	return $self->{cgi}->param('name') || 'It doesn't receive it.';
    </tmpl_ex>
    </div>

    <div style="margin:10; background:#DDD;">
    <tmpl_loop name="users">
      <div>
      <tmpl_var name="u_name" escape="html">
      : <tmpl_var name="email" escape="html">
      </div>
    </tmpl_loop>
    </div>

    <tmpl_ex name="users">
    return [
     { u_name=> 'foo', email=> 'foo@mydomain'    },
     { u_name=> 'boo', email=> 'boo@localdomain' },
     ];
    </tmpl_ex>

    <tmpl_var name="env_remote_addr">

    <body></html>
    END_OF_TEMPLATE

    my $tmpl= HTML::Template::Ex->new($self, {
      setup_env=> 1,
      scalarref=> \$template,
      encoder  => sub { Jcode->new($_[0])->euc },
      # ... other 'HTML::Template' options.
      });

    print STDOUT $cgi->header, $tmpl->output;

## DESCRIPTION

### <tmpl_ex> ... </tmpl_ex> (EX-Code)

The character string enclosed with <tmpl_ex> ... </tmpl_ex> (Hereafter, it is written as EX-Code) is evaluated as Perl code and executed.

- The HASH reference for the definition of the parameter of the object and the template of the first argument given to the constructor of HTML::Template::Ex is passed to the code. The value substituted for the HASH for the parameter definition can be referred to by using <tmpl_var *NAME>.

Example of template.

    <tmpl_ex>
      my($self, $param)= @_;
      $param->{banban}= '<b>banban</b>';
      "My Object = ". ref($self)
    </tmpl_ex>
    --- <tmpl_var name="banban"> ---

When you do output.

    My Object = *OBJECT-NAME
    --- <b>banban</b> ---

- If the return value of the code is an array and doesn't exist, <tmpl_var *NAME> to bury the return value under the position is put.

Example of template.

    <tmpl_ex> "<h1>result string.</h1>"; </tmpl_ex>

When you do output.

    <h1>result string.</h1>

- The name of the variable for which the return value of the code is substituted can be specified.
  Please use and refer to <tmpl_var *NAME> for the substituted value.

Example of template.

    <tmpl_ex name="foge"> "<b>result string.</b>"; </tmpl_ex>
    --- <tmpl_var name="foge"> ---

When you do output.

    <b>result string.</b>
    --- <b>result string.</b> ---

- When the thing that the return value is buried under the position is not hoped as stated above, the hidden option is made effective.

Example of template.

    <tmpl_ex name="foge" hidden="1"> "<b>result string.</b>"; </tmpl_ex>
    --- <tmpl_var name="foge"> ---

When you do output.

    --- <b>result string.</b> ---

- When the code returns the ARRAY reference, it substitutes for the parameter specified by the name option and it ends. Please use and refer to <tmpl_loop *NAME> for this value.

Example of template.

    <tmpl_ex name="array">
      my @array= ({ name=> 'name1' }, { name=> 'name2' });
      return \@array;
    </tmpl>
    <tmpl_loop><div>name: <tmpl_var name="name"></div></tmpl_loop>

When you do output.

    <div>name: name1</div>
    <div>name: name2</div>

- The 'escape' option to hand to HTML::Template to output it after it escapes in the return value of the code can be specified.

Example of template.

    <tmpl_ex escape="html"> "<h1>result string.</h1>"; </tmpl_ex>

When you do output.

    <result string.>

### <tmpl_set name='...' value='...'>

The parameter value of the template inside can be set with <tmpl_set name='...' value='...'>.

Example of template.

    <tmpl_set name="page_title" value="my page title">
    <h1><tmpl_var name="page_title"></h1>

When you do output.

    <h1>my page title</h1>

### <tmpl_var name='env_*[ Environment variable name. ]'>

The parameter to call the environment variable when the 'setup_env' option is made effective when the constructor is called is prepared. To refer to the prepared value, the name of the environment variable that wants to refer following env_ is specified.

Example of template.

    <div>HTTP_REFERER: <tmpl_var name="env_http_referer"></div>
    <div>REMOTE_ADDR : <tmpl_var name="env_remote_addr"></div>

When you do output.

    <div>HTTP_REFERER: http://....... </div>
    <div>REMOTE_ADDR : 0.0.0.0</div>

## METHOD

### new

It is a constructor.
Please pass in the first argument and pass the option to a suitable object and the second argument with HAHS reference.

Example of code.

    my $self= bless {}, __PACKAGE__;
    my $ex= HTML::Template::Ex
            -> new ($self, { filename=> 'foooo.tmpl', setup_env=> 1 });

#### Parameter of option

Another for HTML::Template can specify the option to evaluate to following original HTML::Template::Ex in the option.

setup_env

... It is made to prepare of refer to the environment variable with <tmpl_var *NAME>.

exec_off

... To invalidate EX-Code temporarily, it keeps effective.

encoder

... The CODE reference to keep the character-code of the template to be constant can be defined.

* When the template made from a different character-code exists together, it finds it useful.

auto_encoder

... Only when the character set was able to be picked up from the template, the code reference passed by this option is started.

* When this option is set, the 'encoder' option becomes meaningless.

no_strict_exec

... When this option becomes effective, the check on the syntax of EX-Code becomes sweet.

### charset

The value can be referred to when charset can be acquired from <meta ... content="text/html; charset=[Character set]"> in the template read.

### other

Other methods succeed the one of HTML::Template.

## NOTES

- About the option to give to the constructor.

      global_vars, compulsorily becomes effective.
      die_on_bad_params, strict, file_cache, shared_cache, compulsorily becomes invalid.
      It came to be able to specify cache from v0.03.

- About order by which EX-Code is evaluated.

  This problem had been improved from v0.03 before though the processing order became complex when <TMPL_INCLUDE *NAME> existed.

  Processing is done in order of <TMPL_EX>'s appearing regardless of the presence of <TMPL_INCLUDE *NAME>.

- Strict code is demanded EX-Code. Otherwise, the error is output or even if the error is not output, the record will remain in the error log of HTTPD.
- There is no restriction in the Perl code that can be written in EX-Code.
  There is a possibility of causing an unpleasant situation because anything passes.
  When the code that especially accepts the input from the visitor is written, close attention is necessary for the user.
  Moreover, please do not write the code that does exit on the way. Because it doesn't understand what happens....
  Let's have it not put on the place where the template is seen from WEB though it is a thing that not is to saying as it....

## WARNING

This module aims only at convenience, is made, and the thing concerning security is not considered. Please give enough security countermeasures on the project code side when actually using it.

## BUGS

When you find a bug, please email me (mizuno@beeflag.com) with a light heart.

## SEE ALSO

HTML::Template.

## COPYRIGHT

Copyright 2005 Bee Flag, Corp. <http://beeflag.com/>, All Rights Reserved.

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

## AUTHOR

Masatoshi Mizuno, mizuno@beeflag.com