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

$LastChangedRevision$

$LastChangedDate: 2005-07-24 11:09:36 -0700 (Sun, 24 Jul 2005) $

 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);

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

$obj = Bric::Util::Burner::Template->new($burner);

Creates a new Template burner object. Takes a single parameters - CW$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

Publishes an asset. Returns a list of resources burned. Parameters are:

*

$ba A business asset object to publish.

*

$at A asset type object for CW$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 Compiles the template found in CW$ba. If the compile succeeds with no errors, chk_syntax() returns true. Otherwise, it returns false, and the error will be in the CW$err varible passed by reference. Throws: NONE. Side Effects: NONE. Notes: NONE. 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 CW$element argument.

*

Error compiling script ...

*

Error running script ... Side Effects: NONE. Notes: NONE. 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 CW$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

This method builds all the TMPL_VARs and TMPL_LOOPs that can be extracted from CW$element. Returns a hash-ref suitable for passing to CW$template->param(). Throws: NONE Side Effects: NONE Notes: NONE 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 CW$element eq category then the category script or template is searched for. Throws: NONE. Side Effects: NONE. Notes: NONE. 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. Adds a Bric::Dist::Resource object to this burn. Throws: NONE Side Effects: NONE Notes: NONE

$self->_write_pages(\$output)

Writes pages in CW$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

$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 CW$code in a clean lexical context. Throws: NONE Side Effects: NONE Notes: NONE

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

Sam Tregar gtstregar@about-inc.comlt

Bric::Util::Burner