DADA::App::FormatMessages

- NAME
- SYNOPSIS
- DESCRIPTION
- METHODS

- new
- format_headers_and_body

- ACCESSORS

- Subject
- use_list_template
- use_email_templates
- treat_as_discussion_msg
- use_header_info

- PRIVATE METHODS

- _fix_for_only_html_part
- _format_text
- _create_multipart_from_html
- _make_multipart
- _create_plaintext_from_html
- _format_headers
- _list_name_subject
- _parse_in_list_info
- _macro_tags
- _apply_template
- _apply_list_template

- get_entity
- email_template
- COPYRIGHT

# NAME

DADA::App::FormatMessages

# SYNOPSIS

     my $fm = DADA::App::FormatMessages->new(-List => $list);

     # The subject of the message is...
       $fm->Subject('This is the subject!');

     # Use information you find in the headers
      $fm->use_header_info(1);

     # Use the list template
       $fm->use_list_template(1);

     # Use the email template.
       $fm->use_email_templates(1);

     # Consider this message as if it's from a discussion list
       $fm->treat_as_discussion_msg(1);

     my ($header_str, $body_str) = $fm->format_headers_and_body(-msg => $msg);

     # (... later on...

     use DADA::MAilingList::Settings;
     use DADA::Mail::Send;

     my $ls = DADA::MailingList::Settings->new({-list => $list});
     my $mh = DADA::Mail::Send->new({-list => $list});

     $mh->send(
               $mh->return_headers($header_str),
                       Body => $body_str,
                      );

# DESCRIPTION

DADA::App::FormatMessages is used to get a email message ready for sending to your mailing list. Most of its magic is behind the scenes, and isn't something you have to worry about, but we'll go through some detail.

# METHODS

## new

     my $fm = DADA::App::FormatMessages->new(-List => $list);

## format_headers_and_body

     my ($header_str, $body_str) = $fm->format_headers_and_body(-msg => $msg);

Given a string, $msg, returns two variables; $header_str, which will have all the headers and $body_str, that holds the body of your message.

# ACCESSORS

## Subject

Set the subject of a message

## use_list_template

If set to a true value, will apply the list template to the HTML part of your message

## use_email_templates

If set to a true value, will apply your email templates to the HTML/PlainText parts of your message.

## treat_as_discussion_msg

When set to a true value, will try the message as if it was from a discussion list.

## use_header_info

If set to a true value, will inspect the headers of a message (for example, the From: line) to work with

# PRIVATE METHODS

## _fix_for_only_html_part

     $entity = $self->_fix_for_only_html_part($entity);

Changes the single part, HTML entity into a multipart/alternative message, with an auto plaintext version.

## _format_text

     $entity = $self->_format_text($entity);

Given an MIME::Entity (may be multipart) will attempt to:

- Apply the List Template
- Apply the Email Template
- interpolate the message to change Dada Mail's pseudo tags to their real value

## _create_multipart_from_html

     $entity = $self->_create_multipart_from_html($entity);

Recursively goes through a multipart entity, changing any non-attachment singlepart HTML message into a multipart/alternative message with an auto-generated PlainText version.

## _make_multipart

     $entity = $self->_make_multipart($entity);

    Takes a single part entity and changes it to a multipart/alternative message,
    with an autogenerated PlainText version.

## _create_plaintext_from_html

     my $PlainText_var = $self->_create_plaintext_from_html($HTML_Ver);

     Given a B<string>, simple converts the HTML to PlainText

## _format_headers

     $entity = $self->_format_headers($entity)

Given an entity, will do some transformations on the headers. It will:

- Tack on the list name/list shortname on the Subject header for discussion lists
- Add the correct Reply-To header
- Remove any Message-ID headers
- Makes sure the To: header has a real name associated with it

## _list_name_subject

     my $subject = $self->_list_name_subject($list_name, $subject));

Appends, $list_name onto subject.

## _parse_in_list_info

     $data = $self->_parse_in_list_info(-data => $data,
                                        -type => (PlainText/HTML),
                                       );

    Given a string, changes Dada Mail's pseudo tags into what they represent.

-type can be either PlainText or HTML

## _macro_tags

     my $s_link   = $self->_macro_tags(-type => 'subscribe'  );
     my $us_link  = $self->_macro_tags(-type => 'unsubscribe');

Explode the various link pseudo tags into a form that will later be interpolated.

-type can be:

- subscribe
- unsubscribe
- confirm_subscribe
- confirm_unsubscribe

## _apply_template

$content = $self->_apply_template(-data => $content,
| -type => $entity->head->mime_type,
| );

Given a string in -data, applies the correct email mailing list template, depending on what -type is passed, this will be either the PlainText or HTML version.

## _apply_list_template

     $new_data = $self->_apply_list_template($new_data);

Given a string, will apply the List Template. The List Template is usually used for HTML screens that appear in your web browser.

# get_entity

`get_entity` is a simple subroutine that takes a string, passed in, `-data` and turns it into a HTML::Entities entity:

     my $entity = get_entity(
                      {
                          -data => $str,
                      }
                  );

Optionally, you may also pass the `-parser_params` paramater, which will direct the parser on how specifically to parse the message. Currently, there is only one param to play around with: `-input_mechanism` - you can set this to either, parse (which is the default), or parse_open.

If you pass, parse_open, also pass a filename in -data instead of a string. Right.

my $entity = get_entity( { -data => $filename, } );

Make sure to delete the file when you're finished.

# email_template

This subroutine is extremely similar to DADA::Template::Widgets `screen` subroutine and in fact is basically a wrapper around it, although it also ``knows'' about Email Message headers and attempts not to muck them up when you place variables in the template.

It basically looks at the various parts of your email message and passes these parts to DADA::Template::Widgets `screen` subroutine to be templated out.

The parts of the email message that will be templated out are any and all text/plain, text/html bodies - both of which have an inline content disposition (ie: it's not an attachment) and the To, From and Subject headers of a message.

For the To and From headers, this subroutine will only attempt to template out the phrase part of the header and will make sure that the phrase is properly escaped out.

One main difference between this subroutine and `screen` is that this subroutine does not take the template to work with in the `-data`, or, `-screen` paramater, but instead takes it in the, `-entity` paramater. The `-entity` paramater should be populated like so:

     use MIME::Parser;
     my $parser = new MIME::Parser;
     my $entity = $parser->parse_data($msg);

     DADA::App::FormatMessages::email_template({-entity => $entity});

( Probably should elaborate...)

The subroutine also passes the `-dada_pseudo_tag_filter` (set to 1) automatically to `screen`.

# COPYRIGHT

Copyright (c) 1999-2008 Justin Simoni All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.