1HTML(3)               User Contributed Perl Documentation              HTML(3)
2
3
4

NAME

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

SYNOPSIS

10         perl -MMIME::Lite::HTML -e '
11            new MIME::Lite::HTML
12                From     => "MIME-Lite\@alianwebserver.com",
13                To       => "alian\@cpan.org",
14                Url      => "http://localhost/server-status";'
15

VERSION

17       $Revision: 1.23 $
18

DESCRIPTION

20       This module is a Perl mail client interface for sending message that
21       support HTML format and build them for you..  This module provide
22       routine to transform a HTML page in MIME::Lite mail.  So you need this
23       module to use MIME-Lite-HTML possibilities
24
25   What's happen ?
26       The job done is:
27
28       •   Get the file (LWP) if needed
29
30       •   Parse page to find include images (gif, jpg, flash)
31
32       •   Attach them to mail with adequat header if asked (default)
33
34       •   Include external CSS,Javascript file
35
36       •   Replace relative url with absolute one
37
38       •   Build the final MIME-Lite object with each part found
39
40   Usage
41       Did you alread see link like "Send this page to a friend" ?. With this
42       module, you can do script that to this in 3 lines.
43
44       It can be used too in a HTML newsletter. You make a classic HTML page,
45       and give just url to MIME::Lite::HTML.
46
47   Construction
48       MIME-Lite-HTML use a MIME-Lite object, and RFC2557 construction:
49
50       If images and text are present, construction use is:
51
52         --> multipart/alternative
53         ------> text/plain
54         ------> multipart/related
55         -------------> text/html
56         -------------> each images
57
58       If no images but text is present, this is that:
59
60         ---> multipart/alternative
61         -------> text/plain if present
62         -------> text/html
63
64       If images but no text, this is:
65
66         ---> multipart/related
67         -------> text/html
68         -------> each images
69
70       If no images and no text, this is:
71
72         ---> text/html
73
74   Documentation
75       Additionnal documentation can be found here:
76
77       •   MIME-lite module
78
79       •   RFC 822, RFC 1521, RFC 1522 and specially RFC 2557 (MIME
80           Encapsulation of Aggregate Documents, such as HTML)
81
82   Clients tested
83       HTML in mail is not full supported so this module can't work with all
84       email clients. If some client recognize HTML, they didn't support
85       images include in HTML. So in fact, they recognize multipart/relative
86       but not multipart/related.
87
88       Netscape Messager (Linux-Windows)
89           100% ok
90
91       Outlook Express (Windows-Mac)
92           100% ok. Mac work only with Content-Location header. Thx to Steve
93           Benbow for give mr this feedback and for his test.
94
95       Eudora (Windows)
96           If this module just send HTML and text, (without images), 100% ok.
97
98           With images, Eudora didn't recognize multipart/related part as
99           describe in RFC 2557 even if he can read his own HTML mail. So if
100           images are present in HTML part, text and HTML part will be
101           displayed both, text part in first.  Two additional headers will be
102           displayed in HTML part too in this case.  Version 1.0 of this
103           module correct major problem of headers displayed with image
104           include in HTML part.
105
106       KMail (Linux)
107           If this module just send HTML and text, (without images), 100% ok.
108
109           In other case, Kmail didn't support image include in HTML. So if
110           you set in KMail "Prefer HTML to text", it display HTML with images
111           broken. Otherwise, it display text part.
112
113       Pegasus (Windows)
114           If this module just send HTML and text, (without images), 100% ok.
115
116           Pegasus didn't support images in HTML. When it find a
117           multipart/related message, it ignore it, and display text part.
118
119       If you find others mail client who support (or not support) MIME-Lite-
120       HTML module, give me some feedback ! If you want be sure that your mail
121       can be read by maximum of people, (so not only OE and Netscape), don't
122       include images in your mail, and use a text buffer too. If
123       multipart/related mail is not recognize, multipart/alternative can be
124       read by the most of mail client.
125
126   Install on WinX with ActiveState / PPM
127       Just do in DOS "shell":
128
129         c:\ ppm
130         > set repository alian http://www.alianwebserver.com/perl/CPAN
131         > install MIME-Lite-HTML
132         > quit
133
134   How know when next release will be ?
135       Subscribe on http://www.alianwebserver.com/cgi-bin/news_mlh.cgi
136

