NAME

MasonX::Request::HTMLTemplate - Add templates to the Mason Request object

SYNOPSIS

In your httpd.conf file:

  PerlSetVar  MasonRequestClass      MasonX::Request::HTMLTemplate
  # and optionally
  PerlSetVar  MasonDefaultLanguage   en
  PerlSetVar  MasonTemplateBaseDir   undef

In a component hello.mpl

  <& $m->print_template &>

In a file hello.htt

  <HTML><HEAD></HEAD><BODY>
    Hello: %user%
  </BODY></HTML>

and if you call hello.mpl with parameter "user=your_name" 
through POST or through GET like:

http://your_web_site/hello.mpl?user=your_name

the HTML response will be

  <HTML><HEAD></HEAD><BODY>
    Hello: your_name
  </BODY></HTML>

In a file hello.it.htt

  <HTML><HEAD></HEAD><BODY>
    Ciao: %user%
  </BODY></HTML>

and if you call hello.mpl with parameter "user=your_name" 
and "lang=it" through POST or through GET as

http://your_web_site/hello.mpl?user=your_name&lang=it

the HTML response will be

  <HTML><HEAD></HEAD><BODY>
    Ciao: your_name
  </BODY></HTML>

DESCRIPTION

This module tries to add two peculiar functionalities to Mason

easy use of templates
easy building of localized web site

to produce a framewark with all power of Mason but by separating completely the script language from the graphical interface language.

This is done by inheritance HTML::Mason::Request, HTML::Template::Extension and MasonX::Request::WithApacheSession in a single module and by adding one public method "print_template" to standard Mason syntax.

In the form more simple, "print_template" prints out the html code present in a file in the same folder of the called component but with an "htt" extension.

This file has opened using HTML:Template and HTML::Template::Extension.

This file receives a template variable which is a merge of this objects:

all parameters passed from client through GET/POST ($m->request_args)
all parameters present in the session variable $m->session that is a MasonX::Request::WithApacheRequest object
all parameters set through add_template_args method.
for each parameter $key=>$value of the previous items an element of the form "$key=$value"=>1 (to be used with TMPL_IF and IF_TERN HTML::Template::Extension plugins).

This template variable can be used inside the HTML template file using the HTML::Template and HTML::Template::Extension syntax.

As an example, writing a component which calls simply the method "print_template"

html_test.mpl
=============
<& $m->print_template &>

one is simply saying that content HTML of the file html_test.htt is wanted to be printed.

If the content HTML of the file is

html_test.htt
=============
<HTML><HEAD></HEAD><BODY>
  Hello: %user%
</BODY></HTML>

the response will be: "Hello:".

But if you call html_test.mpl with parameter "user=my_name" through POST or through GET as

http://my_web_site/html_test.mpl?user=my_name

the response will be "Hello: my_name".

In the same way, if the variable user is values within the component as:

html_test.mpl
=============
% $m->{args}->{user} = my_name
<& $m->print_template &>

the result will be the same one.

Moreover if a variable "lang" come last to the template why defined in the cookie of session, in the arguments passes to you through POST or through GET or why explicitly defined in the component, then it will come tried, if it exists, the file html_test.${lang}.htt like model localized for the demanded language.

EXAMPLES

Before giving a glance to the syntax of the module we see some uses possible of this module.

SIMPLE SUBSTITUTION OF VARIABLE

simple_var.mpl
==============
<%init>
  # comment next line and call this component as
  # http://.../simple_var.mpl?myscript=Mason
  # it produces the same result
  $m->add_template_args( myscript => 'Mason');
  $m->print_template();
</%init>

simple_var.htt
==============
<HTML><HEAD></HEAD><BODY>
  I love %myscript%!
</BODY></HTML>

it will output

<HTML><HEAD></HEAD><BODY>
  I love Mason!
</BODY></HTML>

The HTML page simple_var.htt can also be wrote as:

<HTML><HEAD></HEAD><BODY>
  I love <TMPL_VAR name="myscript">!
</BODY></HTML>

or as:

  <HTML><HEAD></HEAD><BODY>
    I love 
      <TMPL_VAR name="myscript">
        here my preferred language will appear!
	  </TMPL_VAR>
  </BODY></HTML>

because they produce the same output.

AUTOHANDLER TO DEFINE TEMPLATES

Using Mason autohandler We can define what kind of file are automatically interpreted as template

autohandler
===========
<%init>
  if ($m->request_comp->name =~ /\.htm$/) {
    $m->print_template(undef,$m->request_comp->path);
    return;
  }
  $m->call_next;
</%init>

all files with the extension .htm will be interpreted as template file. With this autohandler, the first example can therefore be rewritten like :

simple_var.htm
==============
<HTML><HEAD></HEAD><BODY>
  I love %myscript%!
</BODY></HTML>

without use of mpl/htt binomial. Obviously, if it is necessary to have greater control about the operation of the page one can be always used the binomial "mpl/htt".

PAGES IN VARIOUS LANGUAGES

We suppose we have set the parameter "default_language" as "en" (this is however the default value) in handler.pm and, for simplicity, we continue to use, as possible, autohandler above.

