NAME¶
MIME::Lite::HTML - Provide routine to transform a HTML page in a MIME-Lite mail
SYNOPSIS¶
perl -MMIME::Lite::HTML -e '
new MIME::Lite::HTML
From => "MIME-Lite\@alianwebserver.com",
To => "alian\@cpan.org",
Url => "http://localhost/server-status";'
VERSION¶
$Revision: 1.23 $
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 (gif, jpg, flash)
- •
- 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 RFC2557 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 2557 (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 2557 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.
Install on WinX with ActiveState / PPM¶
Just do in DOS "shell":
c:\ ppm
> set repository alian http://www.alianwebserver.com/perl/CPAN
> install MIME-Lite-HTML
> quit
How know when next release will be ?¶
Subscribe on
http://www.alianwebserver.com/cgi-bin/news_mlh.cgi
Public Interface¶
- new(%hash)
- Create a new instance of MIME::Lite::HTML.
The hash can have this key : [Url], [Proxy], [Debug], [IncludeType],
[HashTemplate], [LoginDetails], [TextCharset], [HTMLCharset],
[TextEncoding], [HTMLEncoding], [remove_jscript]
- Url
- ... is url to parse and send. If this param is found, call
of parse routine and send of mail is done. Else you must use parse routine
of MIME::Lite::HTML and send of MIME::Lite.
- Proxy
- ... is url of proxy to use.
Eg: Proxy => 'http://192.168.100.166:8080'
- remove_jscript
- if set, remove all script code from html source
Eg: remove_jscript => 1
- Debug
- ... is trace to stdout during parsing.
Eg: 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. Eg:
$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'}. (See eg/example2.pl)
- LoginDetails
- ... is the couple user:password for use with restricted
url.
Eg: LoginDetails => 'my_user:my_password'
- TextCharset
- ... is the character set to use for the text part.
Eg: TextCharset => 'iso-8859-7'
for Greek. If none specified, the default is used (iso-8859-1).
- HTMLCharset
- ... is the character set to use for the html part.
Eg: HTMLCharset => 'iso-8859-7'
for Greek. If none specified, the default is used (iso-8859-1). Take care,
as that option does NOT change the character set of the HTML page, it only
changes the character set of the mime part.
- TextEncoding
- ... is the Encoding to be used for the text part (if such a
part exists). If none specified, the default is used (7bit).
Eg: TextEncoding => 'base64'
- HTMLEncoding
- ... is the Encoding to be used for the html part. If none
specified, the default is used (quoted-printable).
Eg: HTMLEncoding => 'base64'.
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
<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.
- create_image_part($url)
- (private)
Fetch if needed $url, and create a MIME part for it.
- 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
- link_form($gabarit,$root)
- (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.
CGI Example¶
#!/usr/bin/perl -w
# A cgi program that do "Mail this page to a friend";
# Call this script like this :
# script.cgi?email=myfriend@isp.com&url=http://www.go.com
use strict;
use CGI qw/:standard/;
use CGI::Carp qw/fatalsToBrowser/;
use MIME::Lite::HTML;
my $mailHTML = new MIME::Lite::HTML
From => 'MIME-Lite@alianwebserver.com',
To => param('email'),
Subject => 'Your url: '.param('url');
my $MIMEmail = $mailHTML->parse(param('url'));
$MIMEmail->send; # or for win user : $mail->send_by_smtp('smtp.fai.com');
print header,"Mail envoye (", param('url'), " to ", param('email'),")<br>\n";
TERMS AND CONDITIONS¶
Copyright (c) 2000 by Alain BARBET alian (at) cpan.org
All rights reserved. This program is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.
This software comes with
NO WARRANTY of any kind. See the COPYING file in
the distribution for details.
AUTHOR¶
Alain BARBET alian@cpan.org , see file Changes for helpers.