Bric::Util::Burner::PHP(3p)

NAME
Bric::Util::Burner::PHP - Publish stories using PHP templates

VERSION
$LastChangedRevision$

DATE
$LastChangedDate: 2004-11-19 03:55:15 -0500 (Fri, 19 Nov 2004) $

SYNOPSIS
  use Bric::Util::Burner::PHP;

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

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

DESCRIPTION
This module handles burning business story resources (files) PHP templates.

INTERFACE

  Constructors

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

my $encoding = $burner->get_encoding
    Returns the character set encoding to be used to write out the contents of a burn to a file. Defaults to "raw". Note that this is different than the default for the other burners because the "utf8" flag on Perl variables is lost in the conversion to PHP. This should effectively be okay, however, as long as your PHP templates use the "mb_*" functions and identify the encoding as UTF-8. For example:

      $sub = mb_substr($element->get_value('deck'), 0, 255, 'utf-8');

    See <http://us2.php.net/manual/en/ref.mbstring.php> for more information on handling multibyte characters in PHP.

    Throws: NONE.

    Side Effects: NONE.

    Notes: NONE.

$burner = $burner->set_encoding($encoding)
    Sets the character set encoding to be used to write out the contents of a burn to a file. Use this attribute if templates are converting output data from Bricolage's native UTF-8 encoding to another encoding. Use "raw" if your templates are outputting binary data. Defaults to "raw".

    Throws: NONE.

    Side Effects: NONE.

    Notes: NONE.

$resources = $b->burn_one($ba, $oc, $cat);
    Publishes an asset. Returns a list of resources burned. Parameters are:

    *   $ba

        A business asset object to publish.

    *   $oc

        An output channel object to use for the publish

    *   cat

        A category in which to publish.

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 PHP 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.

$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.

$output = $b->sdisplay_element($element)
    A method to be called from template space. This is a "sprint"-likef version of "display_element()", i.e. it returns the output as a string rather than outputting it it as "display_element()" does.

    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.

$burner->_display_container($element)
    Called by "display_element()" and "sidsplay_element()" this method uses the PHP::Interpreter object to execute the element template for a container element.

  Private Functions
None.

NOTES
NONE.

AUTHOR
Garth Webb <garth@perijove.com>

Sam Tregar <stregar@about-inc.com>

David Wheeler <david@justatheory.com>

SEE ALSO
Bric, Bric::Util::Burner