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

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 framework 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 and HTML::Template::Extension 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::WithApacheSession object. (only available in MasonX::Request::HTMLTemplate::WithApacheSession environment.
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 components using add_template_args like:

html_test.mpl
=============
% $m->add_template_args( user => my_name );
% $m->print_template;

the result will be the same one.

Moreover if a variable lang come sent 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 like:

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

or like:

  <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. Of course, so that htm files are processes from autohandler it's necessary that they are seen as Mason component. To do this simply add to your httpd.conf

<Files ~ "\.htm$" />
  SetHandler perl-script
  PerlHandler HTML::Mason::ApacheHandler
</Files>

or however in an analogous way to as they have been it sets up .mpl/.mhtm files.

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 (in MasonX::Request::HTMLTemplate::WithApacheSession environement):
```
$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 like:
```
$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.

TEXTBOX FORM WITH VALUES PROPAGATED

form_text.htm
=============
<html><head></head><body>
  <form method="POST" action="#">
    I love <input type="text" name="myscript" value="%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

form_checkbox.htm
=================
<html><head></head><body>
  <form method="POST" action="#">
    I love<br>
    <input type="checkbox" name="myscript" 
      value="MASON" %myscript=MASON?checked%>MASON<br>
    <input type="checkbox" name="myscript" 
      value="PHP" %myscript=PHP?checked%>PHP<br>
    <input type="checkbox" name="myscript"
      value="VBScript" %myscript=VBScript?checked%>VBScript<br>
    <input type="submit" value="Test me" name="action">
  </form>
</body></html>

RADIO BUTTON FORM WITH VALUES PROPAGATED

form_radio.htm
==============
<html><head></head><body>
  <form method="POST" action="#">
    I love<br>
    <input type="radio" name="myscript" 
      value="MASON" %myscript=MASON?checked%>MASON<br>
    <input type="radio" name="myscript" 
      value="PHP" %myscript=PHP?checked%>PHP<br>
    <input type="radio" name="myscript"
      value="VBScript" %myscript=VBScript?checked%>VBScript<br>
    <input type="submit" value="Test me" name="action">
  </form>
</body></html>

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 parameter to the parameters given to the ApacheHandler constructor:

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

template_arg ( template_param_name )

Return the value of the selected template parameter previously added with add_template_args method.

PUBLIC VARIABLES

No public variables defined

DIAGNOSTICS

No diagnostics error returned.

EXPORT

Nothing to export.

REQUIRES

HTML::Mason, HTML::Template::Extension, Params::Validate, File::Spec

SUPPORT

Contact directly the author or submit a bug to

http://rt.cpan.org/NoAuth/Bugs.html?Dist=MasonX-Request-HTMLTemplate

AUTHOR

Emiliano Bruni, <info <at> ebruni <dot> it>

LICENSE

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

This module is free software; you can redistribute it and/or modify it under the terms of either:

a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or

b) the "Artistic License" which comes with this module.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details.

You should have received a copy of the Artistic License with this module, in the file ARTISTIC. If not, I'll be glad to provide one.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

To install MasonX::Request::HTMLTemplate, copy and paste the appropriate command in to your terminal.

cpanm

cpanm MasonX::Request::HTMLTemplate

CPAN shell

perl -MCPAN -e shell
install MasonX::Request::HTMLTemplate

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)