Used to specify the default template that should be used for a layout. It can be specified as anything that the Template::TT3::Templates template() method will accept, e.g. a template name, text references, subroutine reference, etc.

template is the default option for the service. Thus the following:

my $layout = Template::TT3::Services->service(
    layout => 'site/layout.tt3',
);

is syntactic sugar for:

my $layout = Template::TT3::Services->service(
    layout => {
        template => 'site/layout.tt3',
    },
);

This can be used to change the name of the service component. The default name is layout. If a layout is specified in the environment passed to the pipeline service function then it will be used in preference to the default template .

$pipeline->(
    context => $context,
    input   => 'example.tt3',
    layout  => 'my/layout.tt3',     # over-ride default layout template
);

This is the main service method. It is called automatically when the service is bound in a pipeline that is executed. A copy of the environment is passed as the first argument (a reference to a hash array). A reference to a subroutine representing the rest of the pipeline is passed as the second argument.

The method looks in the environment for an item named layout, or whatever alternate name the service has been given (e.g. site_layout, section_layout, etc). If the item isn't specified then it instead uses the default layout template defined when the service is created. If that is undefined or set to a false value (e.g. 0 or the empty string '') then no layout is added.

Rendering a layout template is a little complicated. First we have to push the main page template onto the context's visit stack. This is so that slot definitions in the layout template can be filled by block definition in the main page template. Then we define a closure which renders the pipeline content and bind this to the content variable. Then we render the layout template.

TODO: tidy up the above.