Which_language_I_speak.htm           Which_language_I_speak.it.htm 
==========================           =============================                         
<HTML><HEAD></HEAD><BODY>            <HTML><HEAD></HEAD><BODY>
  I speak %lang%                       Io parlo %lang%         
</BODY></HTML>                       </BODY></HTML>        

Which_language_I_speak.fr.htm        Which_language_I_speak.es.htm 
=============================        =============================
<HTML><HEAD></HEAD><BODY>            <HTML><HEAD></HEAD><BODY>
  Je parle %lang%                      Jo ablo %lang%         
</BODY></HTML>                       </BODY></HTML>

When a browser requests Which_language_I_speak.htm the relative page in correct language if you have set the variable "lang" in one of this forms

defining it explicitly in you URI request through query string or POST content as
```
http://.../Which_language_I_speak.htm?lang=[en,it,fr,es]
```
if in whatever other pages called before this you set the session parameter
```
$m->session->{lang} = "en"; # or "it" or "fr" or "es"
```
if you use a mpl component instead to directly call Which_language_I_speak.htm, by changing them by substituting "htm" with "htt" and by defining the variable "lang" directly in the component as:
```
$m->add_template_args( 'lang' => "en" ); # or "it" or "fr" or "es"
$m->print_template;
```

Of course Which_language_I_speak.htm (or .htt with the component usage) will be used if lang=en or lang is not set or lang is set to a value for which Which_language_I_speack.${lang}.htm doesn't exist.

form_text.htm
=============
<html><head></head><body>
  <form method="POST" action="#">
    I love <input type="text" name="myscript">
    <input type="submit" value="Test me" name="action">
  </form>
</body></html>

When this page comes sent you can see that next page remember the value previously stated in the text field.

Also value comes stated in the text field if you call page with query string or POST content like http://.../form_text.htm?myscript=MASON

COMBO FORM WITH VALUES PROPAGATED

form_combo.htm
=============
<html><head></head><body>
  <form method="POST" action="#">
    I love 
    <select name="myscript">
    <option %myscript?:selected%></option>
    <option %myscript=MASON?selected%>MASON</option>
    <option %myscript=PHP?selected%>PHP</option>
    <option %myscript=VBScript?selected%>VBScript</option>
    <input type="submit" value="Test me" name="action">
  </form>
</body></html>

Here it can be seen as it's much simple one to remember the element of the combo selected without to write no line of scripting code but using the TMPL_IF HTML::Template syntax given by IF_TERM Extension plugin.

Like described in the relative section to the method items in fact to all the models it comes given, beyond to a reference to the hash of the parameters of form of the type $key=>$value and for every element of this type, also an element "$key=$value"=>1. So, if you select "MASON" item the next page will have a template parameter "myscript=MASON"=>1 beyond to a parameter 'myscript'=>'MASON' and so %myscript=MASON:selected% will print "selected".

CHECKBOX FORM WITH VALUES PROPAGATED

RADIO BUTTON FORM WITH VALUES PROPAGATED

USAGE

ACTIVATION

To use this module you need to tell Mason to use this class for requests. This can be done in one of two ways. If you are configuring Mason via your httpd.conf file, simply add this:

PerlSetVar  MasonRequestClass  MasonX::Request::HTMLTemplate

If you are using a handler.pl file, simply add this param- eter to the parameters given to the ApacheHandler con- structor:

request_class => 'MasonX::Request::HTMLTemplate'

CONFIGURATION

For every parameter we will give the syntax to configure them in httpd.conf file or via handler.pl file as parameters to and ApacheHandler contructor.

This module accept two optional parameters:

template_base_path / MasonTemplateBasePath => your_template_path

It's the path where we automatically find template if not explicitally given in print_template or filename methods. Default is undef that means null template path.

So if we call a component /foo/bar/moo.mpl that calls print_template the template must be located in /your_template_path/foo/bar/moo.htt where root is Mason root component path.
default_language / MasonDefaultLanguage => lang

Give the language for which default template will be called.

If default_language = 'en' and you call a componente foo.mpl with lang = 'fr' then foo.fr.htt will be search and, if exists, returned, else will be used foo.htt. But if you call it with lang = 'en' then foo.htt will be used and not foo.en.htt.

PUBLIC METHODS

add_template_args ( item_1 => value_1,..., item_n => value_n );

This method will be make that the list passed as parameter could be used in the template in agreement with the syntax of the HTML::Template::Extension module.

filename ( $template_file_path )

Set/get the filename path of the tamplate to be used.

is_absolute (0|1)

This method set/get a boolean value that set if the template_file_path parameter in the print_template and filename method is relative to the root filesystem or is relative to the root Mason component path.

items

Return a reference of an hash that is a merge of this objects:

all parameters passed from client through GET/POST ($m->request_args)
all parameters present in the session variable
all parameters set through add_template_args method.
for each parameter $key=>$value of the previous items an element of the form "$key=$value"=>1 (to be used with TMPL_IF and IF_TERN HTML::Template::Extension plugins).

print_template ( [$args] , [$template_file_path] )

This method print the output in the template present in the same path as the camponent called but with an extention file "htt".

PUBLIC VARIABLES

To Do.

DIAGNOSTICS

No diagnostics error returned.

EXPORT