    CANADIAN
    __        __         _   _
    \ \      / /__  __ _| |_| |__   ___ _ __
     \ \ /\ / / _ \/ _` | __| '_ \ / _ \ '__|
      \ V  V /  __/ (_| | |_| | | |  __/ |
       \_/\_/ \___|\__,_|\__|_| |_|\___|_|

            "It's Canadian, eh!"

----[ Program

    Canadian Weather


----[ Lead Developer

    Jonathan S. Earle (plugins@kronos.honk.org) 


----[ Contributors

    Michael Connors
    Attos Janus
    Chauncey Widdup
    Daniel B. Hemmerich (Author of original weather plugin)


----[ Home Site

    Canadian Weather avaliable at: 
      http://kronos.honk.org/~earlej/can_weather_current.tar.gz


----[ Purpose

    Retrieves weather info from Environment Canada (weatheroffice.ec.gc.ca),
    based on the province and region code provided by the user, and place it
    either before or after the folder list on the left (or right).


----[ Requirements

    o Squirrelmail 1.4.x/1.5.x (tested on SM 1.4.15)
    o Javascript enabled in the client browser to run the config tool. There
      is a workaround provided for non-Javascript users, but the config tool
      will work much nicer with JS enabled.
    o Mozilla / Firefox.


----[ Features

    o The ability to be placed above or below the folder list.
    o Automatically detect whether it should be activated or not based on
      whether or not a region code was entered.
    o Plugin also automatically detects whether the folder width is great enough
      to display the weather info. If the folder width is less than 160 pixels,
      the plugin automatically sets it to 160. This feature is only activated if
      a region code has been entered.
    o Weather is bilingual!
    o Weather displays using either metric or imperial units.
    o Canadian Weather is configured within the General Options page.


----[ Future Changes

    o Got any ideas or complaints, please let me know!


----[ Installation

    To install weather, do what you would do with any other plugin. Decompress
    it in the plugins/ directory, and then run conf.pl in config/ in the base
    squirrelmail directory.

    Do not worry if you have several users and fear that the default is for
    this plugin to be active, it is not. This plugin will only be activated for
    a user if that user enables it by selecting a region to display conditions.

    If you have trouble with plugin installation in general, please send an
    e-mail to squirrelmail-plugins@lists.sourceforge.net, after of course 
    reading the online documentation.

    If you have an inquiry specific to this plugin, feel free to contact me at
    the above address.


----[ Known Issues

    o Found during testing that if you disable Javascript in the Display
      Preferences and then configure Canadian Weather, that the province, which
      may have been set previously, will be erased since it's not put onscreen
      for the non-Javascript users (it's not needed by itself for the plugin to
      work - it's only really used for the config tool).  When you enable
      Javascript, the province and the region (which is keyed off the province)
      are not shown onscreen, meaning you have to reselect them.  Not a big
      deal, but might cause some head scratching if you didn't expect it (not
      that many people are going to do this anyway).


----[ Changelog

	June 27, 2008 - version 3.2.0

	  o Major change.  EC whacked their site again and I've had to go back to
	    the old, ugly parsing method of extracting data. Their RSS feed holds
  	    promise but doesn't include all information (specifically, the weather
	    conditions icon).

    Aug 3, 2007 - version 3.1.6

      o Fixed another EC change plus fixed a bug (similar to that fixed in
        3.1.4) found during region list retrieval.

    May 22, 2007 - version 3.1.5

      o EC made another change.  Fixed.
      o Removed a debug statement I'd left in by mistake.

    Apr 17, 2007 - version 3.1.4

      o Looks like EC made a change.. had to fix the URI used to request pages.
      o Fixed an error returned in some weather pages.. looks like a mistype
        in one of their templates.
      o Tweaked the stylesheet to look a little better.

    Mar 02, 2007 - version 3.1.3

      o Fixed the display of weather warnings/watches to handle the case where 
        EC sets multiple warnings for a given region.

    Feb 24, 2007 - version 3.1.2

      o Fixed a bug pulling provincial region data from EC (page changed).
      o Fixed (worked around) that minor display issue within IE.

    Nov xx, 2006 - version 3.1.1 (not released)

      o Added more versioning info required by newer plugin architecture.
      o Implemented code pointed out by Michael Connors to allow the options
        page to work in 1.5.x.
      
    Nov 11, 2006 - version 3.1.0

      o Fixed bug that prevented plugin from working on IE.  Last minute code
        change worked on Firefox (my main browser) and I neglected to run a 
        final test on IE before releasing the plugin.  Doh!
      o Updated stylesheet to format weather watches and watches/warnings that
        have ended.
      o Improved bilingualism of plugin to include the configuration page.
      o Saved settings will now be highlighted in config page.
      o Allow users who do not have Javascript to directly enter the EC region 
        code for the plugin.  To use, navigate to the weather page for your
        city/region on EC's website (weatheroffice.ec.gc.ca) and copy/paste the
        code into the text entry field on the plugin config page. The code can be
        determined from the URL thusly:
        
          http://weatheroffice.ec.gc.ca/forecast/city_e.html?on-118&unit=m
                                                Region Code: ^^^^^^

    Oct 30, 2006 - version 3.0.0

      o Complete rewrite!  Environment Canada changed their site (completely)
        and so the old code wouldn't work at all.  Needed a useful config tool
        but that means that Javascript must be enabled.  No workaround at this
        time other than manuall entering the region code into the user.pref 
        file.
      o Tested with squirrelmail 1.4.7... might need a tweak for 1.5.x.
      o IE stylesheet not yet created .. subsequent release will address.

    Oct 20, 2003 - version 2.2.2 
      o Fixed problem with SM 1.4.x.  Preferences wouldn't save and the plugin
        wouldn't show onscreen.

    Oct 7, 2003 - No version # change.
      o Updated contact email address.

    Feb 24, 2003 - version 2.2.1
      o Fix for folder width resizing problem.  Plugin always reset folder size to 
        160px even if user set size greater.  Fix contributed by Chauncey Widdup.

    Feb 23, 2003 - version 2.2.0
      o Environment Canada changed their site!  This plugin works with the new site.
      o Added ability for user to select English or French weather.
      o Shows weather warning headlines with links to warning details.
      o Entire weather block is retrieved and displayed, no more hunting and pecking 
        for specific values.  Upshot is, EC can include anything they want in the 
        data and it will be displayed.

    Jan 31, 2003 - version 2.1.1a
      o Documentation update.  No code changes.

    September 20, 2001 - version 2.1.1
      o Added Humidex if reported by EC.
    
    March 15, 2002 - version 2.1.0
      o Adapted Daniel B. Hemmerich's v2.0.0 plugin for use by Canadians.
      o Initial release.
