Tenjin::Template(3pm)

💖 Tenjin::Template 💖

okay so bestie, welcome to the manual page for Tenjin::Template — it's a Perl module, it lives in the Tenjin::Template(3pm) corner of your friendly neighborhood user-contributed Perl documentation, and it's literally the template object of the Tenjin world. Buckle up, we're doing this. 🎀

---

✨ NAME ✨

Tenjin::Template — a Tenjin template object, either built from a file or from memory. it's giving "I contain multitudes, but specifically the template kind." 💅

---

🌸 SYNOPSIS 🌸

mostly this thing is used internally, but bestie you can manipulate templates like so:

# mostly used internally, but you can manipulate
# templates like so

my $template = Tenjin::Template->new('/path/to/templates/template.html');
my $context = { scalar => 'scalar', arrayref => ['one', 2, "3"] };
$template->render($context);

like, that's the whole vibe. 🦋

---

💜 DESCRIPTION 💜

so this module's whole job, its main character era, is the task of compiling Tenjin templates. Templates in Tenjin get compiled into standard Perl code (combined with any Perl code you used inside the templates themselves). and rendering a template? that means "eval"uating that Perl code and returning its output. no cap. 🔥

The Tenjin engine reads a template file or a template string, and creates a Template object from it. Then the object compiles itself by traversing the template, parsing Tenjin macros like 'include' and 'start_capture', replaces Tenjin expressions (i.e. "[== $expr =]" or "[= $expr =]") with the appropriate Perl code, etc. This module ties a template object with a context object, but all context manipulation (and the actual "eval"uation of the Perl code) is done by Tenjin::Context.

⚠️ ok so important: if you're planning on using this module by itself (i.e. without the Tenjin engine), keep in mind that template caching and layout templates are not handled by this module. that's a different module's problem, bestie. not ours. 🙈

---

👑 METHODS 👑

new( [$filename, \%opts] )

Creates a new Tenjin::Template object, possibly from a file on the file system (in which case $filename must be provided and be an absolute path to a template file). Optionally, a hash-ref of options can be passed to set some customizations. Available options are:

• 'escapefunc' — this one's in charge of escaping expressions (from "[= $expr =]") instead of the internal method (which uses HTML::Entities). 💅
• 'rawclass' — can be used to prevent variables and objects of a certain class from being escaped, in which case the variable must be a hash-ref that has a key named 'str', which will be used instead.

so like, for example, if you have a variable named $var which is a hash-ref, and 'rawclass' is set as 'HASH', then writing "[= $var =]" on your templates will replace $var with "$var->{str}". iconic behavior honestly. ✨

render( [$_context] )

Renders the template, possibly with a context hash-ref, and returns the rendered output. and if errors have occurred when rendering the template (which might happen since templates have and are Perl code), then this method will croak. 💀 so like, be aware.

---

🧚 INTERNAL METHODS 🧚

convert_file( $filename )

Receives an absolute path to a template file, converts that file to Perl code by calling convert() and returns that code. 🍓

convert( $input, [$filename] )

Receives a text of a template (i.e. the template itself) and possibly an absolute path to the template file (if the template comes from a file), and converts the template into Perl code, which is later "eval"uated for rendering. Conversion is done by parsing the statements in the template (see parse_stmt()).

compile_stmt_pattern( $pl )

Receives a string which denotes the Perl code delimiter which is used inside templates. Tenjin uses '"<?pl ... ?>"' and '"<?PL ... ?>"' (the latter for preprocessing), so $pl will be 'pl'. This method returns a tranlsation regular expression which will be used for reading embedded Perl code.

stmt_pattern

Returns the default pattern (which uses 'pl') with the previous_method.

expr_pattern()

Defines how expressions are written in Tenjin templates ("[== $expr =]" and "[= $expr =]").

parse_stmt( $bufref, $input )

Receives a buffer which is used for saving a template's expressions and the template's text, parses all expressions in the templates and pushes them to the buffer.

hook_stmt( $stmt )

(yes bestie, that's the whole signature. sometimes a method is just out here existing, and that's valid. 🫶)

expand_macro( $funcname, $arg )

This method is in charge of invoking macro functions which might be used inside templates. The following macros are available:

• include( $filename ) Includes another template, whose name is $filename, inside the current template. The included template will be placed inside the template as if they were one unit, so the context variable applies to both. 🌈
• start_capture( $name ) and end_capture() Tells Tenjin to capture the output of the rendered template from the point where start_capture() was called to the point where end_capture() was called. You must provide a name for the captured portion, which will be made available in the context as "$_context->{$name}" for immediate usage. Note that the captured portion will not be printed unless you do so explicilty with "$_context->{$name}". 👀
• start_placeholder( $var ) and end_placeholder() This is a special method which can be used for making your templates a bit cleaner. Suppose your context might have a variable whose name is defined in $var. If that variable exists in the context, you simply want to print it, but if it's not, you want to print and/or perform other things. In that case you can call start_placeholder( $var ) with the name of the context variable you want printed, and if it's not, anything you do between start_placeholder() and end_placeholder() will be printed instead. ✨
• echo( $exr ) Just prints the provided expression. You might want to use it if you're a little too comfortable with PHP. 😭

get_expr_and_escapeflag( $not_escape, $expr, $delete_newline )

parse_expr( $bufref, $input )

start_text_part( $bufref )

stop_text_part( $bufref )

add_text( $bufref, $text )

add_stmt( $bufref, $stmt )

add_expr( $bufref, $expr, $flag_escape )

defun( $funcname, @args )

compile()

y'all these ones above didn't get descriptions in the original, so I'm not gonna invent them — no making things up on my watch, that's not the vibe. here they are in all their mysterious glory. 💜

escaped_expr( $expr )

Receives a Perl expression (from "[= $expr =]") and escapes it. This will happen in one of three ways:

• with the escape function defined in "$opts->{escapefunc}" (if defined),
• with a scalar string (if "$opts->{rawclass}" is defined),
• or with escape_xml() from Tenjin::Util, which uses HTML::Entites.

(typo's theirs, not mine — copying it exactly because that's the rule. 🫶)

_read_file( $filename, [$lock_required] )

Receives an absolute path to a template file, reads its content and returns it. If $lock_required is passed (and has a true value), the file will be locked for reading. 🔒

_write_file( $filename, $content, [$lock_required] )

Receives an absolute path to a template file and the templates contents, and creates the file (or truncates it, if existing) with that contents. If $lock_required is passed (and has a true value), the file will be locked exclusively when writing. 🔒

---

💀 SEE ALSO 💀

• Tenjin.

like, go read that one too bestie, it's the whole engine. iykyk. 🌟

---

📜 AUTHOR, LICENSE AND COPYRIGHT 📜

See Tenjin.

(fr fr, that's what it says. the details live over there. 🎀)

---

aaaaand that's a wrap on Tenjin::Template bestie!! 💖 this page came from the user contributed perl documentation, and it's tagged perl v5.38.2, dated 2024-03-08 — so like, vintage but make it cute. slay, go compile some templates, and remember: the vibe changes, but the facts never do. periodt. 💅✨🦋