.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Mojolicious::Renderer 3pm"
.TH Mojolicious::Renderer 3pm 2024-05-15 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Mojolicious::Renderer \- Generate dynamic content
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  use Mojolicious::Renderer;
\&
\&  my $renderer = Mojolicious::Renderer\->new;
\&  push @{$renderer\->classes}, \*(AqMyApp::Controller::Foo\*(Aq;
\&  push @{$renderer\->paths}, \*(Aq/home/sri/templates\*(Aq;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Mojolicious::Renderer is the standard Mojolicious renderer.
.PP
See Mojolicious::Guides::Rendering for more.
.SH ATTRIBUTES
.IX Header "ATTRIBUTES"
Mojolicious::Renderer implements the following attributes.
.SS cache
.IX Subsection "cache"
.Vb 2
\&  my $cache = $renderer\->cache;
\&  $renderer = $renderer\->cache(Mojo::Cache\->new);
.Ve
.PP
Renderer cache, defaults to a Mojo::Cache object.
.SS classes
.IX Subsection "classes"
.Vb 2
\&  my $classes = $renderer\->classes;
\&  $renderer   = $renderer\->classes([\*(Aqmain\*(Aq]);
.Ve
.PP
Classes to use for finding templates in \f(CW\*(C`DATA\*(C'\fR sections with Mojo::Loader, first one has the highest precedence,
defaults to \f(CW\*(C`main\*(C'\fR. Only files with exactly two extensions will be used, like \f(CW\*(C`index.html.ep\*(C'\fR. Note that for
templates to be detected, these classes need to have already been loaded and added before "warmup" is called, which
usually happens automatically during application startup.
.PP
.Vb 2
\&  # Add another class with templates in DATA section
\&  push @{$renderer\->classes}, \*(AqMojolicious::Plugin::Fun\*(Aq;
\&
\&  # Add another class with templates in DATA section and higher precedence
\&  unshift @{$renderer\->classes}, \*(AqMojolicious::Plugin::MoreFun\*(Aq;
.Ve
.SS compress
.IX Subsection "compress"
.Vb 2
\&  my $bool  = $renderer\->compress;
\&  $renderer = $renderer\->compress($bool);
.Ve
.PP
Try to negotiate compression for dynamically generated response content and \f(CW\*(C`gzip\*(C'\fR compress it automatically, defaults
to true.
.SS default_format
.IX Subsection "default_format"
.Vb 2
\&  my $default = $renderer\->default_format;
\&  $renderer   = $renderer\->default_format(\*(Aqhtml\*(Aq);
.Ve
.PP
The default format to render if \f(CW\*(C`format\*(C'\fR is not set in the stash, defaults to \f(CW\*(C`html\*(C'\fR. Note that changing the default
away from \f(CW\*(C`html\*(C'\fR is not recommended, as it has the potential to break, for example, plugins with bundled templates.
.SS default_handler
.IX Subsection "default_handler"
.Vb 2
\&  my $default = $renderer\->default_handler;
\&  $renderer   = $renderer\->default_handler(\*(Aqep\*(Aq);
.Ve
.PP
The default template handler to use for rendering in cases where auto-detection doesn't work, like for \f(CW\*(C`inline\*(C'\fR
templates.
.SS encoding
.IX Subsection "encoding"
.Vb 2
\&  my $encoding = $renderer\->encoding;
\&  $renderer    = $renderer\->encoding(\*(Aqkoi8\-r\*(Aq);
.Ve
.PP
Will encode generated content if set, defaults to \f(CW\*(C`UTF\-8\*(C'\fR. Note that many renderers such as
Mojolicious::Plugin::EPRenderer also use this value to determine if template files should be decoded before
processing.
.SS handlers
.IX Subsection "handlers"
.Vb 2
\&  my $handlers = $renderer\->handlers;
\&  $renderer    = $renderer\->handlers({epl => sub {...}});
.Ve
.PP
Registered handlers.
.SS helpers
.IX Subsection "helpers"
.Vb 2
\&  my $helpers = $renderer\->helpers;
\&  $renderer   = $renderer\->helpers({url_for => sub {...}});
.Ve
.PP
Registered helpers.
.SS min_compress_size
.IX Subsection "min_compress_size"
.Vb 2
\&  my $size  = $renderer\->min_compress_size;
\&  $renderer = $renderer\->min_compress_size(1024);
.Ve
.PP
Minimum output size in bytes required for compression to be used if enabled, defaults to \f(CW860\fR.
.SS paths
.IX Subsection "paths"
.Vb 2
\&  my $paths = $renderer\->paths;
\&  $renderer = $renderer\->paths([\*(Aq/home/sri/templates\*(Aq]);
.Ve
.PP
Directories to look for templates in, first one has the highest precedence.
.PP
.Vb 2
\&  # Add another "templates" directory
\&  push @{$renderer\->paths}, \*(Aq/home/sri/templates\*(Aq;
\&
\&  # Add another "templates" directory with higher precedence
\&  unshift @{$renderer\->paths}, \*(Aq/home/sri/themes/blue/templates\*(Aq;
.Ve
.SH METHODS
.IX Header "METHODS"
Mojolicious::Renderer inherits all methods from Mojo::Base and implements the following new ones.
.SS accepts
.IX Subsection "accepts"
.Vb 2
\&  my $all  = $renderer\->accepts(Mojolicious::Controller\->new);
\&  my $best = $renderer\->accepts(Mojolicious::Controller\->new, \*(Aqhtml\*(Aq, \*(Aqjson\*(Aq);
.Ve
.PP
Select best possible representation for Mojolicious::Controller object from \f(CW\*(C`format\*(C'\fR \f(CW\*(C`GET\*(C'\fR/\f(CW\*(C`POST\*(C'\fR parameter,
\&\f(CW\*(C`format\*(C'\fR stash value, or \f(CW\*(C`Accept\*(C'\fR request header, defaults to returning the first extension if no preference could be
detected.
.SS add_handler
.IX Subsection "add_handler"
.Vb 1
\&  $renderer = $renderer\->add_handler(epl => sub {...});
.Ve
.PP
Register a handler.
.PP
.Vb 4
\&  $renderer\->add_handler(foo => sub ($renderer, $c, $output, $options) {
\&    ...
\&    $$output = \*(AqHello World!\*(Aq;
\&  });
.Ve
.SS add_helper
.IX Subsection "add_helper"
.Vb 1
\&  $renderer = $renderer\->add_helper(url_for => sub {...});
.Ve
.PP
Register a helper.
.PP
.Vb 3
\&  $renderer\->add_helper(foo => sub ($c, @args) {
\&    ...
\&  });
.Ve
.SS get_data_template
.IX Subsection "get_data_template"
.Vb 5
\&  my $template = $renderer\->get_data_template({
\&    template       => \*(Aqfoo/bar\*(Aq,
\&    format         => \*(Aqhtml\*(Aq,
\&    handler        => \*(Aqepl\*(Aq
\&  });
.Ve
.PP
Return a \f(CW\*(C`DATA\*(C'\fR section template from "classes" for an options hash reference with \f(CW\*(C`template\*(C'\fR, \f(CW\*(C`format\*(C'\fR,
\&\f(CW\*(C`variant\*(C'\fR and \f(CW\*(C`handler\*(C'\fR values, or \f(CW\*(C`undef\*(C'\fR if no template could be found, usually used by handlers.
.SS get_helper
.IX Subsection "get_helper"
.Vb 1
\&  my $helper = $renderer\->get_helper(\*(Aqurl_for\*(Aq);
.Ve
.PP
Get a helper by full name, generate a helper dynamically for a prefix, or return \f(CW\*(C`undef\*(C'\fR if no helper or prefix could
be found. Generated helpers return a proxy object containing the current controller object and on which nested helpers
can be called.
.SS render
.IX Subsection "render"
.Vb 1
\&  my ($output, $format) = $renderer\->render(Mojolicious::Controller\->new);
.Ve
.PP
Render output through one of the renderers. See "render" in Mojolicious::Controller for a more user-friendly interface.
.SS respond
.IX Subsection "respond"
.Vb 3
\&  my $bool = $renderer\->respond(Mojolicious::Controller\->new, $output, $format);
\&  my $bool = $renderer\->respond(
\&    Mojolicious::Controller\->new, $output, $format, $status);
.Ve
.PP
Finalize dynamically generated response content and "compress" it if possible.
.SS template_for
.IX Subsection "template_for"
.Vb 1
\&  my $name = $renderer\->template_for(Mojolicious::Controller\->new);
.Ve
.PP
Return default template name for Mojolicious::Controller object, or \f(CW\*(C`undef\*(C'\fR if no name could be generated.
.SS template_handler
.IX Subsection "template_handler"
.Vb 4
\&  my $handler = $renderer\->template_handler({
\&    template => \*(Aqfoo/bar\*(Aq,
\&    format   => \*(Aqhtml\*(Aq
\&  });
.Ve
.PP
Return handler for an options hash reference with \f(CW\*(C`template\*(C'\fR, \f(CW\*(C`format\*(C'\fR and \f(CW\*(C`variant\*(C'\fR values, or \f(CW\*(C`undef\*(C'\fR if no
handler could be found.
.SS template_name
.IX Subsection "template_name"
.Vb 5
\&  my $template = $renderer\->template_name({
\&    template => \*(Aqfoo/bar\*(Aq,
\&    format   => \*(Aqhtml\*(Aq,
\&    handler  => \*(Aqepl\*(Aq
\&  });
.Ve
.PP
Return a template name for an options hash reference with \f(CW\*(C`template\*(C'\fR, \f(CW\*(C`format\*(C'\fR, \f(CW\*(C`variant\*(C'\fR and \f(CW\*(C`handler\*(C'\fR values, or
\&\f(CW\*(C`undef\*(C'\fR if no template could be found, usually used by handlers.
.SS template_path
.IX Subsection "template_path"
.Vb 5
\&  my $path = $renderer\->template_path({
\&    template => \*(Aqfoo/bar\*(Aq,
\&    format   => \*(Aqhtml\*(Aq,
\&    handler  => \*(Aqepl\*(Aq
\&  });
.Ve
.PP
Return the full template path for an options hash reference with \f(CW\*(C`template\*(C'\fR, \f(CW\*(C`format\*(C'\fR, \f(CW\*(C`variant\*(C'\fR and \f(CW\*(C`handler\*(C'\fR
values, or \f(CW\*(C`undef\*(C'\fR if the file does not exist in "paths", usually used by handlers.
.SS warmup
.IX Subsection "warmup"
.Vb 1
\&  $renderer\->warmup;
.Ve
.PP
Prepare templates from "classes" for future use.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Mojolicious, Mojolicious::Guides, <https://mojolicious.org>.