• NAME
• VERSION
• DATE
• SYNOPSIS
• DESCRIPTION
• INTERFACE
  • Constructors
  • Public Instance Methods
  • Private Instance Methods
  • Private Class Methods
• NOTES
• AUTHOR
• SEE ALSO

NAME

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

VERSION

$Revision: 1.20 $

DATE

$Date: 2002/08/30 17:05:25 $

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 - args should be a list of key-value pairs

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

$link = _page_link($page)

Returns the filename for the given $page number - index.html for 1, index1.html for 2, etc.

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