Bric::Util::Burner - Publishes Business Assets and Deploys Templates

$LastChangedRevision$

$LastChangedDate: 2005-10-26 16:58:52 -0700 (Wed, 26 Oct 2005) $

 use Bric::Util::Burner qw(:modes);

 # Create a new publish object.
 $burner = new Bric::Util::Burner;

 # Deploy a formatting asset.
 $burner = $burner->deploy($formatting_asset);

 # Undeploy a formatting asset.
 $burner = $burner->undeploy($formatting_asset);

 # Burn an asset given an output chanels and category
 $burner->burn_one($asset, $output_channel, $category);

 # set list of page extensions
 $burner->set_page_extensions(@page_extensions);

 # get list of page extensions
 @page_extensions = $burner->get_page_extensions();

 # set page numbering start
 $burner->set_page_numb_start($start);

 # retrieve page numbering start
 $page_numb_start = burner->get_page_numb_start;

This module accomplishes two tasks:

1

Manages the process of deploying and undeploying of formatting assets through CWdeploy() and CWundeploy().

2

Manages the process of publishing and previewing business assets via the CWpublish() and CWpreview() methods, respectively. The actual work of publishing is done by one of Bric::Util::Burner's subclasses depending on the CWburner_type of the asset being published. See Bric::Util::Burner::Mason and Bric::Util::Burner::Template for details.

We anticipate that new Burner subclasses will be added to the system. Here's a brief guide to adding a new Burner to Bricolage:

•

Write Bric::Util::Burner::Foo. You'll need to create a new subclass of Bric::Util::Burner that implements three methods - CWnew(), CWchk_syntax(), and CWburn_one(). You can use an existing subclasses as a model for the interface and implementation of these methods. Make sure that when you execute your templates, you do it in the namespace reserved by the CWTEMPLATE_BURN_PKG directive get this constant by adding

  use Bric::Config qw(:burn);

to your new Burner subclass. Your burner class will also need to call the CW_register_burner() method when it loads. Again, see the existing subclasses for some examples.

•

Modify Bric::Biz::AssetType. To use your Burner you'll need to be able to assign elements to it. To do this edit Bric::Biz::AssetType and add a constant for your burner. For example, Bric::Util::Burner::Template's constant is CWBURNER_TEMPLATE. Next, edit the CWmy_meths() entry for the burner type to include an entry for your constant.

•

Done! Now start testing...

In addition to the class and object methods documented below, Bric::Util::Burner can export a number of constants. These constants are used for comparing the values stored in the CWmode property of a burner object. They can be imported individually, or by using the CW:modes or CW:all export tags. The supported constants are: The burner object is in the process of publishing an asset. The burner object is in the process of previewing an asset. The burner object is in the process of checking the syntax of a template.

$obj = new Bric::Util::Burner($init);

Creates a new burner object. The parameters that can be passed via the CW$init hash reference are: The directory where the Burner stores compiled template files. Defaults to the value stored in the CWBURN_DATA_ROOT directive set in bricolage.conf. ID of the user to get a sandbox to deploy/undeploy templates for previewing. CWsandbox_dir is set from this value. The directory to which the burner deploys and can find templates for burning. Defaults to the value stored in the CWBURN_COMP_ROOT directive set in bricolage.conf. The directory in which the burner writes burned content files upon publication or preview. Defaults to the value stored in the CWBURN_DATA_ROOT directive set in bricolage.conf. Throws: NONE. Side Effects: NONE. Notes: NONE.

$self->DESTROY

Dummy method to prevent wasting time trying to AUTOLOAD DESTROY.

Returns the name of the burner class that handles templates with the extension passed in. The extension must be the full extension name without with the ., such as mc or tmpl. Throws: NONE. Side Effects: NONE. Notes: NONE. Returns the name of the burner class that handles category templates with the base file name passed in. The file name must be the base file name, omitting any exception, such as autohandler or category. Throws: NONE. Side Effects: NONE. Notes: NONE. Returns true if the category template with the base file name CW$filename has a file extension, and false if it doesn't. For example Mason category templates have no extension, so this method returns false for the CW$filename autohandler. On the other hand, HTML::Template templates do have extensions, so this method returns true for the CW$filename category. Throws: NONE. Side Effects: NONE. Notes: NONE. Returns an array reference of array references of burner file name extensions mapped to labels for each. Suitable for use in select widgets. Throws: NONE. Side Effects: NONE. Notes: NONE.

