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

NAME
Bric::Util::Burner::Template - Bric::Util::Burner subclass to publish business assets using HTML::Template formatting assets.

VERSION
$LastChangedRevision$

DATE
$LastChangedDate: 2004-09-10 12:05:14 -0700 (Fri, 10 Sep 2004) $

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

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

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

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

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, $at, $oc, $cat);
    Publishes an asset. Returns a list of resources burned. Parameters are:

    *   $ba

        A business asset object to publish.

    *   $at

        A asset type object for $ba

    *   $oc

        An output channel object to use for the publish

    *   $category

        A category in which to publish.

    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

$burner->content()
    This routine returns the magic content marker used in category templates to break between the header and the footer.

    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.

$success = $self->_add_resource();
    Adds a Bric::Dist::Resource object to this burn.

    Throws:

    NONE

    Side Effects:

    NONE

    Notes:

    NONE

$self->_write_pages(\$output)
    Writes pages in $output (and _header and _footer) to the appropriate output files on disk. Also takes care of building a list of resources in _res for the files written.

    Throws:

    NONE

    Side Effects:

    NONE

    Notes:

    NONE

  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