1HTML(3) User Contributed Perl Documentation HTML(3)
2
6 MIME::Lite::HTML - Provide routine to transform a HTML page in a
7 MIME-Lite mail
8
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
17 $Revision: 1.23 $
18
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 What's happen ?
26 The job done is:
27 • Get the file (LWP) if needed
29 • Parse page to find include images (gif, jpg, flash)
31 • Attach them to mail with adequat header if asked (default)
33 • Include external CSS,Javascript file
35 • Replace relative url with absolute one
37 • Build the final MIME-Lite object with each part found
39 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 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 Construction
48 MIME-Lite-HTML use a MIME-Lite object, and RFC2557 construction:
49 If images and text are present, construction use is:
51 --> multipart/alternative
53 ------> text/plain
54 ------> multipart/related
55 -------------> text/html
56 -------------> each images
57 If no images but text is present, this is that:
59 ---> multipart/alternative
61 -------> text/plain if present
62 -------> text/html
63 If images but no text, this is:
65 ---> multipart/related
67 -------> text/html
68 -------> each images
69 If no images and no text, this is:
71 ---> text/html
73 Documentation
75 Additionnal documentation can be found here:
76 • MIME-lite module
78 • RFC 822, RFC 1521, RFC 1522 and specially RFC 2557 (MIME
80 Encapsulation of Aggregate Documents, such as HTML)
81 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 Netscape Messager (Linux-Windows)
89 100% ok
90 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 Eudora (Windows)
96 If this module just send HTML and text, (without images), 100% ok.
97 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 KMail (Linux)
107 If this module just send HTML and text, (without images), 100% ok.
108 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 Pegasus (Windows)
114 If this module just send HTML and text, (without images), 100% ok.
115 Pegasus didn't support images in HTML. When it find a
117 multipart/related message, it ignore it, and display text part.
118 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 Install on WinX with ActiveState / PPM
127 Just do in DOS "shell":
128 c:\ ppm
130 > set repository alian http://www.alianwebserver.com/perl/CPAN
131 > install MIME-Lite-HTML
132 > quit
133 How know when next release will be ?
135 Subscribe on http://www.alianwebserver.com/cgi-bin/news_mlh.cgi
136
138 new(%hash)
139 Create a new instance of MIME::Lite::HTML.
140 The hash can have this key : [Url], [Proxy], [Debug],
142 [IncludeType],
143 [HashTemplate], [LoginDetails], [TextCharset], [HTMLCharset],
144 [TextEncoding], [HTMLEncoding], [remove_jscript]
145 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 Proxy
151 ... is url of proxy to use.
152 Eg: Proxy => 'http://192.168.100.166:8080'
154 remove_jscript
156 if set, remove all script code from html source
157 Eg: remove_jscript => 1
159 Debug
161 ... is trace to stdout during parsing.
162 Eg: Debug => 1
164 IncludeType
166 ... is method to use when finding images:
167 location
169 Default method is embed them in mail whith
170 'Content-Location' header.
171 cid You use a 'Content-CID' header.
173 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 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 ExternImages => [ '.*cat\.jpg.*', 'external/.*' ]
186 ...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 $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 $hash{'HashTemplate'}{'http://www.al.com/images/sommaire.gif'}=\@data;
199 or
201 $hash{'HashTemplate'}{'http://www.al.com/script.js'}="alert("Hello world");;
203 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 LoginDetails
210 ... is the couple user:password for use with restricted url.
211 Eg: LoginDetails => 'my_user:my_password'
213 TextCharset
215 ... is the character set to use for the text part.
216 Eg: TextCharset => 'iso-8859-7'
218 for Greek. If none specified, the default is used (iso-8859-1).
220 HTMLCharset
222 ... is the character set to use for the html part.
223 Eg: HTMLCharset => 'iso-8859-7'
225 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 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 Eg: TextEncoding => 'base64'
236 HTMLEncoding
238 ... is the Encoding to be used for the html part. If none
239 specified, the default is used (quoted-printable).
240 Eg: HTMLEncoding => 'base64'.
242 Others keys are use with MIME::Lite constructor.
244 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 parse($html, [$url_txt], [$url_base])
251 Subroutine used for created HTML mail with MIME-Lite
252 Parameters:
254 $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 http://www.alianwebserver.com
261 file://c|/tmp/index.html
262 <img src=toto.gif>
263 $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 $url_base
269 $url_base is used if $html is a buffer, for get element found
270 in HTML buffer.
271 Return the MIME::Lite part to send
273 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
281 build_mime_object($html,[$txt],[@mail])
282 (private)
283 Build the final MIME-Lite object to send with each part read before
285 $html
287 Buffer of HTML part
288 $txt
290 Buffer of text part
291 @mail
293 List of images attached to HTML part. Each item is a MIME-Lite
294 object.
295 See "Construction" in "Description" for know how MIME-Lite object
297 is build.
298 create_image_part($url)
300 (private)
301 Fetch if needed $url, and create a MIME part for it.
303 include_css($gabarit,$root)
305 (private)
306 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 include_javascript($gabarit,$root)
312 (private)
313 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 input_image($gabarit,$root)
319 (private)
320 Search in HTML buffer ($gabarit) to remplace input form image with
322 his cid
323 Return final buffer and list of MIME::Lite part
325 link_form($gabarit,$root)
327 (private)
328 Replace link to formulaire with absolute link
330 fill_template($masque,$vars)
332 $masque
333 Path of template
334 $vars
336 hash ref with keys/val to substitue
337 Give template with remplaced variables Ex: if $$vars{age}=12, and
339 $masque have
340 J'ai <? $age ?> ans,
342 this function give:
344 J'ai 12 ans,
346
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 @errors = $mailHTML->errstr;
352 If no errors where found, it'll return undef.
354
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 my $mailHTML = new MIME::Lite::HTML
366 From => 'MIME-Lite@alianwebserver.com',
367 To => param('email'),
368 Subject => 'Your url: '.param('url');
369 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
375 Copyright (c) 2000 by Alain BARBET alian (at) cpan.org
376 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 This software comes with NO WARRANTY of any kind. See the COPYING file
381 in the distribution for details.
382
384 Alain BARBET alian@cpan.org , see file Changes for helpers.
385perl v5.38.0 2023-07-20 HTML(3)
