/ 
Minima-v0.4.1
River stage zero No dependents
/ Minima::View::HTML

NAME

Minima::View::HTML - Render HTML views

SYNOPSIS

use Minima::View::HTML;

my $view = Minima::View::HTML->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.

Default Data

A default data hash can be set using set_default_data. This hash serves as a base for data passed to render, allowing the data in render to overwrite default values as needed.

This is particularly useful for data available at the time of view initialization, which does not depend on the specific controller that ultimately renders the view.

CONFIGURATION

tt

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.

template_ext

The template_ext key may be used to set a default file extension for templates. By default, ht will be used. This extension is added automatically to template file names if none is provided.

METHODS

new

method new (app)

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

add_class

method add_class ($class)

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

add_header_css

method add_header_css ($css)

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

add_header_script

method add_header_script ($script)

Adds the passed script to the header script list.

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.

add_post

method add_post ($post)

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

add_pre

method add_pre ($pre)

Adds the passed template name to the pre-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.

prepare_response

method prepare_response ($response)

Sets the appropriate Content-Type header on the provided Plack::Response object.

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, visit the "CONFIGURATION" in "Configuration" section. See also set_default_data.

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_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_default_data

method set_default_data ($data)

Sets a default data hash that will be used in rendering pages. The hash provided in render is merged with this default data hash.

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

set_template

method set_template ($title)

Sets the template name to be used. If no extension is present, the extension set by the template_ext configuration key (ht by default) will be added. The template file name must not contain a dot (.), except for the one used in the extension.

set_title

method set_title ($title, $description = undef)

Sets the title and description (optional).

SEE ALSO

Minima, Minima::Controller, Minima::View, perlclass.

AUTHOR

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

Written in September 2024.