Best practices

phillipadsmith edited this page Aug 16, 2010 · 1 revision
Clone this wiki locally

Friendly error messages

$burner->throw_error('What are you thinking??')

Template layout

I really liked this rational for using a Mason %init block at the bottom of templates (from http://search.cpan.org/~drolsky/HTML-Mason-1.37/lib/HTML/Mason/Devel.pod):

<%init>

This section contains initialization code that executes as soon as the component is called. For example: checking that a user is logged in; selecting rows from a database into a list; parsing the contents of a file into a data structure.

Technically an <%init> block is equivalent to a <%perl> block at the beginning of the component. However, there is an aesthetic advantage of placing this block at the end of the component rather than the beginning.

We’ve found that the most readable components (especially for non-programmers) contain HTML in one continuous block at the top, with simple substitutions for dynamic elements but no distracting blocks of Perl code. At the bottom an <%init> block sets up the substitution variables. This organization allows non-programmers to work with the HTML without getting distracted or discouraged by Perl code. For example:


    <html>
    <head><title><% $headline %></title></head>
    <body>
    <h2><% $headline %></h2>
    <p>By <% $author %>, <% $date %></p>

    <% $body %>

    </body>
    </html>

    <%init>
    # Fetch article from database
    my $dbh = DBI::connect ...;
    my $sth = $dbh->prepare("select * from articles where id = ?");
    $sth->execute($article_id);
    my ($headline, $date, $author, $body) = $sth->fetchrow_array;
    # Massage the fields
    $headline = uc($headline);
    my ($year, $month, $day) = split('-', $date);
    $date = "$month/$day";
    </%init>

    <%args>
    $article_id
    </%args>

Configuration directives

I’ve been finding a few threads related to some extra settings to handle Unicode characters, etc. Seems that this is a useful configuration directive to set:


PERL_LOADER               = use Apache::Util qw(:all); use
Bric::Util::Burner qw(:modes); use Encode; use HTML::Entities;

Also, I found this this one speeding this up noticeably:


# Content compression setting. Enabling this directive makes the Bricolage UI
# Apache process use mod_gzip to compress the UI pages.  This leads to a
# significant reduction in page size (five to fifteen times), which is good
# especially if users work over the Internet rather than only a LAN.
# Disabled by default.

ENABLE_GZIP               = Yes

This is pretty cool too:


# Relateds POD Tag. This directive controls the type of related media and
# related story POD tags that will be generated by the C<serialize_to_pod()>
# method of Bric::Biz::Element::Container and therefore the "Bulk Edit"
# interface in the UI. The tags have the format of '=related_story_*' or
# '=related_media_*', where "*" is drawn from this directive and can be any
# one of: "uuid", "uri", "url", or "id". Defaults to "uuid."

RELATED_DOC_POD_TAG     = uri

Unicode and character encoding

What a hassle. But I’ve had this problem a few times, so I think I’d collect some links:
http://www.justatheory.com/computers/programming/perl/utf8_trials.html
http://marc.info/?t=107812062600002&r=1&w=2
http://marc.info/?t=107911428800003&r=1&w=2

Loading Perl / CPAN modules at start-up

Using Other Perl Modules
Since Bricolage’s templates are all Perl-based (even the PHP templates run inside a PHP interpreter inside a Perl interpreter), it is of course possible to load Perl modules and use them in your templates. You might want to use the DBI to pull data in from another database, or use XML::RSS to burn in headlines from another site. This is one of the great strengths of Bricolage’s templating architecture, and we strongly urge you to exploit it.

However, it’s not efficient to load modules directly in your templates, since every time they’re run, they’ll load the template into a separate Apache process, and therefore use more system resources (memory). It would be better to load all of the modules you’ll need at Bricolage startup time, so that they get shared across processes and therefore use less memory.

With the PERL_LOADER bricolage.conf configuration directive, you can do just that. The PERL_LOADER directive takes, on a single line, an arbitrary line of Perl code, and executes it in the name space reserved for Mason, Template Toolkit, and PHP templates (any exports won’t be available to HTML::Template templates, although any imported modules of course will be). So you can execute a whole bunch of Perl use statements here, and all the modules will be available to you in your templates without needing to reload them there. Here’s an example:

PERL_LOADER = use XML::RSS; use CGI qw(:standard); use Apache::DBI;

Distribution options for large sites

Great thread:
http://marc.info/?t=118962976800001&r=1&w=2

Creating PDFs


>   Much to my surprise I have not been able to find any folks talking
> about pdf or rtf output for content. This will be a big issue for my
> organization. Can anyone point me in the right direction on a "best
> practice" for accomplishing general PDF output would be.

1. Create a "PDF" output channel.
2. Write the templates to use a PDF library from CPAN to generate
    the output. Be sure to load it in PERL_LOADER and use $m->print
    to output it. PDF::API2 looks good. You might also need to parse
    any markup in story content to convert it to whatever PDF needs
    (such as changing <em> to use an italic font).


    http://search.cpan.org/dist/PDF-API2/
    http://search.cpan.org/dist/PDF-API2-Lite/

— Bric.PhillipSmith – 28 Oct 2007