RFC: HTML::Template::Dumper

[hardburn]

Inspired by Testing Template, or should I write a diff for TT templates?, I've worked on a subclass for HTML::Template that will dump only the datastructure that would be used to fill in the template. This makes it easy to parse the output for automatic testing tools.

---

• NAME
• SYNOPSIS
• DESCRIPTION
• USAGE
• new
• set_output_format
• output
• parse
• WRITING NEW FORMATTERS
• new
• dump
• parse
• AUTHOR
• COPYRIGHT
• SEE ALSO

---

NAME

  HTML::Template::Dumper - Output template data in a test-friendly format

---

SYNOPSIS

  # Switch the module used to the regular HTML::Template when you're 
  # finished testing
  #
  #use HTML::Template;
  use HTML::Template::Dumper;

  my $tmpl = 
        #HTML::Template
        HTML::Template::Dumper
        ->new( . . . );
  $tmpl->set_output_format( 'YAML' ) if $tmpl->isa( 'HTML::Template::Dumper' );

  # Do processing for the template

  $tmpl->output();

---

DESCRIPTION

This module helps you to test HTML::Template-based programs by printing only the information used to fill-in the template data. This makes it much easier to automatically parse the output of your program. Currently, data can be outputed by Data::Dumper (default) or YAML.

Note that the underlieing HTML::Template methods are still called, so options like strict and die_on_bad_params will still throw errors.

---

USAGE

new

Called just like HTML::Template->new() method.

set_output_format

  $tmpl->set_output_format( 'YAML' );

Set the output format. Currently known formats are:

  Format Name         Module
  -------------       --------
  Data_Dumper         HTML::Template::Dumper::Data_Dumper
  YAML                HTML::Template::Dumper::YAML

The module is found by applying the following rules:

1. If the name has a :: anywhere, then it is taken as the full name of the module.

2. Otherwise, the module is loaded from HTML::Template::Dumper::$NAME, where $NAME is what you passed to set_output_format.

3. If the name didn't have a :: in it, but it didn't pass rule #2, then take it as the full name of the module.

4. If none of the above work, then call die.

In any of the cases, the module returned must inheirt from HTML::Template::Dumper::Format. Otherwise, die is called.

output

Called just like the regular HTML::Template->output(), but will return a simplified view of the template data instead of the full object.

The print_to parameter is respected as specified in the HTML::Template documentation.

parse

Called with the data that was returned by output(). Returns a hashref of all the parameters.

---

WRITING NEW FORMATTERS

Formaters must inheirt from HTML::Template::Dumper::Format. There are two methods used.

new

Not called with anything. Returns a blessed reference. The default implementation blesses a scalar reference in order to save a little memory. This should be sufficient for most formatters, but you can always override this method if you need it.

dump

All formatters must override this method.

It is called with a single reference which is formatted and returned.

parse

All formaters must override this method.

It is called with a single scalar that holds the complete data returned by this formatter's dump method. It returns a hashref of all the parameters held in that dump.

---

AUTHOR

  Timm Murray <[e-mail]>

  http://www.agronomy.org
  CPAN ID: TMURRAY

---

COPYRIGHT

---

SEE ALSO

---

Update: Added readmore tags.

[jdtoronto]

Now thats a cool idea, I haven't yet read the thread that inspired you, but I am embarking on writing some modules of my own and I am thinking that some of this stuff would be useful to include - so the module is easily testable.

Thanks for your inspiration hardburn I thihk it will help my own cause a lot.

jdtoronto

[dws]

I've worked on a subclass for HTML::Template that will dump only the datastructure that would be used to fill in the template.

Cool. I suspect that many of us would end up writing a simple script to drive it, so you would save us the work by including a simple driver script.

[pernod]

Excellent idea. This is something I have been thinking about a lot recently, but your solution seems far more comprehensive than mine (which was more or less to test what went into the template, not what came out, thereby losing a 'dimension' in the test).

May I suggest that you add links to YAML (and Data::Dumper) in the 'See Also' section? It would help those of us who saw YAML Ain't Markup Language (tm) for the first time.

Otherwise: great initiative. Good luck!

pernod
--
Mischief. Mayhem. Soap.

[EvdB]

Being the author of the node you mentioned I am very positive towards this.

However my original node was more about checking that the template behaved correctly, rather than checking the template data itself.

Still, the checking of templates is something that is currently a bit of a hot potato, mainly I think because there is no accepted way to do it. Hopefully this module puts us on the path to getting it sorted.

For Template fans the following code achieves something similar to the above:

if ( $DEBUG_TEMPLATE_DATA ) {
  use YAML;
  print DUMP( $vars );
} else {
  $tt->process( 'file_to_process', $vars );
}