The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Minima-v0.1.1
River stage zero No dependents
/ Minima::View::HTML

NAME

Minima::View::HTML -- Render HTML views

SYNOPSIS

use Minima::View::HTML;

my $view = Minima::HTML::View->new(app => $app);

$view->set_directory('templates'); # where templates resite
$view->set_template('home');
$view->set_title('Minima');
$view->add_script('global.js');

my $body = $view->render({ data => ... });

DESCRIPTION

Minima::View::HTML provides a way to render HTML templates using Template Toolkit with ease and a versatile set of data and settings.

This class holds a reference to a Minima::App object, which is primarily used to interact with the configuration hash, where defaults may be set to customize its behaviour.

Its principle of operation is quite simple: after configuring the directory where templates reside (with set_directory or the default templates directory) and selecting the template to be used (with set_template), the view collects and formats data to pass to the template. This final stage ultimately determines how the output is structured.

Note: Minima::View::HTML works with UTF-8 by default, and encodes the body response.

DATA

Content

The following data is managed and made available to template in the view hash. Whether it's used for its original purpose or a custom one is left to the template implementation itself.

title

Scalar used as the page title.

description

Scalar used as the page description (<meta> tag).

header_scripts

A list of scripts to be included in the header.

header_css

A list of linked CSS to be included in the header.

pre

A list of templates to be included before the main template.

post

A list of templates to be included after the main template.

pre_body

A list of templates to be included right before the opening <body> tag.

scripts

A list of scripts to be embeded directly at the end of <body>.

classes

A list of CSS classes to be included in <main>. Before being passed to the view, the class list will be converted into a scalar (with classes separated by spaces). The template name is cleaned up, having its extension removed and any dots replaced by dashes (tr/./-/) to be able to form valid CSS classes.

Settings

The following data is managed and made available to the template in the view.settings hash.

block_indexing

A boolean scalar holding whether or not robots should be blocked from indexing the page.

theme_color

A color to be set on the <meta name="theme-color"> tag.

CONFIGURATION

The tt key may be used in the main Minima::App configuration hash to customize Template Toolkit.

By default, the following configuration is used:

{
    OUTLINE_TAG => '%%',
    ANYCASE => 1,
    ENCODING => 'utf8',
}

These can be overwritten. Additionally, if the app is in development mode (see "development" in Minima::App), DEBUG is set to DEBUG_UNDEF.

METHODS

new

method new (app)

Constructs a new object. Requires a Minima::App reference.

render

method render ($data = {})

Renders the template with the passed data made available to it, as well as the standard data (described in "Data") and returns it.

To configure Template Toolkit, see the "Configuration" section.

set_title

method set_title ($title, $description = undef)

Sets the title and description (optional).

set_compound_title

method set_compound_title ($title, $description = undef)

Sets a secondary title, using the main title as primary, as well as description.

$v->set_title('Title');
$v->set_compound_title('Page');
# Results in: Title • Page

If no primaty title is already set, calling this method produces the same effect as set_title.

set_directory

method set_directory ($directory)

Sets the main directory where templates reside. If this method is not called, the default templates directory will be used.

set_template

method set_template ($title)

Sets the template name to be used. If no extension is present, .tt will be added. A dot (.) must not be present in the template name.

add_include_path

method add_include_path ($directory)

Adds the passed directory as a include path in conjunction with the main directory (set by set_directory). This method can be called multiple times to add multiple paths.

set_block_indexing

method set_block_indexing ($bool = 1)

Sets a boolean scalar to indicate if robots should be blocked from indexing the page. Defaults to true.

set_name_as_class

method set_name_as_class ($bool = 1)

Sets a boolean scalar to indicate whether the template name should be added to the <main> CSS class list. This is particularly useful to target a page on a CSS file by simply using .main.template. Defaults to true.

add_header_script

method add_header_script ($script)

Adds the passed script to the header script list.

add_header_css

method add_header_css ($css)

Adds the passed CSS file name to the header CSS list.

add_pre

method add_pre ($pre)

Adds the passed template name to the pre-template list.

add_post

method add_post ($post)

Adds the passed template name to the post-template list.

add_pre_body

method add_pre_body ($pre)

Adds the passed template name to the pre-body template list.

add_script

method add_script ($script)

Adds the passed script name to the list of scripts embedded in the body.

add_class

method add_class ($class)

Adds the passed class name to the list of <main> classes.

SEE ALSO

Minima, Minima::Controller, perlclass.

AUTHOR

Cesar Tessarin, <cesar@tessarin.com.br>.

Written in September 2024.