Returns the data directory. Throws: NONE. Side Effects: NONE. Notes: NONE. Sets the data directory. Throws: NONE. Side Effects: NONE. Notes: NONE. Returns the component directory. Throws: NONE. Side Effects: NONE. Notes: NONE. Sets the component directory. Throws: NONE. Side Effects: NONE. Notes: NONE. Returns the output directory. Throws: NONE. Side Effects: NONE. Notes: NONE. Sets the output directory. Throws: NONE. Side Effects: NONE. Notes: NONE. Returns the burn mode. The value is an integer corresponding to one of the following constants: PUBLISH_MODE, PREVIEW_MODE, and SYNTAX_MODE. Throws: NONE. Side Effects: NONE. Notes: NONE. Returns the character set encoding to be used to write out the contents of a burn to a file. Defaults to utf8. Throws: NONE. Side Effects: NONE. Notes: NONE. Sets the character set encoding to be used to write out the contents of a burn to a file under Perl 5.8.0 and later. 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 utf8. Throws: NONE. Side Effects: NONE. Notes: NONE. Returns the story currently being burned that is, during the execution of templates by CWburn_one(). Throws: NONE. Side Effects: NONE. Notes: NONE. Returns the element currently being burned that is, during the execution of the various element templates by CWburn_one(). Throws: NONE. Side Effects: NONE. Notes: NONE. Returns the output channel in which the story returned by CWget_story() is currently being burned. Throws: NONE. Side Effects: NONE. Notes: NONE. Returns the category to which the story returned by CWget_story() is currently being burned. Throws: NONE. Side Effects: NONE. Notes: NONE. Returns the index number of the page that's currently being burned. The index is 0-based. The first page is 0, the second page is 1 and so on. Throws: NONE. Side Effects: NONE. Notes: NONE. Returns the base name used to create the file names of all files created by the current burn. This will have the same value as CW$burner->get_oc->get_filename. Throws: NONE. Side Effects: NONE. Notes: NONE. Returns the filename extension used to create the file names of all files created by the current burn. This will have the same value as CW$burner->get_oc->get_file_ext. Throws: NONE. Side Effects: NONE. Notes: NONE. Returns the local file system path to the directory that will be used as the base path for all files written for documents within a given output channel. Throws: NONE. Side Effects: NONE. Notes: NONE. Returns the local file system path to the directory into which all files created by the current burn will be written. Throws: NONE. Side Effects: NONE. Notes: NONE. Returns the base URI to the directory into which all files created by the current burn will be written. Throws: NONE. Side Effects: NONE. Notes: NONE. Sets page extensions to be used during burning. Will revert to page numbering once the extensions are all used. Each of the page extensions passed must be unique or an exception will be thrown. Throws: NONE. Side Effects: NONE. Notes: Example:

   $burner->set_page_extensions(qw(intro main conc));
   $burner->display_pages('page');

$burner->publish_another($ba);

  $burner->publish_another($ba);
  $burner->publish_another($ba, $publish_time);
  $burner->publish_another($ba, $publish_time, $anytime);

Designed to be called from within a template, this method publishes a document other than the one currently being published. This is useful when a template for one document type needs to trigger the publish of another document. Look up that document via the Bricolage API and then pass it to this method to have it published at the same time as the story currently being published. If the mode isn't CWPUBLISH_MODE or if the document passed in is the same story as the currently burning story, the publish will not actually be executed. Pass in a DateTime string to specify a different date and time to publish the document. If that date is in the future, a publish job will be schedule at that time. Pass in a true value as the third argument to trigger the publish in any mode, including CWPREVIEW_MODE (not recommended). Note that any values stored in the CWnotes attribute of the current burner will be copied to the new burner that burns the new document, unless the CW$publish_time agrument schedules the document to be published at a future time. Throws: NONE. Side Effects: NONE. Notes: NONE. Publishes an asset. Returns a list of resources burned. Parameters are: A business asset object to publish. The output channel to which to burn the asset. A category in which to burn the asset. Throws: NONE. Side Effects: NONE. Notes: NONE. Compiles the template found in CW$ba. If the compile succeeds with no errors, chk_syntax() returns true. Otherwise, it returns false, and the error will be in the CW$err varible passed by reference. Throws: NONE. Side Effects: NONE. Notes: NONE.

  % # Mason syntax.
  % my $page_file = $burner->page_file($number);
  <a href="<% $page_file %>">Page Number <% $number %></a>

Returns the file name for a page in a story as the story is being burned. The page number must be greater than 0. Throws:

*

Page number not greater than zero. Side Effects: NONE. Notes: This method does not check to see if the page number passed in is actually a page in the story. Caveat templator.

  % # Mason syntax.
  % my $page_uri = $burner->page_uri($number);
  <a href="<% $page_uri %>">Page Number <% $number %></a>

Returns the URI for a page in a story as the story is being burned. The page number must be greater than 0. Throws:

*

Page number not greater than zero. Side Effects: NONE. Notes: This method does not check to see if the page number passed in is actually a page in the story. Caveat templator. Returns the complete local file system file name for a page in a story as the story is being burned. The page number must be greater than 0. Throws:

*

Page number not greater than zero. Side Effects: NONE. Notes: This method does not check to see if the page number passed in is actually a page in the story. Caveat templator.

  % if (my $prev = $burner->prev_page_file) {
      <a href="<% $prev %>">Previous Page</a>
  % }

