Bric::Util::Burner::TemplateToolkit(3)

NAME
Bric::Util::Burner::TemplateToolkit - Publish stories using Template Toolkit templates

VERSION
$LastChangedRevision$

DATE
$LastChangedDate: 2008-01-25 01:09:39 +0100 (Fri, 25 Jan 2008) $

SYNOPSIS
 use Bric::Util::Burner::TemplateToolkit;

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

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

DESCRIPTION
This module handles burning business assets using TemplateToolkit templates.

INTERFACE

  Constructors

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

  Public Instance Methods

$resources = $b->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. Note that this is not currently used by the TT burner

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 variable passed by reference.

    Throws: NONE.

    Side Effects: NONE.

    Notes: This method has not yet been implemented for Template Toolkit templates. For the time being, it always returns success.

my $template = $burner->find_template($uri, $tmpl_name)
    Finds the first instance of the template with the name $tmpl_name in the URI directory hierarchy in $uri. Returns the template path, if it exists, and undef if it does not. For example:

      my $uri = '/foo/bar/bletch';
      my $tmpl_name = 'story.mc';
      my $template = $burner->find_template($uri, $tmpl_name);

    The find_template() method will look first for '/foo/bar/bletch/story.mc', and return that string if the template exists. If it doesn't, it'll look for '/foo/bar/story.mc'. If it doesn't find that, it'll look for '/foo/story.mc' and then '/story.mc'. If it finds none of these, it will rutrn null (or an empty list in an array context.

    Throws: NONE.

    Side Effects: NONE.

    Notes: Uses HTML::Mason::Interp->comp_exists() internally to determine if the template exists.

my $template = $burner->find_first_template(@tmpl_list)
    Returns the path to the first template it finds in @tmpl_list. It uses find_template() (see above) to examine each template in @tmpl_list in turn. Thus, this method looks down the directory hierarchy of each template in @tmpl_list before moving on to the next one. For example:

      my @tmpl_list = ('/foo/bar/story.mc', '/sci/anthro/fizzle.mc');
      my $template =  $burner->find_first_template(@tmpl_list)

    In this example, find_first_template will return the name of the first template it finds in this order:

    •   /foo/bar/story.mc'

    •   /foo/story.mc'

    •   /story.mc'

    •   /sci/anthro/fizzle.mc'

    •   /sci/fizzle.mc'

    •   /fizzle.mc'

    If no template is found to exist, find_first_template will return undef (or an empty list in an array context).

    Throws: NONE.

    Side Effects: NONE.

    Notes: See also find_template() above.

$content = $b->display_element($element)
$content = $b->display_element($element, %ARGS)
    A method to be called from template space. This method will find the template associated with the element passed in and call include it in the Template Toolkit execution. The return value is the content to be output. Pass in a list of arguments to have them set up variables in the stash of the element's execution context.

    Throws: NONE.

    Side Effects: NONE.

    Notes: NONE.

my $more_pages = $b->get_more_pages
      % unless ($burner->get_more_pages) {
            <h3>Last page</h3>
      % }

    Returns true if more pages remain to be burned, and false if not. Only enumerated when "display_pages()" is being used to output pages.

    Throws: NONE.

    Side Effects: NONE.

    Notes: NONE.

PRIVATE

  Private Class Methods
NONE.

  Private Instance Methods

$template = $b->_load_template_element($element);
    Given an element (a business asset/data element) return the template element that formats it.

    Throws: NONE.

    Side Effects: NONE.

    Notes: NONE.

$elem = $b->_current_element
    Return the current element in this context.

    Throws: NONE.

    Side Effects: NONE.

    Notes: NONE.

$elem = $b->_current_element_type
    Return the current element type in this context.

    Throws: NONE.

    Side Effects: NONE.

    Notes: NONE.

$b = $b->_push_element($element)
$element = $b->_pop_element;
    Push and pops an element from the element stack. As a story is burned, the burn process can travel down several elements deep. This stack records the order in which each element was transversed so when the burn process exits an element, the correct and current element is at the top of the stack.

    Throws: NONE.

    Side Effects: NONE.

    Notes: NONE.

  Private Functions
None.

NOTES
NONE.

AUTHOR
Arther Bergman <sky@nanisky.com>

David Wheeler <david@kineticode.com>

SEE ALSO
Bric, Bric::Util::Burner