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

SYNOPSIS
      use MIME::Lite;
      use MIME::Lite::HTML;

      my $mailHTML = new MIME::Lite::HTML
           From     => 'MIME-Lite@alianwebserver.com',
         To       => 'alian@jupiter',
         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.2 $

DESCRIPTION
    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 cid

    *   Include external CSS,Javascript file

    *   Replace relative url with absolute one

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

  Usage
    It can be used by example 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 are present, construction use is:

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

    If no images is present, this is that:

      ---> multipart/alternative
      -------> text/plain if present
      -------> 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)
        100% ok

    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.

        %hash can have this key : [Proxy], [Debug], [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

        $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.alianwebserver.com/images/sommaire
        .gif'}=\@data; or
        $hash{'HashTemplate'}{'http://www.alianwebserver.com/script.js'}="al
        ert("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'}.

    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

    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.

AUTHOR
    Alain BARBET alian@alianwebserver.com

