
=head1 NAME

HTML::FromMail::Format - base-class for message formatters


=head1 INHERITANCE

 HTML::FromMail::Format
   is a Mail::Reporter

 HTML::FromMail::Format is extended by
   HTML::FromMail::Format::Magic
   HTML::FromMail::Format::OODoc


=head1 SYNOPSIS

 my $fmt  = HTML::FromMail::Format::Magic->new(...);

 my $make = HTML::FromMail->new
  ( templates => ...
  , formatter => 'Magic'
 #, formatter => 'HTML::FromMail::Format::Magic'
 #, formatter => $fmt
  );


=head1 DESCRIPTION

The formatter is implementing the template system: it formats the output.
This base class defines the methods which must be provided by any extension.

At the moment, the following template systems are available:

=over 4

=item * L<HTML::FromMail::Format::OODoc|HTML::FromMail::Format::OODoc>

Based on L<OODoc::Template>, a simplified version of Text::MagicTemplate. It
has all the basic needs of a template system, but may get slow for large
template files.

=item * L<HTML::FromMail::Format::Magic|HTML::FromMail::Format::Magic>

Based on L<Text::MagicTemplate>, created by Domizio Demichelis.
You will have to install Bundle::MagicTemplate before you can use this
formatter.  The default system is compatible with the previous formatter,
so you can easily upgrade.

The formatter has nice simplifications for the user, especially
when a lot own data must be included in the templates: so data with or
without relation to messages which is not provided by this distribution
(yet).

=back



=head1 METHODS


$obj-E<gt>B<containerText>(ARGS)

=over 4

Produces the text encapsulated between begin and end tag of this
template block.  If the tag is "stand alone", not a container, the
value of C<undef> is returned.  When the container is "empty", an
(optionally empty) string with white-spaces is returned.

=back

$obj-E<gt>B<lookup>(TAG, ARGS)

=over 4

Lookup the value for a certain TAG.  This TAG may, but also may not,
be derived from the template.  The value is lookup is the data produced
by the various producer methods, implemented in L<HTML::FromMail::Page|HTML::FromMail::Page>
extensions.  The values are administered by the various formatters,
because there meaning (and for instance their scoping) is formatter
dependent.  Values which are looked-up are often not simple strings.

=back

HTML::FromMail::Format-E<gt>B<new>(OPTIONS)

=over 4

=back

$obj-E<gt>B<onFinalToken>(ARGS)

=over 4

Returns whether the parser has more data in this particular part of
the template.

=back

$obj-E<gt>B<processText>(TEXT, ARGS)

=over 4

New TEXT is supplied, which can be seen as part of the currently active
container.

=back








=head1 REFERENCES

See the HTML::FromMail website at L<http://perl.overmeer.net/html-from-mail/> for more details.

=head1 COPYRIGHTS

Module version 0.01.
Written by Mark Overmeer (mark@overmeer.net).  See the ChangeLog for
other contributors.

Copyright (c) 2003 by the author(s). All rights reserved.  This program
is free software; you can redistribute it and/or modify it under the
same terms as Perl itself.


