
TWC Weather Plug-in v1.2 Beta 2a
By Jamuel P. Starkey jamuel@my740il.com

Description
------------
A Squirrelemail compatible plug-in to retrieve weather-related information
on a per-user basis from data provided by weather.com  Sites can be added
(by individual SM users) by entering a zip code, or by searching City, State, 
and/or Country.


Disclaimer
----------
This plug-in was written purley as a recreational/educational task.  It pulls 
data from a COMMERICAL website--www.weather.com--so just keep that in mind 
if you reuse this plug-in in a commerical endeavour.  Regardless the output of
the plug-in is *always* attributed to www.weather.com to give credit where 
credit is due for the datafeed.  

Additionally this plug-in is based on Dan Hemmerich's (dan@spot.org) original 
Weather 3.0.0 code base.  I only mangled it for the purpose described herein.



Features in 1.2 Beta 2 & 2a
---------------------------
-- Added Administrator config.php option to force SM server to proxy
   weather icon requests to the datafeed.  Previously the plugin would only
   provide the original URL via image tag (IMG SRC).  If an SM client
   was accessing SM via secure HTTP (HTTPS) then this "redirect" would
   usually force a pop-up warning the user about being redirect to 
   an unsecure site (the weather.com datafeed).  The default setting
   is still set to the original behaviour as the PHP on the SM server
   needs to have GD (with GIF read and PNG write) as well as streams
   enabled.  Since I don't know how PHP defaults GD builds I'll leave it
   be.  So if you flip weather_proxy_icons on and start getting error 
   messages then you might want to check GD is compiled into your PHP.

-- Minor formatting change for Location and/or Alias when no weather icon
   is displayed--it's now centered.

-- Beta 2 was an internal release.

Features in 1.2 Beta 1
----------------------
-- Support for setting the default options that are selected when a new
   location is added (Thanks to steve@blinky.net for the core code!).
   Default options for new users are set in by the Admin in config.php.
   After a user creates a location subsequent locations created by the
   user are templated from the location previously created.
   
   Take a look a the config.php file to set up these default options.

-- Minor useability enhancements

-- Patch to handle TWC URL change from www to w3


Features in 1.1-p1
------------------
-- Everything you see below relating to v1.1 ;)

-- Plus a patch to handle TWC URL change from www to w3


Features in 1.1 RC 2
---------------------
-- Minor bug fix to check if SM_PATH is already defined.  Code was colliding
   with some other plugins according to reports.


Features in 1.1 RC 1a
---------------------
-- Minor fix to options.php to support SM 1.4.0 release

-- Cleaned up/rearranged more code

-- Re-enabled most administrative config options.  See the config.php
   file in the twc_weather directory.

-- Added a socket timeout/timer option to config.php to safety/check stalled/
   broken connections to the TWC datafeed.  This options has been set to 
   15 seconds.  It's enforced on a per weather location basis for the primary
   weather data values and then again on the forecast/narrative since these
   are made with two seperate connections.  Not sure if the default of 15
   seconds will impact an SM server tied to a really slow dialup or cable 
   connections--that's why it's user configurable!  ;)

