/ 
MIME-Lite-HTML-1.4
River stage one • 1 direct dependent • 1 total dependent
/ MIME::Lite::HTML

NAME

MIME::Lite::HTML - Provide routine to transform a HTML page in a MIME-Lite mail

SYNOPSIS

use MIME::Lite::HTML;

my $mailHTML = new MIME::Lite::HTML
   From     => 'MIME-Lite@alianwebserver.com',
   To       => 'alian@saturne',
   Subject => 'Mail in HTML with images';

$MIMEmail = $mailHTML->parse('http://www.alianwebserver.com');
$MIMEmail->send; # or for win user : $mail->send_by_smtp('smtp.fai.com');

VERSION

$Revision: 1.4 $

DESCRIPTION

This module is a Perl mail client interface for sending message that support HTML format and build them for you.. This module provide routine to transform a HTML page in MIME::Lite mail. So you need this module to use MIME-Lite-HTML possibilities

What's happen ?

The job done is:

  • Get the file (LWP) if needed

  • Parse page to find include images

  • Attach them to mail with adequat header if asked (default)

  • Include external CSS,Javascript file

  • Replace relative url with absolute one

  • Build the final MIME-Lite object with each part found

Usage

Did you alread see link like "Send this page to a friend" ?. With this module, you can do script that to this in 3 lines.

It can be used too in a HTML newsletter. You make a classic HTML page, and give just url to MIME::Lite::HTML.

Construction

MIME-Lite-HTML use a MIME-Lite object, and RFC2257 construction:

If images and text are present, construction use is:

--> multipart/alternative
------> text/plain
------> multipart/related
-------------> text/html
-------------> each images

If no images but text is present, this is that:

---> multipart/alternative
-------> text/plain if present
-------> text/html

If images but no text, this is:

---> multipart/related
-------> text/html
-------> each images

If no images and no text, this is:

---> text/html

Documentation

Additionnal documentation can be found here:

  • MIME-lite module

  • RFC 822, RFC 1521, RFC 1522 and specially RFC 2257 (MIME Encapsulation of Aggregate Documents, such as HTML)

Clients tested

HTML in mail is not full supported so this module can't work with all email clients. If some client recognize HTML, they didn't support images include in HTML. So in fact, they recognize multipart/relative but not multipart/related.

Netscape Messager (Linux-Windows)

100% ok

Outlook Express (Windows-Mac)

100% ok. Mac work only with Content-Location header. Thx to Steve Benbow for give mr this feedback and for his test.

Eudora (Windows)

If this module just send HTML and text, (without images), 100% ok.

With images, Eudora didn't recognize multipart/related part as describe in RFC 2257 even if he can read his own HTML mail. So if images are present in HTML part, text and HTML part will be displayed both, text part in first. Two additional headers will be displayed in HTML part too in this case. Version 1.0 of this module correct major problem of headers displayed with image include in HTML part.

KMail (Linux)

If this module just send HTML and text, (without images), 100% ok.

In other case, Kmail didn't support image include in HTML. So if you set in KMail "Prefer HTML to text", it display HTML with images broken. Otherwise, it display text part.

Pegasus (Windows)

If this module just send HTML and text, (without images), 100% ok.

Pegasus didn't support images in HTML. When it find a multipart/related message, it ignore it, and display text part.

If you find others mail client who support (or not support) MIME-Lite-HTML module, give me some feedback ! If you want be sure that your mail can be read by maximum of people, (so not only OE and Netscape), don't include images in your mail, and use a text buffer too. If multipart/related mail is not recognize, multipart/alternative can be read by the most of mail client.

Public Interface

new(%hash)

Create a new instance of MIME::Lite::HTML.

The hash can have this key : [Proxy], [Debug], [IncludeType], [HashTemplate]

Proxy is url of proxy to use. Ex: 'Proxy' => 'http://192.168.100.166:8080'

Debug is trace to stdout during parsing. Ex: 'Debug' => 1

IncludeType is method to use when finding images:

location

Default method is embed them in mail whith 'Content-Location' header.

cid

You use a 'Content-CID' header.

extern

Images are not embed, relative url are just replace with absolute, so images are fetch when user read mail. (Server must be reachable !)

$hash{'HashTemplate'} is a reference to a hash. If present, MIME::Lite::HTML will substitute <? $name ?> with $hash{'HashTemplate'}{'name'} when parse url to send. $hash{'HashTemplate'} can be used too for include data for subelement. Ex: $hash{'HashTemplate'}{'http://www.al.com/images/sommaire.gif'}=\@data; or $hash{'HashTemplate'}{'http://www.al.com/script.js'}="alert("Hello world");;

When module find the image http://www.alianwebserver.com/images/sommaire.gif in buffer, it don't get image with LWP but use data found in $hash{'HashTemplate'}.

Others keys are use with MIME::Lite constructor.

This MIME-Lite keys are: Bcc, Encrypted, Received, Sender, Cc, From, References, Subject, Comments, Keywords, Reply-To To, Content-*, Message-ID,Resent-*, X-*,Date,MIME-Version,Return-Path, Organization

parse($html, [$url_txt], [$url_base])

Subroutine used for created HTML mail with MIME-Lite

Parameters:

$html

Url of HTML file to send, can be a local file. If $url is not an url (http or https or ftp or file or nntp), $url is used as a buffer. Example : http://www.alianwebserver.com, file://c|/tmp/index.html or '<img src=toto.gif>'.

$url_txt

Url of text part to send for person who doesn't support HTML mail. As $html, $url_txt can be a simple buffer.

$url_base

$url_base is used if $html is a buffer, for get element found in HTML buffer.

Return the MIME::Lite part to send

size()

Display size of mail in characters (so octets) that will be send. (So use it *after* parse method). Use this method for control size of mail send, I personnaly hate receive 500k by mail. I pay for a 33k modem :-(

Private methods

build_mime_object($html,[$txt],[@mail])

(private)

Build the final MIME-Lite object to send with each part read before

$html

Buffer of HTML part

$txt

Buffer of text part

@mail

List of images attached to HTML part. Each item is a MIME-Lite object.

See "Construction" in "Description" for know how MIME-Lite object is build.

include_css($gabarit,$root)

(private)

Search in HTML buffer ($gabarit) to remplace call to extern CSS file with his content. $root is original absolute url where css file will be found.

include_javascript($gabarit,$root)

(private)

Search in HTML buffer ($gabarit) to remplace call to extern javascript file with his content. $root is original absolute url where javascript file will be found.

input_image($gabarit,$root)

(private)

Search in HTML buffer ($gabarit) to remplace input form image with his cid

Return final buffer and list of MIME::Lite part

(private)

Replace link to formulaire with absolute link

fill_template($masque,$vars)
$masque : Path of template
$vars : hash ref with keys/val to substitue

Give template with remplaced variables Ex: if $$vars{age}=12, and $masque have

J'ai <? $age ?> ans,

this function give:

J'ai 12 ans,

Error Handling

The set_err routine is used privately. You can ask for an array of all the errors which occured inside the parse routine by calling:

@errors = $mailHTML->errstr;

If no errors where found, it'll return undef.

AUTHOR

Alain BARBET alian@alianwebserver.com