Provided by: libmime-lite-html-perl_1.24-2_all bug

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
       Additional 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 with '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 !)

           ExternImages
               This is a listref of regular expressions.  If an image matches any of the regular
               expressions, it will be rendered as an <img> link, without being attached to the
               mail, regardless of the IncludeType setting above.  For example:

                 ExternImages => [ '.*cat\.jpg.*', 'external/.*' ]

               ...would mean that "images/cat.jpg" and "external/foo.jpg" would be sent as
               external <img> links, but "images/dog.jpg" would be sent using whatever the
               default IncludeType (above) is.

           $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
       occurred 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.