HTML Mail plugin for SquirrelMail
=================================
Ver 2.3, 2005/10/15

Original Author: Paul Lesneiwski <paul@openguild.net>



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)
   *  Fix: add sig or attachment, etc. and extra blank lines added between each line
      (which seems related to linefeeds being wrapped in <p> tag sets... I'll
      let the editor makers deal with this)
   *  It might be nice to include images that come with an HTML mail 
      and are sent along in a reply (links that include src/download.php....
      but that's a pretty big hassle.  currently we just remove those <img> tags
   *  Might want to use these in the default FCKeditor config:  New configuration options are available to hide tabs from the Image Dialog and Link Dialog windows: LinkDlgHideTarget, LinkDlgHideAdvanced, ImageDlgHideLink and ImageDlgHideAdvanced.



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

  2.3 - 2005/10/15 - Paul Lesneiwski <paul@openguild.net>
   * Added default editor_height for older SquirrelMail versions
     without that setting in the user preferences.
   * Fixed additional newlines being added to message body when 
     signature added, attachment added, etc.
   * PHP 5 fix (Thanks to Tomas)
   * Updated FCKeditor editor to version 2.1
   * Default to sample config file if not otherwise configured

  2.2 - 2005/05/12 - Paul Lesneiwski <paul@openguild.net>
   * Configuration file has changed again, please take note!
   * Turn off all functionality if JavaScript is not available
   * User can now change to HTML format reply directly from 
     compose screen even when Display Preference composition 
     type is set to Plain Text
   * Fixed FCKeditor height and width to obey SquirrelMail editor settings
   * Moved prefs item into the compose preferences page in 
     SM 1.5.1+
   * Implemented reconstruction of HTML of the original mail
     when replying
   * Emoticons and other links are now sent out in emails with 
     absolute (not relative) URIs
   * User may now choose editor type (if admin allows)
   * Fixed problems on some systems where editor wasn't showing up
   * Replaced *nix/Windows configuration item with ASpell path 
     configuration instead
   * FCKeditor is version 2.0FC
   * HTMLArea is cvs from 2005/03/15 (still 3.0beta)
   * Compatibility plugin no longer required

  2.1 - 2005/03/16 - Paul Lesneiwski <paul@openguild.net>
   * 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 <paul@openguild.net>
   * 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 <paul@openguild.net>
   * 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

