Bric::Util::Burner::MaUser3Contributed Perl DocumBric::Util::Burner::Mason(3p)



NAME
       Bric::Util::Burner::Mason - Publish sturies using Mason templates

VERSION
       $LastChangedRevision$

DATE
       $LastChangedDate: 2006-09-06 00:52:09 +0200 (Wed, 06 Sep 2006) $

SYNOPSIS
         use Bric::Util::Burner::Mason;

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

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

DESCRIPTION
       This module handles burning business assets using Mason templates.

INTERFACE
   Constructors
       $obj = Bric::Util::Burner::Mason->new($burner);
           Creates a new Mason 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 Mason.

       my $bool = $burner->chk_syntax($template, \$err)
           Compiles the template found in $template. 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: NONE.

       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 return 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:

           o   /foo/bar/story.mc'

           o   /foo/story.mc'

           o   /story.mc'

           o   /sci/anthro/fizzle.mc'

           o   /sci/fizzle.mc'

           o   /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.

       $success = $b->display_element($element)
       $success = $b->display_element($element, %ARGS)
           A method to be called from template space. This method will find
           the mason element associated with the element passed in and call
           "$m->comp". All arguments after the first argument will be passed
           to the template executed as its %ARGS hash.

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       $html = $b->sdisplay_element($element)
           A method to be called from template space. This is a sprintf
           version of $b->display_element(), i.e. it returns as a string of
           HTML what would have been displayed with $b->display_element().

           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.

       $success = $b->chain_next()
           This method can be used in an autohandler template. It calls the
           next template in the chain, whether its the next autohandler down
           the line or the template itself.

           Throws: NONE.

           Side Effects: NONE.

           Notes:

           This is a wrapper around masons 'call_next' method. We wrap it here
           to make sure we have control over the burn process at this level if
           we need it. It also gives us the opportunity to tailor the verbiage
           to suit our application better.

       $success = $b->end_page;
           Writes out the current page and starts a new one.

           Throws:

           o   Unable to open file for writing.

           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.

       $html = $b->_render_element($element, $display)
           Common code used by $b->display_element and $b->sdisplay_element.
           It directly displays the HTML for display_element, while it returns
           the HTML as a string for sdisplay_element.

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

   Private Functions
       _interp_args()
           Returns HTML::Mason->Interp arguments, with custom tags set.

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

       _custom_preprocess($component, $burner)
           HTML::Mason::Compiler pre-process filter, to allow custom mason
           tags.

           Pre-processor checks the tagset for the context, which can be
           PREVIEW_MODE, BURN_MODE or SYNTAX_MODE, and processes the tags
           according to the context.

           Throws: NONE.

           Side Effects: NONE.

           Notes: NONE.

NOTES
       NONE.

AUTHOR
       Garth Webb gtgarth@perijove.comlt

       Sam Tregar gtstregar@about-inc.comlt

       David Wheeler gtdavid@justatheory.comlt

SEE ALSO
       Bric, Bric::Util::Burner



perl v5.12.2                      2006-09-05     Bric::Util::Burner::Mason(3p)
