• Name
• Synopsis
• Description
• Interface
  • Constructors
  • Public Instance Methods
  • Private Instance Methods
  • Private Class Methods
• Notes
• Author
• See Also

Name

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

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