File Coverage

lib/Web/DataService/Render.pm

Criterion	Covered	Total	%
statement	9	35	25.7
branch	0	18	0.0
condition	0	6	0.0
subroutine	3	8	37.5
pod	0	5	0.0
total	12	72	16.6

#
# Web::DataService::Render
#
# This module provides a role that is used by 'Web::DataService'.  It
# implements routines for generating documentation pages and output pages by
# rendering templates.
#
# Author: Michael McClennen

use strict;

package Web::DataService::Render;

use Carp 'croak';

use Moo::Role;


# check_doc ( template )
#
# Return the given template filename if the corresponding file path exists and
# is readable under the documentation template directory.  Throw an exception
# if the file exists but is not readable.  Return undefined (false) if the
# file is not there.

sub check_doc {

    my ($ds, $template_path) = @_;

    return unless defined $template_path && $template_path ne '';

    my $full_path = $Web::DataService::FOUNDATION->file_path($ds->{doc_template_dir}, $template_path);

    if ( -e $full_path )
    {
	return $template_path if -r $full_path;
	croak "template $template_path: $!";
    }

    return;
}


# read_doc_partial ( path )
#
# Read the first 2048 characters of the specified template file and return
# them.

sub read_doc_partial {

    my ($ds, $template_path) = @_;

    my $full_path = $Web::DataService::FOUNDATION->file_path($ds->{doc_template_dir}, $template_path);

    open(my $fh, "<", $full_path) || die "cannot read documentation template '$full_path': $!";
    sysread($fh, my $contents, 2048);

    return $contents;
}


# render_doc ( template, definitions, header, footer, vars )
#
# Render the specified template, with the specified parameters.  If
# $definitions and/or $header are defined, process them before the main
# template.  If $footer is defined, process it after the main template.  If
# $vars is defined, it must be a hashref of variable definitions that will be
# passed to the template rendering engine.

sub render_doc {

    my ($ds, $main, $defs, $header, $footer, $vars) = @_;

    # Throw an exception if no templating module was selected.

    croak "you must select a templating module"
	unless defined $ds->{templating_plugin};

    my $templates = { defs => $defs, header => $header,
		      main => $main, footer => $footer };

    $ds->{templating_plugin}->render_template($ds, $ds->{doc_engine}, $vars, $templates);
}


# check_output ( template )
#
# Return the given template filename if the corresponding file path exists and
# is readable under the output template directory.  Throw an exception if the
# file exists but is not readable.  Return undefined (false) if the file is
# not there.

sub check_output {

    my ($ds, $template) = @_;

    return unless defined $template && $template ne '';

    my $template_file = $Web::DataService::FOUNDATION->file_path($ds->{output_templates}, $template);

    if ( -e $template_file )
    {
	return $template if -r $template_file;
	croak "template $template_file: $!";
    }

    return;
}


# render_output ( template, definitions, header, footer, vars )
#
# Render the specified template, with the specified parameters.  If
# $definitions and/or $header are defined, process them before the main
# template.  If $footer is defined, process it after the main template.  If
# $vars is defined, it must be a hashref of variable definitions that will be
# passed to the template rendering engine.

sub render_output {

    my $ds = shift;

    # Throw an exception if no templating module was selected.

    croak "you must select a templating module"
	unless defined $ds->{templating_plugin};

    $ds->{templating_plugin}->render_template($ds->{doc_templates}, @_);
}


1;