Bric::Util::Burner::Template(3)

NAME
Bric::Util::Burner::Template - Publish stories using HTML::Template templates

VERSION
$LastChangedRevision$

DATE
$LastChangedDate: 2006-01-18 01:09:49 +0100 (Wed, 18 Jan 2006) $

SYNOPSIS
  use Bric::Util::Burner::Template;

  # Create a new HTML::Template burner using the settings from $burner
  my $template_burner = Bric::Util::Burner::Template->new($burner);

  # burn an asset, get back a list of resources
  my $resources = $template_burner->burn_one($ba, $oc, $cat, $at);

DESCRIPTION
This module handles burning business assets using HTML::Template templates.

INTERFACE

  Constructors

$obj = Bric::Util::Burner::Template->new($burner);
    Creates a new Template burner object. Takes a single parameters - $burner which is a Bric::Util::Burner object. The new object will have its attributes initialized by the passed object.

    Throws:

    NONE

    Side Effects:

    NONE

    Notes:

    NONE

  Public Instance Methods

$resources = $template_burner->burn_one($ba, $oc, $cat, $at);
    Burn an asset in a given output channel and category, this is usually called by the preview or publish method. Returns a list of resources burned.

    Parameters are:

    $ba A business asset object to burn.

    $oc The output channel to which to burn the asset.

    $cat
        A category in which to burn the asset.

    $at A asset type object for $ba

    Throws:

    NONE

    Side Effects:

    NONE

    Notes:

    NONE

my $bool = $burner->chk_syntax($ba, \$err)
    Compiles the template found in $ba. If the compile succeeds with no errors, chk_syntax() returns true. Otherwise, it returns false, and the error will be in the $err varible passed by reference.

    Throws: NONE.

    Side Effects: NONE.

    Notes: NONE.

$output = $burner->run_script($element, @args)
    This method finds the script for the given element and executes it. The return value is the output of the script.

    If a script cannot be found for the element then one is autogenerated that looks like:

      return $burner->new_template()->output;

    This enables you to write template files that contain just the default template autofill template tags and not have to create a script file to drive them.

    An Apache::Registry-esque compilation is performed - the script source is compiled as the body of a subroutine in a private package. After the first time a script is compiled it is cached in memory and only re-compiled if changed.

    Throws:

    *   Bric::Util::Template::run_script() requires an $element argument.

    *   Error compiling script ...

    *   Error running script ...

    Side Effects: NONE.

    Notes: NONE.

$template = $burner->new_template(...)
    This routine returns a new HTML::Template::Expr object. This method can take all the same options as HTML::Template::Expr::new() (which is, in turn, mostly the same as the options to HTML::Template::new()) with a few additions. The additional options are:

    element
        The element option tells the burner to find the template associated with that object and open it. Defaults to the current global $element. To turn off this option simply specify a template by name using the filename option.

    autofill
        The returned template object will have TMPL_VARs and TMPL_LOOPs set for the element's attributes. You must specify the element option to use autofill. The autofill option defaults to 1.

        For details about the TMPL_VARs and TMPL_LOOPs that autofill creates see Bric::HTMLTemplate.

    Additionally, some of the defaults for HTML::Template::new() are different:

    global_vars
        Defaults to on for the benefit of the autofill code and general sanity.

    loop_context_vars
        Defaults to on since you'll definitely want 'em.

    cache
        Defaults to off. Don't turn it on unless you know what you're doing - there are some potential problems with <tmpl_include> and Bricolage.

    A common usage of this method within a script file is:

      my $template = $burner->new_template();

    Which is the equivalent of:

      my $template = $burner->new_template(element  => $element,
                                           autofill => 1);

    See Bric::HTMLTemplate for more examples and discussion.

    Throws:

    new_template called with odd number of arguments.

    Unable to find HTML::Template template file.

    Side Effects:

    NONE

    Notes:

    NONE

$burner->page_break()
    This routine breaks pages in the output. It returns a page boundary marker to insert in into the text.

    Throws:

    NONE

    Side Effects:

    NONE

    Notes:

    NONE

  Private Instance Methods

$data = $self->_build_element_vars($element, $template, \@path);
    This method builds all the TMPL_VARs and TMPL_LOOPs that can be extracted from $element. Returns a hash-ref suitable for passing to $template->param().

    Throws:

    NONE

    Side Effects:

    NONE

    Notes:

    NONE

$filename = $self->_find_file($element, $extension);
    Finds a file for this element and extension (.pl or .tmpl) in the current oc and cat. Searches up the category tree as necessary. Returns undef if the file cannot be found.

    As a special-case if $element eq "category" then the category script or template is searched for.

    Throws: NONE.

    Side Effects: NONE.

    Notes: NONE.

@path = $self->_get_template_path()
    Returns the HTML::Template path setting that will search up the category tree for templates starting from the category returned by get_cat.

    Throws: NONE.

    Side Effects: NONE.

    Notes: NONE.

$self->_write_pages(\$output, $element)
    Splits the pages in $$output in to their separate parts, executes any category templates for each, and writes them to the appropriate output files on disk. Also takes care of adding resources for the files written.

    Throws:

    NONE

    Side Effects:

    NONE

    Notes:

    NONE

$output = $self->_runit($element, $script)
    Called by "run_script()" and, for category templates, by "_write_pages()", this method executes the script (with the full path to the .pl script defined in $script and returns the result. If $script is undefined, "_runit()" simply calls "new_template()" and returns the output of the template.

    Throws: NONE.

    Side Effects: NONE.

    Notes: NONE.

@category_template_paths = $self->_find_category_scripts
    This method is called by "_write_pages()" fo find all of the category templates that need executing. The templates are returned as a list of array refereneces. Each array reference contains two items: The full path to the script without the file type extension and a string indicating the template type, either "pl" or "tmpl". The order of the list is defined by the order of execution. For example, if a story was being published in the /reviews/books category, and the category templates /category.pl and /reviews/category.tmpl exist, then the return value will be

      (
        ['/reviews/category', 'tmpl'],
        ['/category', 'pl'],
      )

    The upshot being that /reviews/category.tmpl should be executed first (by calling "new_template()") and that /category.pl should be executed second (by calling "run_script()").

  Private Class Methods

$filename = _element_filename($element)
    Translates the element name into a filename replacing non-alphanumeric characters with underscores. Not garaunteed to be unique, but assumed to be close enough...

    Throws:

    NONE

    Side Effects:

    NONE

    Notes:

    NONE

_compile($code)
    Evals $code in a clean lexical context.

    Throws:

    NONE

    Side Effects:

    NONE

    Notes:

    NONE

NOTES
Bric::Util::Burner::Template does not support the PERL_LOADER or XML_WRITER options described in Bric::Admin.

AUTHOR
Sam Tregar gtstregar@about-inc.comlt

SEE ALSO
Bric::Util::Burner