Bric::Util::Burner::TeUsertContributed Perl DoBric::Util::Burner::Template(3p)



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

VERSION
       $LastChangedRevision$

DATE
       $LastChangedDate: 2006-01-18 01:09:49 +0100 (Wed, 18 Jan 2006) $

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:

           o   Bric::Util::Template::run_script() requires an $element
               argument.

           o   Error compiling script ...

           o   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



perl v5.12.2                      2006-01-17  Bric::Util::Burner::Template(3p)
