Statocles::Template - A template object to pass around


This is the template abstraction layer for Statocles.



The main template string. This will be generated by reading the file path by default.


The path to the file for this template. Optional.


The theme this template was created from. Used for includes and other information.


An array of stores to look for includes. Will be used in addition to the include_stores from the Theme.



Set the default path to something useful for in-memory templates.


    my $html = $tmpl->render( %args )

Render this template, passing in %args. Each key in %args will be available as a scalar in the template.


    my $tmpl = $tmpl->include( $path );
    my $tmpl = $tmpl->include( @path_parts );

Get the desired template to include based on the given path or path_parts. Looks through all the include_stores. If nothing is found, looks in the theme includes.


    $tmpl->merge_state( $state );

Merge the given $state hash reference into the existing. Keys in $state override those in the state attribute.


    my $coerce = Statocles::Template->coercion;

    has template => (
        is => 'ro',
        isa => InstanceOf['Statocles::Template'],
        coerce => Statocles::Template->coercion,

A class method to returns a coercion sub to convert strings into template objects.


The default Statocles template language is Mojolicious's Embedded Perl template. Inside the template, every key of the %args passed to render() will be available as a simple scalar:

    # template.tmpl
    % for my $p ( @$pages ) {
    <%= $p->{content} %>
    % }

    my $tmpl = Statocles::Template->new( path => 'template.tmpl' );
        pages => [
            { content => 'foo' },
            { content => 'bar' },


The following functions are available to the template by default.


The content helper gets and sets content sections, including the main content.

    %= content
    <%= content %>

With no arguments, content will get the main content of the template. This will be the HTML from the document or page.

    % content section_name => begin
        Section Content
    % end
    <% content section_name => "Section Content" %>

With two arguments, save the content into the named section. This will be saved in the template state attribute, which can be copied to other templates (like the layout template).

    %= content 'section_name'
    <%= content 'section_name' %>

With one argument, gets the content previously stored with the given section name. This comes from the state attribute.


    %= include 'path/file.html.ep'
    %= include 'path/file.markdown', var => 'value'

Include a file into this one. The file will be parsed as a template and given the same variables as the current template. Optionally, additional name-value pairs can be given to the included template. These additional template variables override any current variables.

Includes will be searched for in the Theme's include_stores attribute. For content documents rendered by the Statocles::Page::Document class, this includes the document's parent directory.

Including markdown files does not automatically translate them into HTML. If you're in a page template or layout template, use the markdown helper to render the markdown into HTML.


    %= markdown $markdown_text
    %= markdown $app->{data}{description}
    %= markdown include 'path/include.markdown'

Render the given markdown text into HTML. This is useful for allowing users to write markdown in site data, and app data in the configuration file, or document data attributes in the document frontmatter.

Combining the markdown and include helpers allows for adding template directives to any included markdown file.