Returns the file name for the previous file in a story as the story is being burned. If there is no previous file, CWprev_page_file() returns undef. Throws: NONE. Side Effects: NONE. Notes: NONE.

  % if (my $prev = $burner->prev_page_uri) {
      <a href="<% $prev %>">Previous Page</a>
  % }

Returns the URI for the previous file in a story as the story is being burned. If there is no previous URI, CWprev_page_uri() returns undef. Throws: NONE. Side Effects: NONE. Notes: NONE.

  % if (my $next = $burner->next_page_file) {
      <a href="<% $next %>">Next Page</a>
  % }

Returns the file name for the next file in a story as the story is being burned. If there is no next file, CWnext_page_file() returns undef. Throws: NONE. Side Effects: NONE. Notes: NONE.

  % if (my $next = $burner->next_page_uri) {
      <a href="<% $next %>">Next Page</a>
  % }

Returns the URI for the next file in a story as the story is being burned. If there is no next URI, CWnext_page_uri() returns undef. Throws: NONE. Side Effects: NONE. Notes: NONE.

  % if (my $rel_story = $element->get_related_story) {
      <a href="<% $burner->best_uri($rel_story)->as_string %>">
        <% $rel_story->get_title %>
      </a>
  % }

Returns a URI object representing Bricolage's best guess as to the appropriate URI to use to link to the story or media object passed as an argument. See the URI docs for information on its interface. The semantics that CWbest_uri() uses to create the URI are as follows: First, it checks to see if the asset's Site ID is the same as the the Site ID for the current output channel. If it is, then the URI is returned without the protocol or server name, but formatted for either the current output channel or for the document's primary output channel. If the document isn't in the current output channel's site, CWbest_uri() looks for an alias to the document in the current output channel's site. If there is one the alias is used to create the URI, and the URI is returned without the protocol or server name, but formatted for either the current output channel or for the alias' primary output channel. And finally, if the document is in another site and there is no alias in the current site, CWbest_uri() will return a full URI with the prtocol and the document's site's domain name, formatted according to the settings of the document's primary output channel. Throws: NONE. Side Effects: NONE. Notes: NONE.

$burner->notes

  my $notes = $burner->notes;
  while (my ($k, $v) = each %$notes) {
      print "$k => $v\n";
  }

  my $last = 10;
  $burner->notes( last_story => $last );
  $last = $burner->notes('last_story');

The CWnotes() method provides a place to store burn data data, giving template developers a way to share data among multiple burns over the course of publishing a single story in a single category to a single output channel. Any data stored here persists for the lifetime of the burner object, as well as to any burners generated by calls to CWpublish_another() or CWpreview_another(). Use CWclear_notes() to manually clear the notes. Conceptually, CWnotes() contains a hash of key-value pairs. CWnotes($key, $value) stores a new entry in this hash. CWnotes($key) returns a previously stored value. CWnotes() without any arguments returns a reference to the entire hash of key-value pairs. CWnotes() is similar to the mod_perl method CW$r->pnotes(). The main differences are that this CWnotes() can be used in a non-mod_perl environment (such as when a story is published by bric_queued), and that its lifetime is tied to the lifetime of the burner object. Throws: NONE. Side Effects: NONE. Notes: NONE.

$burner->clear_notes

  $cb_request->clear_notes;

Use this method to clear out the notes hash. Throws: NONE. Side Effects: NONE. Notes: NONE.

$burner->throw_error($message);

  my $media = $element->get_related_media
    or $burner->throw_error("Hey, you forgot to associate a media document!");

Throws a Bric::Util::Fault::Exception::Burner::User exception. The error message passed as an argument will be displayed in the UI so that your user can see any mistakes you caught and fix them. Throws: NONE. Side Effects: NONE. Notes: NONE.

__PACKAGE__->_register_burner(@args)

  __PACKAGE__->_register_burner( Bric::Biz::AssetType::BURNER_TEMPLATE,
                                 category_fn => 'category',
                                 exts        =>
                                   { 'pl'   => 'HTML::Template Script (.pl)',
                                     'tmpl' => 'HTML::Template Template (.tmpl)'
                                   }
                               );

Protected method only called by Burner subclasses when they're loaded. This method registers the subclasses, along with their Bric::Biz::AssetType constants, file names, and file extenstions. Note that the CWcategory_fn and must be unique among all burners, as must the file extensions passed via the CWexts directive. Throws: NONE. Side Effects: NONE. Notes: NONE.

$burner->_get_subclass($ba)

Returns the subclass of Bric::Util::Burner appropriate for handling the CW$ba template object. Throws: NONE. Side Effects: NONE. Notes: NONE.

NONE.

Garth Webb <garth@perijove.com>

Sam Tregar <stregar@about-inc.com>

Matt Vella <mvella@about-inc.com>

David Wheeler <david@wheeler.net>

Bric, Bric::Util::Burner::Mason, Bric::Util::Burner::Template.