/ 
Taco-0.03
/ Taco::Template

NAME

Taco::Template.pm - Taco templates

SYNOPSIS

use Taco::Template;

$template = new Taco::Template( 'Howdy, [[$name]]!' );
$template->output($buffer);
$string = $template->interpret;
$string2 = &Taco::Template::interpret( 'And hello, [[$name2]]!' );
# ... etc.

DESCRIPTION

This module is a class implementing fill-in templates for Taco. It provides support for streaming the output of a filled-in template. The specific syntaxes of the tags are not defined in this class, so it is extensible and flexible.

Functions and Methods

  • new Taco::Template($text);

    Creates a new Template object whose content is the given text.

  • find Taco::Template('name')

    Searches $G::params for an entry called 'name_text' or 'name_template'. Returns a template whose content is the value of 'name_text', or whose content is the contents of the file referred to by 'name_template'. If neither is found, returns the undefined value.

    May be called with an optional second argument, which is a reference to a scalar variable. This scalar will be set to the string 'text' if the 'name_text' parameter is found, or 'template' if the 'name_template' parameter is found, or the undefined value if neither is found:

    my $template = find Taco::Template('name', \$kind);
if ($kind eq 'text') ...

    Note that if no suitable parameter is found in $G::params, no error will be printed to STDERR. This allows you the flexibility to write code like this:

    # Template is required:
my $template = find Taco::Template('display')
   or die ("Couldn't find 'display_template' or 'display_text'");

# Template is optional:
my $template = find Taco::Template('wrapping');
if ($template) {
   # ... do something with $template ...
}

  • $template->get_text()

    Returns the content of the template object.

  • $template->set_text('text blah [[$blah]]')

    Sets the content of the template to the given text.

  • $template->get_file('filename')

    Puts the contents of the file 'filename' into the template's content. If the filename has a leading slash, it is treated as an absolute filename. If it does not, get_file will search the directories in the template's path for the given file.

    See also set_path.

  • $template->set_path('dir1', 'dir2', ...);

    Sets the path for the get_file method. If called as an object method, will set the path for just the given template. If called as a static class method, will set the default path for all templates:

    Taco::Template->set_path('/etc/templates');   # sets default path
$my_templ->set_path('/etc/templates');  # only sets path for $my_templ

  • $template->set_property( name => 'property')

  • $template->get_property('name')

    The user of a template may wish to set some attribute of a template, and later retrieve that attribute. These methods let you do so. This is useful to achieve small extensions to the functionality of the templates without having to derive a new class.

  • $template->output($buffer)

  • &Taco::Template::output($text, $buffer)

    Interprets and outputs the contents of the template. Checks a flag to see whether printing is okay, or whether output should be added to the end of the buffer. Typically, output will be buffered in nested tags:

    ____________ outer.tmpl: ________________________________
[[ &list( key=[[&parse(parse_template=inner.tmpl)]] ) ]]
____________ inner.tmpl: ________________________________
this is the key's value
_________________________________________________________

    Since &parse is called inside &list, it must not print its output, it must return it. The Template class keeps track of when it's okay to print, and when a routine must return its output instead. In this way, output can be streamed as much as possible.

    If the first argument to output is a reference, then this argument will be treated as a template object. Otherwise, it will be treated as a string.

    Here is a simple example of a routine that uses output:

     sub do_something {
	my $template  = find Taco::Template('stuff') or die ("Can't find my stuff");
	my $buffer;
	
	&Taco::Template::output('<ol start=[[$num]]>', $buffer);
	# Instead of: print &Taco::Template::interpret('<ol start=[[$num]]>');

	$template->output($buffer);
	# Will append text to $buffer if necessary
	
	&Taco::Template::straight_output('</ol>', $buffer);
	
	return $buffer;
 }

  • $template->straight_output($buffer)

  • &Taco::Template::straight_output($text, $buffer)

    Identical to output, except the text will not be interpreted as a template, it will be output directly (or appended to $buffer). This is useful for outputting chunks of text quickly when you know there are no tags in it:

    &Taco::Template::straight_output("</ol>\n", $buffer);

  • $template->interpret

  • &Taco::Template::interpret( $text )

    Returns the parsed contents of the template or text. Will not print anything (assuming the functions called in the template are well-behaved and use Taco::Template::output and the like).

Controlling template syntax and execution

  • &Taco::Template::set_chunker( char, \&routine );

    Sets the chunker for the given character. The chunker will be called when building the syntax tree for a template. A chunker routine takes two arguments: the character (such as $ or &) of the type of template call, and the text of the template call, with leading and trailing delimiters and whitespace removed. For instance, with the following in a template:

    [[ &burp(because=have_gas) ]]

    The chunker will receive '&' as its first argument, and 'burp(because=have_gas)' as its second argument.

    A chunker function should parse the text into a hash reference, which includes a 'type' field equal to the chunker's first argument. The rest of the hash can have whatever structure the executor of that hook will need to execute it (see set_executor). The chunker returns a single argument, the hash reference with the 'type' field.

    Here is an example of a chunker which handles tags like [[ $var ]]:

    sub chunk_variable {
  # returns {type=>'$', name=>'whatever'}

  my $type = shift;
  my $text = shift;
  return {
     type=>$type,
     name=>&Taco::Template::interpret($text),  
                  # So we can handle things like [[ $var[[$two]] ]].
                  # If we didn't need to, we could just do name=>$text.
  };
}

  • &Taco::Template::set_executor( char, \&routine );

    Sets the executor function for the given character. The executor will be called to interpret the value of a template tag. It takes one argument, a hash reference created by a chunker. The executor should return a string which is the result of executing the given tag.

SEE ALSO

Have a look at Taco::Dispatcher.pm if you're want to see the chunker and executor functions. They govern the syntax and execution of the individual tags.

AUTHOR

Ken Williams (ken@forum.swarthmore.edu)

Copyright (c) 1998 Swarthmore College. All rights reserved.