.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "HTML 3pm"
.TH HTML 3pm "2008-10-14" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
MIME::Lite::HTML \- Provide routine to transform a HTML page in a MIME\-Lite mail
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&  perl \-MMIME::Lite::HTML \-e \*(Aq
\&     new MIME::Lite::HTML
\&         From     => "MIME\-Lite\e@alianwebserver.com",
\&         To       => "alian\e@cpan.org",
\&         Url      => "http://localhost/server\-status";\*(Aq
.Ve
.SH "VERSION"
.IX Header "VERSION"
\&\f(CW$Revision:\fR 1.23 $
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is a Perl mail client interface for sending message that 
support \s-1HTML\s0 format and build them for you..
This module provide routine to transform a \s-1HTML\s0 page in MIME::Lite mail.
So you need this module to use MIME-Lite-HTML possibilities
.SS "What's happen ?"
.IX Subsection "What's happen ?"
The job done is:
.IP "\(bu" 4
Get the file (\s-1LWP\s0) if needed
.IP "\(bu" 4
Parse page to find include images (gif, jpg, flash)
.IP "\(bu" 4
Attach them to mail with adequat header if asked (default)
.IP "\(bu" 4
Include external \s-1CSS\s0,Javascript file
.IP "\(bu" 4
Replace relative url with absolute one
.IP "\(bu" 4
Build the final MIME-Lite object with each part found
.SS "Usage"
.IX Subsection "Usage"
Did you alread see link like \*(L"Send this page to a friend\*(R" ?. With this module,
you can do script that to this in 3 lines.
.PP
It can be used too in a \s-1HTML\s0 newsletter. You make a classic \s-1HTML\s0 page,
and give just url to MIME::Lite::HTML.
.SS "Construction"
.IX Subsection "Construction"
MIME-Lite-HTML use a MIME-Lite object, and \s-1RFC2557\s0 construction:
.PP
If images and text are present, construction use is:
.PP
.Vb 5
\&  \-\-> multipart/alternative
\&  \-\-\-\-\-\-> text/plain
\&  \-\-\-\-\-\-> multipart/related
\&  \-\-\-\-\-\-\-\-\-\-\-\-\-> text/html
\&  \-\-\-\-\-\-\-\-\-\-\-\-\-> each images
.Ve
.PP
If no images but text is present, this is that:
.PP
.Vb 3
\&  \-\-\-> multipart/alternative
\&  \-\-\-\-\-\-\-> text/plain if present
\&  \-\-\-\-\-\-\-> text/html
.Ve
.PP
If images but no text, this is:
.PP
.Vb 3
\&  \-\-\-> multipart/related
\&  \-\-\-\-\-\-\-> text/html
\&  \-\-\-\-\-\-\-> each images
.Ve
.PP
If no images and no text, this is:
.PP
.Vb 1
\&  \-\-\-> text/html
.Ve
.SS "Documentation"
.IX Subsection "Documentation"
Additionnal documentation can be found here:
.IP "\(bu" 4
MIME-lite module
.IP "\(bu" 4
\&\s-1RFC\s0 822, \s-1RFC\s0 1521, \s-1RFC\s0 1522 and specially \s-1RFC\s0 2557 (\s-1MIME\s0 Encapsulation
of Aggregate Documents, such as \s-1HTML\s0)
.SS "Clients tested"
.IX Subsection "Clients tested"
\&\s-1HTML\s0 in mail is not full supported so this module can't work with all email
clients. If some client recognize \s-1HTML\s0, they didn't support images include in
\&\s-1HTML\s0. So in fact, they recognize multipart/relative but not multipart/related.
.IP "Netscape Messager (Linux-Windows)" 4
.IX Item "Netscape Messager (Linux-Windows)"
100% ok
.IP "Outlook Express (Windows-Mac)" 4
.IX Item "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.
.IP "Eudora (Windows)" 4
.IX Item "Eudora (Windows)"
If this module just send \s-1HTML\s0 and text, (without images), 100% ok.
.Sp
With images, Eudora didn't recognize multipart/related part as describe in
\&\s-1RFC\s0 2557 even if he can read his own \s-1HTML\s0 mail. So if images are present in 
\&\s-1HTML\s0 part, text and \s-1HTML\s0 part will be displayed both, text part in first. 
Two additional headers will be displayed in \s-1HTML\s0 part too in this case. 
Version 1.0 of this module correct major problem of headers displayed 
with image include in \s-1HTML\s0 part.
.IP "KMail (Linux)" 4
.IX Item "KMail (Linux)"
If this module just send \s-1HTML\s0 and text, (without images), 100% ok.
.Sp
In other case, Kmail didn't support image include in \s-1HTML\s0. So if you set in 
KMail \*(L"Prefer \s-1HTML\s0 to text\*(R", it display \s-1HTML\s0 with images broken. Otherwise, 
it display text part.
.IP "Pegasus (Windows)" 4
.IX Item "Pegasus (Windows)"
If this module just send \s-1HTML\s0 and text, (without images), 100% ok.
.Sp
Pegasus didn't support images in \s-1HTML\s0. When it find a multipart/related 
message, it ignore it, and display text part.
.PP
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 \s-1OE\s0 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.
.SS "Install on WinX with ActiveState / \s-1PPM\s0"
.IX Subsection "Install on WinX with ActiveState / PPM"
Just do in \s-1DOS\s0 \*(L"shell\*(R":
.PP
.Vb 4
\&  c:\e ppm
\&  > set repository alian http://www.alianwebserver.com/perl/CPAN
\&  > install MIME\-Lite\-HTML
\&  > quit
.Ve
.SS "How know when next release will be ?"
.IX Subsection "How know when next release will be ?"
Subscribe on http://www.alianwebserver.com/cgi\-bin/news_mlh.cgi
.SH "Public Interface"
.IX Header "Public Interface"
.IP "new(%hash)" 4
.IX Item "new(%hash)"
Create a new instance of MIME::Lite::HTML.
.Sp
The hash can have this key : [Url], [Proxy], [Debug], [IncludeType],
 [HashTemplate], [LoginDetails], [TextCharset], [HTMLCharset],
 [TextEncoding], [HTMLEncoding], [remove_jscript]
.RS 4
.IP "Url" 4
.IX Item "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.
.IP "Proxy" 4
.IX Item "Proxy"
\&... is url of proxy to use.
.Sp
.Vb 1
\&  Eg: Proxy => \*(Aqhttp://192.168.100.166:8080\*(Aq
.Ve
.IP "remove_jscript" 4
.IX Item "remove_jscript"
if set, remove all script code from html source
.Sp
.Vb 1
\&  Eg: remove_jscript => 1
.Ve
.IP "Debug" 4
.IX Item "Debug"
\&... is trace to stdout during parsing.
.Sp
.Vb 1
\&  Eg: Debug => 1
.Ve
.IP "IncludeType" 4
.IX Item "IncludeType"
\&... is method to use when finding images:
.RS 4
.IP "location" 4
.IX Item "location"
Default method is embed them in mail whith 'Content\-Location' header.
.IP "cid" 4
.IX Item "cid"
You use a 'Content\-CID' header.
.IP "extern" 4
.IX Item "extern"
Images are not embed, relative url are just replace with absolute, 
so images are fetch when user read mail. (Server must be reachable !)
.RE
.RS 4
.RE
.ie n .IP "$hash{'HashTemplate'}" 4
.el .IP "\f(CW$hash\fR{'HashTemplate'}" 4
.IX Item "$hash{'HashTemplate'}"
\&... is a reference to a hash. If present, MIME::Lite::HTML 
will substitute <? \f(CW$name\fR ?> with \f(CW$hash\fR{'HashTemplate'}{'name'} when parse url 
to send. \f(CW$hash\fR{'HashTemplate'} can be used too for include data for subelement.
Eg:
.Sp
.Vb 1
\&  $hash{\*(AqHashTemplate\*(Aq}{\*(Aqhttp://www.al.com/images/sommaire.gif\*(Aq}=\e@data;
.Ve
.Sp
or
.Sp
.Vb 1
\&  $hash{\*(AqHashTemplate\*(Aq}{\*(Aqhttp://www.al.com/script.js\*(Aq}="alert("Hello world");;
.Ve
.Sp
When module find the image http://www.alianwebserver.com/images/sommaire.gif 
in buffer, it don't get image with \s-1LWP\s0 but use data found in 
\&\f(CW$hash\fR{'HashTemplate'}. (See eg/example2.pl)
.IP "LoginDetails" 4
.IX Item "LoginDetails"
\&... is the couple user:password for use with restricted url.
.Sp
.Vb 1
\&  Eg: LoginDetails => \*(Aqmy_user:my_password\*(Aq
.Ve
.IP "TextCharset" 4
.IX Item "TextCharset"
\&... is the character set to use for the text part.
.Sp
.Vb 1
\&  Eg: TextCharset => \*(Aqiso\-8859\-7\*(Aq
.Ve
.Sp
for Greek. If none specified, the default is used (iso\-8859\-1).
.IP "HTMLCharset" 4
.IX Item "HTMLCharset"
\&... is the character set to use for the html part.
.Sp
.Vb 1
\&  Eg:  HTMLCharset => \*(Aqiso\-8859\-7\*(Aq
.Ve
.Sp
for Greek. If none specified, the default is used (iso\-8859\-1).
Take care, as that option does \s-1NOT\s0 change the character
set of the \s-1HTML\s0 page, it only changes the character set of the mime part.
.IP "TextEncoding" 4
.IX Item "TextEncoding"
\&... is the Encoding to be used for the text part (if such a part 
exists). If none specified, the default is used (7bit).
.Sp
.Vb 1
\&  Eg: TextEncoding => \*(Aqbase64\*(Aq
.Ve
.IP "HTMLEncoding" 4
.IX Item "HTMLEncoding"
\&... is the Encoding to be used for the html part. If none specified, the 
default is used (quoted-printable).
.Sp
.Vb 1
\&  Eg: HTMLEncoding => \*(Aqbase64\*(Aq.
.Ve
.RE
.RS 4
.Sp
Others keys are use with MIME::Lite constructor.
.Sp
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
.RE
.IP "parse($html, [$url_txt], [$url_base])" 4
.IX Item "parse($html, [$url_txt], [$url_base])"
Subroutine used for created \s-1HTML\s0 mail with MIME-Lite
.Sp
Parameters:
.RS 4
.ie n .IP "$html" 4
.el .IP "\f(CW$html\fR" 4
.IX Item "$html"
Url of \s-1HTML\s0 file to send, can be a local file. If \f(CW$url\fR is not an
url (http or https or ftp or file or nntp), \f(CW$url\fR is used as a buffer.
Example :
.Sp
.Vb 3
\&  http://www.alianwebserver.com
\&  file://c|/tmp/index.html
\&  <img src=toto.gif>
.Ve
.ie n .IP "$url_txt" 4
.el .IP "\f(CW$url_txt\fR" 4
.IX Item "$url_txt"
Url of text part to send for person who doesn't support \s-1HTML\s0 mail.
As \f(CW$html\fR, \f(CW$url_txt\fR can be a simple buffer.
.ie n .IP "$url_base" 4
.el .IP "\f(CW$url_base\fR" 4
.IX Item "$url_base"
\&\f(CW$url_base\fR is used if \f(CW$html\fR is a buffer, for get element found in \s-1HTML\s0 buffer.
.RE
.RS 4
.Sp
Return the MIME::Lite part to send
.RE
.IP "\fIsize()\fR" 4
.IX Item "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 :\-(
.SH "Private methods"
.IX Header "Private methods"
.IP "build_mime_object($html,[$txt],[@mail])" 4
.IX Item "build_mime_object($html,[$txt],[@mail])"
(private)
.Sp
Build the final MIME-Lite object to send with each part read before
.RS 4
.ie n .IP "$html" 4
.el .IP "\f(CW$html\fR" 4
.IX Item "$html"
Buffer of \s-1HTML\s0 part
.ie n .IP "$txt" 4
.el .IP "\f(CW$txt\fR" 4
.IX Item "$txt"
Buffer of text part
.ie n .IP "@mail" 4
.el .IP "\f(CW@mail\fR" 4
.IX Item "@mail"
List of images attached to \s-1HTML\s0 part. Each item is a MIME-Lite object.
.RE
.RS 4
.Sp
See \*(L"Construction\*(R" in \*(L"Description\*(R" for know how MIME-Lite object is build.
.RE
.IP "create_image_part($url)" 4
.IX Item "create_image_part($url)"
(private)
.Sp
Fetch if needed \f(CW$url\fR, and create a \s-1MIME\s0 part for it.
.IP "include_css($gabarit,$root)" 4
.IX Item "include_css($gabarit,$root)"
(private)
.Sp
Search in \s-1HTML\s0 buffer ($gabarit) to remplace call to extern \s-1CSS\s0 file
with his content. \f(CW$root\fR is original absolute url where css file will
be found.
.IP "include_javascript($gabarit,$root)" 4
.IX Item "include_javascript($gabarit,$root)"
(private)
.Sp
Search in \s-1HTML\s0 buffer ($gabarit) to remplace call to extern javascript file
with his content. \f(CW$root\fR is original absolute url where javascript file will
be found.
.IP "input_image($gabarit,$root)" 4
.IX Item "input_image($gabarit,$root)"
(private)
.Sp
Search in \s-1HTML\s0 buffer ($gabarit) to remplace input form image with his cid
.Sp
Return final buffer and list of MIME::Lite part
.IP "link_form($gabarit,$root)" 4
.IX Item "link_form($gabarit,$root)"
(private)
.Sp
Replace link to formulaire with absolute link
.IP "fill_template($masque,$vars)" 4
.IX Item "fill_template($masque,$vars)"
.RS 4
.PD 0
.ie n .IP "$masque" 4
.el .IP "\f(CW$masque\fR" 4
.IX Item "$masque"
.PD
Path of template
.ie n .IP "$vars" 4
.el .IP "\f(CW$vars\fR" 4
.IX Item "$vars"
hash ref with keys/val to substitue
.RE
.RS 4
.Sp
Give template with remplaced variables
Ex: if $$vars{age}=12, and \f(CW$masque\fR have
.Sp
.Vb 1
\&  J\*(Aqai <? $age ?> ans,
.Ve
.Sp
this function give:
.Sp
.Vb 1
\&  J\*(Aqai 12 ans,
.Ve
.RE
.SH "Error Handling"
.IX Header "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:
.PP
\&\f(CW@errors\fR = \f(CW$mailHTML\fR\->errstr;
.PP
If no errors where found, it'll return undef.
.SH "CGI Example"
.IX Header "CGI Example"
.Vb 8
\&  #!/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     => \*(AqMIME\-Lite@alianwebserver.com\*(Aq,
\&     To       => param(\*(Aqemail\*(Aq),
\&     Subject => \*(AqYour url: \*(Aq.param(\*(Aqurl\*(Aq);
\&  
\&  my $MIMEmail = $mailHTML\->parse(param(\*(Aqurl\*(Aq));
\&  $MIMEmail\->send; # or for win user : $mail\->send_by_smtp(\*(Aqsmtp.fai.com\*(Aq);
\&  print header,"Mail envoye (", param(\*(Aqurl\*(Aq), " to ", param(\*(Aqemail\*(Aq),")<br>\en";
.Ve
.SH "TERMS AND CONDITIONS"
.IX Header "TERMS AND CONDITIONS"
.Vb 1
\&  Copyright (c) 2000 by Alain BARBET alian (at) cpan.org
.Ve
.PP
All rights reserved.  This program is free software; you can
redistribute it and/or modify it under the same terms as Perl
itself.
.PP
This software comes with \fB\s-1NO\s0 \s-1WARRANTY\s0\fR of any kind.
See the \s-1COPYING\s0 file in the distribution for details.
.SH "AUTHOR"
.IX Header "AUTHOR"
Alain \s-1BARBET\s0 alian@cpan.org , see file Changes for helpers.