Public Interface

138       new(%hash)
139           Create a new instance of MIME::Lite::HTML.
140
141           The hash can have this key : [Url], [Proxy], [Debug],
142           [IncludeType],
143            [HashTemplate], [LoginDetails], [TextCharset], [HTMLCharset],
144            [TextEncoding], [HTMLEncoding], [remove_jscript]
145
146           Url ... is url to parse and send. If this param is found, call of
147               parse routine and send of mail is done. Else you must use parse
148               routine of MIME::Lite::HTML and send of MIME::Lite.
149
150           Proxy
151               ... is url of proxy to use.
152
153                 Eg: Proxy => 'http://192.168.100.166:8080'
154
155           remove_jscript
156               if set, remove all script code from html source
157
158                 Eg: remove_jscript => 1
159
160           Debug
161               ... is trace to stdout during parsing.
162
163                 Eg: Debug => 1
164
165           IncludeType
166               ... is method to use when finding images:
167
168               location
169                   Default method is embed them in mail whith
170                   'Content-Location' header.
171
172               cid You use a 'Content-CID' header.
173
174               extern
175                   Images are not embed, relative url are just replace with
176                   absolute, so images are fetch when user read mail. (Server
177                   must be reachable !)
178
179           ExternImages
180               This is a listref of regular expressions.  If an image matches
181               any of the regular expressions, it will be rendered as an <img>
182               link, without being attached to the mail, regardless of the
183               IncludeType setting above.  For example:
184
185                 ExternImages => [ '.*cat\.jpg.*', 'external/.*' ]
186
187               ...would mean that "images/cat.jpg" and "external/foo.jpg"
188               would be sent as external <img> links, but "images/dog.jpg"
189               would be sent using whatever the default IncludeType (above)
190               is.
191
192           $hash{'HashTemplate'}
193               ... is a reference to a hash. If present, MIME::Lite::HTML will
194               substitute <? $name ?> with $hash{'HashTemplate'}{'name'} when
195               parse url to send. $hash{'HashTemplate'} can be used too for
196               include data for subelement.  Eg:
197
198                 $hash{'HashTemplate'}{'http://www.al.com/images/sommaire.gif'}=\@data;
199
200               or
201
202                 $hash{'HashTemplate'}{'http://www.al.com/script.js'}="alert("Hello world");;
203
204               When module find the image
205               http://www.alianwebserver.com/images/sommaire.gif in buffer, it
206               don't get image with LWP but use data found in
207               $hash{'HashTemplate'}. (See eg/example2.pl)
208
209           LoginDetails
210               ... is the couple user:password for use with restricted url.
211
212                 Eg: LoginDetails => 'my_user:my_password'
213
214           TextCharset
215               ... is the character set to use for the text part.
216
217                 Eg: TextCharset => 'iso-8859-7'
218
219               for Greek. If none specified, the default is used (iso-8859-1).
220
221           HTMLCharset
222               ... is the character set to use for the html part.
223
224                 Eg:  HTMLCharset => 'iso-8859-7'
225
226               for Greek. If none specified, the default is used (iso-8859-1).
227               Take care, as that option does NOT change the character set of
228               the HTML page, it only changes the character set of the mime
229               part.
230
231           TextEncoding
232               ... is the Encoding to be used for the text part (if such a
233               part exists). If none specified, the default is used (7bit).
234
235                 Eg: TextEncoding => 'base64'
236
237           HTMLEncoding
238               ... is the Encoding to be used for the html part. If none
239               specified, the default is used (quoted-printable).
240
241                 Eg: HTMLEncoding => 'base64'.
242
243           Others keys are use with MIME::Lite constructor.
244
245           This MIME-Lite keys are: Bcc, Encrypted, Received, Sender, Cc,
246           From, References, Subject, Comments, Keywords, Reply-To To,
247           Content-*, Message-ID,Resent-*, X-*,Date, MIME-Version, Return-
248           Path, Organization
249
250       parse($html, [$url_txt], [$url_base])
251           Subroutine used for created HTML mail with MIME-Lite
252
253           Parameters:
254
255           $html
256               Url of HTML file to send, can be a local file. If $url is not
257               an url (http or https or ftp or file or nntp), $url is used as
258               a buffer.  Example :
259
260                 http://www.alianwebserver.com
261                 file://c|/tmp/index.html
262                 <img src=toto.gif>
263
264           $url_txt
265               Url of text part to send for person who doesn't support HTML
266               mail.  As $html, $url_txt can be a simple buffer.
267
268           $url_base
269               $url_base is used if $html is a buffer, for get element found
270               in HTML buffer.
271
272           Return the MIME::Lite part to send
273
274       size()
275           Display size of mail in characters (so octets) that will be send.
276           (So use it *after* parse method). Use this method for control size
277           of mail send, I personnaly hate receive 500k by mail.  I pay for a
278           33k modem :-(
279

Private methods

281       build_mime_object($html,[$txt],[@mail])
282           (private)
283
284           Build the final MIME-Lite object to send with each part read before
285
286           $html
287               Buffer of HTML part
288
289           $txt
290               Buffer of text part
291
292           @mail
293               List of images attached to HTML part. Each item is a MIME-Lite
294               object.
295
296           See "Construction" in "Description" for know how MIME-Lite object
297           is build.
298
299       create_image_part($url)
300           (private)
301
302           Fetch if needed $url, and create a MIME part for it.
303
304       include_css($gabarit,$root)
305           (private)
306
307           Search in HTML buffer ($gabarit) to remplace call to extern CSS
308           file with his content. $root is original absolute url where css
309           file will be found.
310
311       include_javascript($gabarit,$root)
312           (private)
313
314           Search in HTML buffer ($gabarit) to remplace call to extern
315           javascript file with his content. $root is original absolute url
316           where javascript file will be found.
317
318       input_image($gabarit,$root)
319           (private)
320
321           Search in HTML buffer ($gabarit) to remplace input form image with
322           his cid
323
324           Return final buffer and list of MIME::Lite part
325
326       link_form($gabarit,$root)
327           (private)
328
329           Replace link to formulaire with absolute link
330
331       fill_template($masque,$vars)
332           $masque
333               Path of template
334
335           $vars
336               hash ref with keys/val to substitue
337
338           Give template with remplaced variables Ex: if $$vars{age}=12, and
339           $masque have
340
341             J'ai <? $age ?> ans,
342
343           this function give:
344
345             J'ai 12 ans,
346

Error Handling

348       The set_err routine is used privately. You can ask for an array of all
349       the errors which occured inside the parse routine by calling:
350
351       @errors = $mailHTML->errstr;
352
353       If no errors where found, it'll return undef.
354

CGI Example

356         #!/usr/bin/perl -w
357         # A cgi program that do "Mail this page to a friend";
358         # Call this script like this :
359         # script.cgi?email=myfriend@isp.com&url=http://www.go.com
360         use strict;
361         use CGI qw/:standard/;
362         use CGI::Carp qw/fatalsToBrowser/;
363         use MIME::Lite::HTML;
364
365         my $mailHTML = new MIME::Lite::HTML
366            From     => 'MIME-Lite@alianwebserver.com',
367            To       => param('email'),
368            Subject => 'Your url: '.param('url');
369
370         my $MIMEmail = $mailHTML->parse(param('url'));
371         $MIMEmail->send; # or for win user : $mail->send_by_smtp('smtp.fai.com');
372         print header,"Mail envoye (", param('url'), " to ", param('email'),")<br>\n";
373

TERMS AND CONDITIONS

375         Copyright (c) 2000 by Alain BARBET alian (at) cpan.org
376
377       All rights reserved.  This program is free software; you can
378       redistribute it and/or modify it under the same terms as Perl itself.
379
380       This software comes with NO WARRANTY of any kind.  See the COPYING file
381       in the distribution for details.
382

AUTHOR

384       Alain BARBET alian@cpan.org , see file Changes for helpers.
385
386
387
388perl v5.36.0                      2023-01-20                           HTML(3)
Impressum