Name

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

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:

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:

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