There is an ongoing outage on the primary CPAN mirror. It is possible to work around the issue by using MetaCPAN as a mirror.

 / 
Minima-v0.7.4
River stage zero No dependents
⭐ Starred 2 GitHub stars
/ Minima::View::HTML

NAME

Minima::View::HTML - Render HTML views

SYNOPSIS

use Minima::View::HTML;

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

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

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

DESCRIPTION

Minima::View::HTML renders HTML templates with Template Toolkit, providing a simple interface and a versatile set of data and settings.

It holds a reference to a Minima::App object, mainly to access the configuration hash, where defaults may be defined to customize its behaviour.

Principle of Operation

In short, Minima::View::HTML manages data and assembles a sequence of templates. This data can be maintained directly by the view (page title, scripts to include, etc. — see "Data") or passed right at the render call (commonly model or database data — see "Custom Data").

The sequence always contains a single main template (set with set_template) and two optional sets to be included before and after the main template (set with add_before_template and add_after_template). A typical use is to render a header before and a footer after the main content.

Template names are resolved against the include paths, which by default contain template and js. This list can be managed with add_directory, clear_directories and the templates_dir configuration key. Extensions may be omitted, as template_ext is automatically applied.

Note: Minima::View::HTML works in UTF-8 and encodes the body response accordingly.

DATA

Data handled by Minima::View::HTML is grouped as content and settings. How this data is used ultimately depends on the template. See the templates generated by minima(1) for examples.

Each item has at least one method to manipulate it (see "Methods").

Content

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

title

Scalar containing the page title.

description

Scalar containing the page description (used in the <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.

body_open

A list of templates to be included immediately after the opening <body> tag, providing a useful insertion point.

body_close

A list of templates to be included immediately before the closing <body> tag, providing a useful insertion point.

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> or <body>. Before being passed to the view, the class list will be converted into a scalar (with classes separated by spaces).

This list may include the template name, if name_as_class is set. In this case, 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. Each of these keys can also be set directly in the Minima::App configuration hash.

block_indexing

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

name_as_class

A boolean scalar holding whether or not the template name should be included in classes. Defaults to true.

theme_color

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

Custom Data

Custom data can also be passed directly at the render call, which accepts a hash where keys will become variables available to the templates.

A default data hash can also 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 method that ultimately renders the view (i.e. user data applicable for all methods of the controller).

CONFIGURATION

In addition to the settings keys, the following options are available in the main Minima::App configuration hash.

default_title

Sets a default title, avoiding the need to call set_title on each page, and enabling the practical use of set_compound_title.

tt

The tt key may be used to customize Template Toolkit. By default, the following configuration is used:

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

Any of these may be overwritten.

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.

templates_dir

List of directories forming the template include path. If this key exists but is not a valid list reference, the include path remains empty. If this key does not exist, the include path list will contain templates and js by default.

See also: add_directory and clear_directories.

METHODS

new

method new (app)

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

add_after_template

method add_after_template ($template)

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

add_before_template

method add_before_template ($template)

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

add_body_close

method add_body_close ($template)

Adds the passed template name to the template list for the insertion point immediatelly before the closing </body> tag.

If no file extension is provided, the one defined by the template_ext configuration key is automatically added.

add_body_open

method add_body_open ($template)

Adds the passed template name to the template list for the insertion point immediatelly after the opening <body> tag.

If no file extension is provided, the one defined by the template_ext configuration key is automatically added.

add_class

method add_class ($class)

Adds the passed class name to the list of classes.

add_directory

method add_directory ($directory)

Adds the given directory to the include path, giving it precedence over previously added ones. This method can be called multiple times to build a search path where the most recently added directory is checked first. The include list can be emptied with clear_directories.

See also: templates_dir.

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_script

method add_script ($script)

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

clear_directories

method clear_directories

Empties the template include path list.

See also: add_directory and templates_dir.

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. Keys in the data hash become variables at the template.

To configure Template Toolkit, see the "Configuration" section. See also set_default_data.

set_block_indexing

method set_block_indexing ($bool = 1)

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

set_compound_title

method set_compound_title ($title, $description = undef)

Appends a secondary title to the main title, separated by a middle dot (•). Optionally sets the description.

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

If no primary title is set, this behaves like set_title. This method is particularly useful in combination with default_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 over this default data hash.

set_description

method set_description ($description)

Sets the /description of the page.

set_name_as_class

method set_name_as_class ($bool = 1)

Sets the boolean scalar /name_as_class to indicate whether the template name should be added to the /classes list. Useful to target a page on a CSS file by simply using i.e. .main.template. Defaults to true.

set_template

method set_template ($name)

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). The title may also be set with default_title. See also set_compound_title.

set_theme_color

method set_theme_color ($color)

Sets the theme_color.

SEE ALSO

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

AUTHOR

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

Written in September 2024.