-- Decided to defer the adjectives feature for the forecast text :(  So there 
   will not be any "low, lower, mid, middle, high, upper" modifiers added 
   to SI/metric converted temperatures in the forecast/narrative text--just a 
   numeric value like 10s or 20s.  Maybe a future (1.2) release . . .


Features in 1.1 Beta 2d
--------------------------
-- Updated Words2Numbers parsing work.  Was failing some test cases that
   contained fractions of an inch and just inches.

-- This is the best known,/most stable release of twc_weather containing
   SI/Metric conversion support.  If you need/enjoy SI units then this
   release is for you.

-- Only support missing in narrative conversion is the addition of adjective
   modifiers (like lower, mid, upper) to temperatures in forecasts--this is
   still the target for Beta 3.


Features in 1.1 Beta 2c
--------------------------

-- Cleaned up twc_support quite a bit.  Added lots of comments and restructured
   some of the lines of code to stay within 80 columns.  

-- Also fixed the output of the weather box to so that the column position 
   of the weather values doesn't fluctuate.  They sort of floated ever since 
   the option to display a wide (vs narrow) forecast/narrative text.  
   (Thanks to Stephen Brown for coming up with the patch for that.)

-- Made a couple of random fixes to the support code to help handle random
   preg_replace problems/bugs in my search-patterns.  What comes to mind
   are a fix for trapping "than" vs "an" (was getting a hit on a phrase 
   that had "than") and was dropping a period on an end of a sentence that 
   contained an inches conversion.  Both are fixed.

Features in 1.1 Beta 2b
--------------------------

-- Fixed a gaff in the "Feels Like" parser logic

-- Changed Barometric SI units to KPa (rather than mb) based on user feedback

-- Added per location option to display the forecast narrative across the
   entire weather box as opposed to aligned with the other weather values.
   (Thanks to Stephen Brown for the contributed code.)

Features in 1.1 Beta 2a&b
--------------------------
-- Another reworked parser fix plus some other bugs from the narrative are
   fixed.


Features in 1.1 Beta 2
-----------------------

-- Metric/SI support for forecast/narratives.  Use the resulting forecasts
with caution as there maybe slight rounding and/or estimation errors in the
coverted text.

This feature is still very much a work in progress. Parsing and converting 
plain-text requires contextual knowledge to interpret the units that are being 
expressed not only in the type of measurement (say temperature versus windspeed) 
but also in some of the adjectives and/or english modifiers being applied 
(e.g low, upper, single digits, middle teens, etc.)  

Currently only some of the adjectives are supported (paritial support is probably
a better description)

Supported: 
Any wind speed, temperature, or precipiation that is expressed clearly
either as a single value or a range of value (e.g. Lows to 30F or Winds 5 to 15
mph, Snow accumulation up to 3 inches) are run thru standard english-->metric
units conversion.  Depending on the measurement the result is is rounded to the
typically expressed precision (e.g. temperature and wind speed in whole units)

Adjectives/quantities supported: numeric up to ten (one, two, three --> 1.0, 2.0, 3.0),
fractions (quarter, half, three-quarters)
 
Partial Support:  single digits = 5, teens = 15 , anything close to 0 is said to
be "near 0" if a range is given (Lows in the 30s --> Lows near 0).

Unsupported:  Low, Upper, Middle  (look for these in Beta 3)

FEEDBACK:  Since I don't live in an SI world--I'd certainly appreciate any SI
usability and/or accuracy feedback -- jamuel@my740il.com .

Enjoy!

Features in 1.1 Beta 1a
-----------------------

-- Verified support for SM 1.4.x branch (tested with 1.4.0 RC1 and RC2A)

-- Metric/SI Units support for all basic weather values except forecast/narratives
   (narrative support is currently in the works (in a forthcoming Beta 2) 

-- Enhanced Barometric Pressure: display appropriate "steady/rising/falling"

-- Enhanced Winds: display Gusting winds speed values when present

-- Did I mention *Metric* support for *ALL* locations -- not just those that report
   in SI Units!  Just select Metric (SI) Units in the TWC Options menu where
   you create/edit a weather location.


Features in 1.0
---------------
I think weather.com overhauled their site and subsequently broke the old plug-in.  
I fixed the parser to handle the new tags and URLs from weather.com.  Also added
Chunk decoding handler since most all of the messages from weather.com seem to 
be chunk encoded.  

Finally I added a couple of cool features:

-- Supports Squirrelmail branches 1.2.x and 1.3.x only! 

-- PHP's register_globals = Off supported (fully on SM 1.3.x, partial on 1.2.x)

-- International Weather Location Support (just enter a location by City, Country)

-- Graphical Current Conditions Indicator/Icon (Sunny, Cloudy, Rain, Snow, etc)

-- Better error handling when adding new locations (will prompt if multiple sites
   are located)
        
-- Handles multiple search results to allow user to select which location they 
   were "really" searching for.

-- Alias support to rename locations to user defined labels 
   (e.g. San Francisco, CA can be S.F.)

-- Random code changes/fixes/bloats to implement the above.


Requirements
------------
The only tested configuration that is supported is as follows:

-- Need feedback for the following:  Squirrelmail 1.2.x, 1.3.x, 1.4.x
   but (known to work with SM 1.4.0-rc2a, 1.2.11 both with PHP 4.3.0)

-- PHP register_globals = Off (or On).  PHP should also support Perl Regular
   Expressions (PCRE) as well as Regular Expressions (EREG). 

Caveats
--------
*  rg = Off supported in SM 1.2.x if user_prefs are *file* based as opposed to 
   MySQL/database-based.  Seems like other portions of SM code prevent correct 
   operation when user preferences are stored in a database as oppoed to being 
   stored in the data directory.

-- Have received a report that the Squid Proxy can interfere with the 
   gathering of the twc data feed.  The user was able to create an appropriate 
   rule to enable the correct operation.  Send me email and we can discuss 
   debugging options if you aren't able to get this plug-in working. I've 
   recently (1.1 RC1) discovered that the $weather_proxy variable was probably
   broken in config.php -- so it might actually work now.  Any takers?

-- Heard that Netscape 4.x browsers can only display the weather box and can NOT
   edit the TWC Options.  A blank page is displayed.  Will try and resolve for
   by the final 1.1 release.

-- If you see an error message about not being able to open an included file:
   "Fatal Error: Failed opening required 'twc_support.php'" please email me
   you PHP version and what compiled options you have (e.g. phpinfo() ).
   The quick fix is to follow the line #'s stated in the error message and
   prepend the full path to the twc_weather directory. 


Installation
------------
1. Untar the ball into your plugins directory 
   (e.g. tar -zxvf twc_weather-0.9.tar.gz)

2. Take a look at config.php and modify as necessary
   In particular, take a look at the $location_def array
   to set defaults for your users when the add a new location.

3. Run SM configuration utility (conf.pl) and add the twc_weather as an active 
   plugin

4. On a per user basis the Options menu in SM will now contain a link to the 
   twc_weather configuration screen, displayed as "TWC Weather".


Motivation
----------
This is *yet another* weather plug-in for the venerable SquirrelMail web-based 
email client.  I was motivated to learn abit of PHP, SquirrelMail plug-in 
architecture, and most of all to fix a broken weather plug-in that I was always 
fond of--at least it was broken back when I made my original modifications last 
year.  twc_weather is based on Daniel Hemmerich (etal's) "Weather" plug-in 
v3.0.0 Credit should go to Dan and crew for the hardwork in creating the 
framework.

Currently twc_weather is in CVS at my house.  Please forgive the commit logging 
that's embedded into some of the source code.  But between it and my random 
comments maybe it will shed some light on the mayhem/chaos.

To Do
-----
Not much -- this plug-in is fairly solid (had a good base thanks to Dan!).  
Have been running on SM 1.2.x for sometime (~ 6 months) and limited testing and 
I've even been running it on SM-1.4.0-RC2a since it was released 
(The latter SM releases is where I focus most of my attention these days).  


-- Incorporate community feedback, bug fixes, feature requests, etc.

-- Reports received that the layout options contained in the twc_weather options
   screen for a specific weather location might not necessarily work.  Treating
   as a bug/incomplete feature to be resolved in a future revision.

-- Allow CVS access to public sites/users that would like to keep their plug-in
   up-to-date with the latest release (or patch).

-- Support the Auto Update plug-in (pupdate is the actual name, I believe).

-- Create a special weather statement alert icon to link to NWS special weather
   statements (that's what the stray alert.bmp file is lurking around for).

-- Determine a good release numbering scheme.



Support
-------
Since twc_weather-1.0-RC2 was officially released on the SM.org site there's 
been more than 700 downloads--and I've yet to receive any complaint/issue emails 
about installation.  Since the release is Beta quality I certainly expect to 
have a few linger bugs hanging out there.  So if you find yourself scratching 
your head don't hesitate to get in touch.  You're best bet is either the SM 
Plugins mailing list or to contact me via jamuel@my740il.com  And I will do my 
best to help you get going.

When sending a support email *BE SURE TO INCLUDE* your SM version and PHP 
version.  A dump from a phpinfoi() would also be useful.  If you don't know what 
phpinfo is just create a web page in your web servers htdocs path and include 
"phpinfo();" inside of /*<?php ?>*/ tags (w/o the quotes and w/o the /**/ 
characters.
 


(Previous) Credits/Notes
------------------------
        Original Author  .......  Daniel B. Hemmerich
        Contact  ...............  dan@spot.org

        Purpose  ...............  Grab a weather info from www.weather.com, based on the
                                  zip code provided by the user, and place it either
                                  before or after the folder list on the left (or right).
###


