NAME

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

SYNOPSIS

No synopsis till now

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 like %myscript%!
</BODY></HTML>

it will output

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

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

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

or as:

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

because they produce the same output.

PAGES IN VARIOUS LANGUAGES

We suppose we have set the parameter "default_language" as "en" in handler.pm

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.

CLASS INTERFACE

CONSTRUCTORS

To DO.

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