HTML Mail plugin for SquirrelMail
=================================
Ver 2.1, 2005/03/16

Original Author: Paul Lesneiwski <pdontthink@angrynerds.com>



Description
===========

This plugin allows users with IE 5.5 and Mozilla 1.4 and 
above to compose and send their email in HTML format.

Integrated items include spell checking, emoticons, and
advanced style and formatting controls.  

Currently, two engines are included with this plugin:

   FCKeditor  http://www.fckeditor.net/

   HTMLArea   http://www.dynarch.com/projects/htmlarea/
              (Soon changing to Xinha http://xinha.gogo.co.nz/)

Configuration and behavior depends on which of those
engines you choose to use, however, if you are using this
plugin with any version of SquirrelMail prior to version
1.4.2, you will need to patch the SquirrelMail source code
no matter which engine you choose.



FCKeditor
=========

Generally the best choice, this engine is less quirky 
and is much easier to configure.  For example, it does 
not require any Perl configuration for its spell checker, 
no patching for emoticons functionality, etc.

You can customize the look and feel of the editor to 
suit your needs by further editing the configuration file
found at plugins/html_mail/fckeditor/fckconfig.js



HTMLArea
========

To use emoticons with HTMLArea, you must make an additional
patch to the SquirrelMail source.  See the INSTALL file for
details.  A selection of emoticons then becomes available 
on the compose screen (if the user turns them on in their
Display Preferences).  Note that these emoticon images will 
be served from your web server when message recipients read 
their mail.  Also note that when adding emoticons, the user 
should be sure to click in the textarea for correct focus.

To use the spall checker with HTMLArea, you must
turn it on in the configuration file, and make sure that
your server is ready to support this functionality (see
below).  



HTMLArea Spell Check Configuration
==================================

You must have a Perl interpreter available with these modules
installed:

  - CGI
  - Encode
  - HTML::Parser
  - HTML::Entities
  - Text::Aspell

If you aren't sure if you have these modules, try the following
commands.  If any of them produce errors, you'll need to install
that module.

   perl -MCGI -e 1
   perl -MEncode -e 1
   perl -MHTML::Parser -e 1
   perl -MHTML::Entities -e 1
   perl -MText::Aspell -e 1

If you have a recent version of Perl (such as 5.8), Text::Aspell
might be the only one of these you don't already have.  Of course,
CPAN.org is helpful in obtaining and installing Perl modules.  An
example of how to get Text::Aspell is as such:

perl -MCPAN -e'CPAN::Shell->install("Text::Aspell")'

You must also make sure your web server is configured to allow
the execution of CGI scripts at least in the spell checker
directory.  For apache, an appropriate directive might look
like:

<Directory /path/to/squirrelmail/plugins/html_mail/htmlarea/plugins/SpellChecker>
  Options +ExecCGI
  AddHandler cgi-script cgi
</Directory>

Note that if you symlink multiple virtual domains to one SquirrelMail
installation, you may need to repeat this directive for each domain,
or alternatively, you can place these directives in a .htaccess file 
in the spell checker directory (given in the above example).  If you
choose the latter, note that your AllowOverride directive would need 
to include the Options directive type.

And, of course, you have to turn on the spell checker in the
html_mail configuration file!



Anecdotes
=========

One person on the plugins mailing list (running Apache 2.0.48, mod_perl-1.99_11,
Perl 5.8.2, PHP-4.3.4, SquirrelMail 1.4.2) found that this worked for them:

<Directory /path/to/squirrelmail/plugins/html_mail/htmlarea/plugins/SpellChecker>
  SetHandler perl-script
  PerlResponseHandler ModPerl::Registry
  PerlOptions +ParseHeaders
  Options +ExecCGI
</Directory>

Someone else writes:

"In addition to the above, I found HTML Mail and the Spell Checker work much 
more reliably if the CGI script that invokes the spell checker lives in a 
separate directory from the other files as Apache tries to execute those and 
fails.  At least it did on my box.  So, I created a "cgi" directory in the 
"htmlarea/plugins/SpellChecker" directory, moved the spell-check-logic.cgi 
script there, and changed my "Directory" directive to use this new directory 
and all seems to be well with my use of HTML_Mail w/ spell checking."



Help Requests
=============

Help requests are welcome at my personal email address, but I
request that you first post to the SquirrelMail Plugins mailing
list, where you'll get faster help from more people and other
people with the same problem will be able to see how your issue
was resolved.  If you don't get good answers that way, you may
try emailing me directly.

Info about the SquirrelMail Plugins mailing list can be found
on the SquirrelMail web site.  It is currently located at:

http://lists.sourceforge.net/mailman/listinfo/squirrelmail-plugins
squirrelmail-plugins@lists.sourceforge.net



Future Work
===========

   *  updates to renderers as they become available (HTMLArea -> Xinha)

   *  try other renderer(s)

   *  try to reformat (as HTML) messages that are being replied 
      to that were originally sent as HTML -- this is a SM core 
      change and will not be easy, but if anyone has an interesting
      idea, I'm all ears...  IDEA: do our own IMAP query to see if
      message being replied to has an HTML part, if so, grab that
      and replace body text with it



Change Log
==========

  2.1 - 2005/03/16 - Paul Lesneiwski <pdontthink@angrynerds.com>
   * Configuration file has changed, please take note!
   * Added FCKeditor as a (better) alternative to HTMLArea
   * Fixed help URL
   * On-the-fly email format conversion is available
     via radio buttons on the compose page (when the
     default type is HTML as specified in the Display
     Preferences).
   * Messages are now sent as correctly formatted 
     multipart mime (text/html)
   * Fix: when replying/forwarding, original messages 
     with special characters were getting interpreted
     incorrectly.
   * Fix: poor performance (including lockups) when 
     replying or forwarding messages due to slow JavaScript
   * Works with newest release (v1.1) of Templates plugin
   * Check that this plugin comes after other plugins that
     change message content such as email_footer and taglines
   * Internationalization fixes
   * Added emoticons patches for SM 1.4.3 and 1.4.4
   * Synched with HTMLArea CVS repository 2005/03/15

  2.0 -  Paul Lesneiwski <pdontthink@angrynerds.com>
   * Newer Gecko browsers (e.g., Mozilla 1.4) now supported
     (htmlArea v3.0 beta)
   * When replying, adding signatures, etc., lines don't
     get concatenated all into one
   * Added emoticons functionality (optional) added (credit
     to Pablo Macouzet Jr. <squirrelmail@kingnothing.com> 
     for writing the original Emoticons plugin)
   * Disable SquirrelSpell plugin when user is composing
     emails in HTML format, since the two plugins are
     not compatible
   * Integrated spell checking mechanism is now available
   * Custom style configuration is available (you can turn
     down the initial font size, etc)
   * Updated for compatibility with email_footer plugin
   * Updated for compatibility with quicksave plugin (quirky)
   * When sending attachments, HTML format is retained
   * Updated HTML renderer
   * Added configuration file

  1.0 -  Paul Lesneiwski <pdontthink@angrynerds.com>
   * Improvements over "Enhanced Text Area Plugin":
     - updated text area renderer
     - fixed all those darn bugs
     - as of SM 1.4.2, no source patch is required
     - sends HTML email in correct format
     - no longer clashes with File Manager plugin

