Jason Kohles > Class-DBI-Template-0.03 > Class::DBI::Template

Download:
Class-DBI-Template-0.03.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  0
View/Report Bugs
Module Version: 0.03   Source  

NAME ^

Class::DBI::Template - Perl extension using Template Toolkit to render Class::DBI objects

SYNOPSIS ^

  package Music::DBI;
  use base 'Class::DBI';
  use Class::DBI::Template;
  Music::DBI->connection('dbi:mysql:dbname','username','password');
  Music::DBI->template_configure(
    INCLUDE_PATH       => '/search/path',
    PRE_CHOMP          => 1,
    POST_CHOMP         => 1,
  );

  package Music::Artist;
  use base 'Music::DBI';
  Music::Artist->table('artist');
  Music::Artist->columns(All => qw/artistid name/);
  Music::Artist->has_many(cds => 'Music::CD');
  Music::Artist->template_define(cd_listing => <<"END");
  [% INSERT header %]

  <h1>CD Listing for [% name %]</h1>

  [% FOR cd = cds %]
    [% cd.render_template('cd_mini_info') %]
  [% END %]

  [% INSERT footer %]
  END

  package Music::CD;
  use base 'Music::DBI';
  Music::CD->table('cd');
  Music::CD->columns(All => qw/cdid artist title year/);
  Music::CD->has_many(tracks => 'Music::Track');
  Music::CD->has_a(artist => 'Music::Artist');
  Music::CD->might_have(liner_notes => LinerNotes => qw/notes/);
  Music::CD->template_define(cd_mini_info => \*DATA);
  __DATA__
  <h1>[% title %]</h1>
  <hr>
  <h2><a href="artist.cgi?artist=[% artist.id %]">[% artist %]</a></h2>

  <ul>Tracks
  [% FOR track = tracks %]
    <li><a href="track.cgi?track=[% track.id %]">[% track.title %]</a>
  [% END %]
  </ul>

  [% IF liner_notes %]
    <blockquote>[% liner_notes %]</blockquote>
  [% END %]

  #-- Meanwhile, in a nearby piece of code! --#

  use strict;
  use CGI;
  my $cgi = new CGI;
  my $artist = Music::Artist->retrieve($cgi->param('artist'));
  print $cgi->header,$artist->template_render('cd_listing');

DESCRIPTION ^

This module provides a tie between Class::DBI and the Template Toolkit. It allows you to specify templates which can be used to render the data available in the module in various ways.

EXPORT ^

template_define($template_name, $template);

The template_define() method takes two arguments, the name of the template, which will be used to refer to it when rendering, and the template data. The name is a simple string (or anything which can be used as a hash key), and the value is any value that will be accepted by the Template module as a template to be rendered.

template_configure(%template_configuration_options);

The template_configure method is used to pass configuration options to the Template modules new() method. It takes a hash of configuration options, and these are passed verbatim to Template->new().

template_render($template_name, [$var1 => $value1, ...]);

The template_render method takes the name of the template to render, and returns the template rendered with the data from the current form. After the template name you can pass a hash of additional data to be added to the data available to the template and of configuration options for the rendering. Any arguments passed in the hash which contain a key that starts with a - are considered to be configuration options. Arguments starting with anything else will be passed to the template.

Note that if the value you pass as a $template_name was not defined as the name of a template using template_define(), $template_name will be passed verbatim to the Template module for rendering. This means that if you setup your template configuration appropriately, you don't even need to predeclare your templates. For example, using the classes defined above, you could do this:

  #!/usr/bin/perl -w
  use strict;
  use warnings;
  use Music::Artist;

  my $artist = Music::Artist->retrieve(1);
  $artist->render('artist_photograph');

Even though the template 'artist_photograph' was never defined, this will work if a file called artist_photograph can be found in the template search path that was defined.

template_data($key => $value[, $key2 => $value2 ...]);

The template_data method takes a hash of data to be added to the variables that are passed to your template for rendering. By default the data will contain only the fields from the database, and some supporting variables.

As an example, if you want access to the environment variables from your template, you could add:

  # not such a good example
  __PACKAGE__->template_data(ENV => \%ENV);

Beware of this practice in long-running or time sensitive applications however. This is probably not a good idea in a mod_perl environment, for example, because the data you will get will be the environment that was in effect at compile time, not at run time. If you need to add data that may change at run time, you are better off providing a subroutine reference that can generate and return the data you need. This also makes things a bit faster, by not doing any of the work of generating that data until the template actually uses it.

  # better example
  __PACKAGE__->template_data(ENV => sub { return \%ENV });

CONFIGURATION ^

In addition to specifying configuration options for the Template module when you call template_configure(), there are also some Class::DBI::Template configuration options you can use.

STASH_ORDER

The STASH_ORDER configuration option will be passed to the Class::DBI::Template::Stash object being created. Refer to the documentation for that module for more details.

STASH_PRELOAD

HINTS, TIPS, and TRICKS ^

SEE ALSO ^

perldoc Class::DBI
perldoc Class::DBI::Template::Stash
perldoc Template
http://www.template-toolkit.org/
http://www.jasonkohles.com/

AUTHOR ^

Jason Kohles <email@jasonkohles.com>

COPYRIGHT AND LICENSE ^

Copyright (C) 2004 by Jason Kohles

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.4 or, at your option, any later version of Perl 5 you may have available.

syntax highlighting: