NAME

Statocles::Template - A template object to pass around

VERSION

version 0.075

DESCRIPTION

This is the template abstraction layer for Statocles.

ATTRIBUTES

content

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

path

The path to the file for this template. Optional.

theme

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

include_stores

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

METHODS

BUILDARGS

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

render

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

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

include

    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.

merge_state

    $tmpl->merge_state( $state );

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

coercion

    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.

TEMPLATE LANGUAGE

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' );
    $tmpl->render(
        pages => [
            { content => 'foo' },
            { content => 'bar' },
        ]
    );

DEFAULT HELPERS

The following functions are available to the template by default.

content

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

    %= 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 $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.

SEE ALSO

Statocles::Help::Theme

Statocles::Theme

AUTHOR

Doug Bell <preaction@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2016 by Doug Bell.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Statocles

perl -MCPAN -e shell
install Statocles