[Chameleon] Chameleon 1.99 beta 3

[Paul Spencer]

All,

I'm pleased (believe me!) to announce the release of Chameleon 1.99 beta 
3.  The full release notes are available at:

http://www.maptools.org/chameleon/index.phtml?page=chameleon-1.99beta3.20041109.history.txt

I've included the release notes, new features and changes sections here 
for your convenience.  To get your new package, visit:

http://www.maptools.org/chameleon/index.phtml?page=download.html

As the note suggests, there are some important changes in this version, 
please read the following in its entirety before upgrading.

--

(PLEASE READ NEW FEATURES AND CHANGES BEFORE INSTALLING THIS VERSION OF 
CHAMELEON)

Those following Bugzilla activity will have noticed a flurry of activity 
recently.  This activity was all in aid of getting a new beta version of 
Chameleon 1.99 ready.  This newest version includes the final Chameleon 
features we were waiting on and bunch of bug fixes and core improvements 
that make Chameleon easier to work with and more stable.

This release, beta 3, will hopefully be the last beta release for 
Chameleon 1.99 and represents a full feature set for the final 1.99 
version.  However, it still contains a number of known issues that we 
will be working on resolving. (Search for target milestone RC 1 under 
the Chameleon product to see a list of issues.)

The current plan is to resolve outstanding issues recorded in Bugzilla 
and then release a first Release Candidate.  After a suitable period and 
further internal testing, we will likely release a second Release 
Candidate to be followed shortly (I hope) by a final version of 1.99.

Our goal for releasing version 1.99 is to have a set of basic, useful 
widgets that are stable and without known problems.  This does not mean 
that every widget available for Chameleon will be at this level of 
stability at the time of the final release of 1.99.  It is beyond our 
current resources to perform sufficient QA on all widgets and get the 
entire set of widgets up to a release standard.  These non-core widgets 
are likely to have known limitations or issues (listed in Bugzilla) that 
will not be addressed for the 1.99 release. At the same time, we do not 
mean that these non-core widgets won't be useable - in fact, most are 
already in active use in some of our projects.  As planning begins for 
future releases, addressing the remaining issues of highest priority 
will be targetted for the upcoming development cycles of Chameleon.

Widgets that will be considered stable will be clearly identified by the 
time we release the first Release Candidate.  We have added a new core 
feature (in bug 701) which assigns a maturity level to each widget.  The 
Chameleon configuration file has been expanded to include a 
'maturity_level' parameter which can be set to one of the predefined 
maturity levels.  This parameter prevents applications from being able 
to access widgets below this maturity level.  Applications can also 
override this value to set a lower or higher minimum maturity level. 
The net effect of this will be that you, the application developer, will 
knowingly have to make a choice to use widgets which may not be fully 
tested or even stable.

The maturity levels that are currently available for use, and their 
definitions, are:

UNKNOWN - the base level at which all widgets start
ALPHA - in development, incomplete functionality, no documentation 
(other than auto generated)
BETA - in development, functionally complete, no know major bugs, no 
documentation (other than auto generated)
RELEASECANDIDATE - out of development, no know bugs, limited testing, 
little documentation (other than auto generated)
TECHNICALRELEASE - out of development, few known bugs (all minor), 
thoroughly tested, widget doc completed
PRODUCTRELEASE - out of development, no known bugs, thoroughly tested, 
all documentation completed

The large majority of available widgets currently have a maturity level 
of BETA (with a few at ALPHA). As further releases of 1.99 come out, 
these maturity levels (in particular, for the basic set of widgets) will 
move along the spectrum of values. Widgets without set maturity levels 
are considered to have the maturity level of UNKNOWN.

There will be more on the maturity system in the documentation available 
for 1.99 RC 1.

NOTE: it is quite likely that, when you install this beta version of 
Chameleon, you will run into issues related to this maturity level 
change.  By issues, I mean that some widgets will no longer appear in 
your application, especially custom widgets.  Do not panic - this is 
normal.  To account for this, you will need to do one of the following:

* modify any widget that is failing to appear by including a line in the 
widget's constructor, as follows:

$this->mnMaturityLevel = MATURITY_<level>;

where <level> is at least as high as the level specified in your 
chameleon.xml file's maturity_level setting. (If it's not in there, copy 
from chameleon.xml-dist and set appropriately.)

* modify your application to accept a lower maturity level by adding the 
following line AFTER $oApp->CWCInitialize():

$oApp->mnMinimumMaturityLevel = MATURITY_<level>;

You will probably want to use UNKNOWN for <level>. This will have the 
effect of allowing all widgets to be used, regardless of maturity level.

* modify your chameleon.xml to set a lower overall maturity level, i.e.:

     <context-param>
           <param-name>maturity_level</param-name>
           <param-value>UNKNOWN</param-value>
           <description>This option controls the widgets that will be 
available to Chameleon applications.  Only widgets at or above the 
configured level will be accessible.  Levels in increasing order of 
maturity are: UNKNOWN, ALPHA, BETA, RELEASECANDIDATE, TECHNICALRELEASE, 
PRODUCTRELEASE.  See Chameleon documentation for a description of these 
maturity levels.  </description>
     </context-param>

END NOTE.


New Features
============

* added a documentation builder and help file viewer for widget-level 
documentation.  The documentation builder is primarily an internal tool 
at this point; it provides support for generating and maintaining 
documentation in xml format for all widgets.

The help viewer is an application developer tool that allows browsing of 
the Chameleon documentation, in particular the widget-specific 
information.

NOTE: The help viewer requires the php_xslt module.  See your PHP 
documentation for instructions on enabling this module.  For MS4W users, 
release 1.0 of MS4W makes this module available by default.  Previous 
versions will not work without modification, specifically the dlls in 
php/dlls must be moved to the cgi-bin directory.

The auto-generated documentation building system has undergone a serious 
overhaul and is targeted at longer term needs, including multilingual 
support and support for processes other than end-user documentation 
(like QA).  For this release, it is primarily an internal tool so there 
are likely to be problems in other configurations.  We will be expanding 
our testing to improve its stability in the next release.  Note that 
this tool is not for application developers - it is for widget 
developers and documentation maintainers.  Use at your own risk!

* bug 565: added new ContextSelector widget which allows for a preset 
list of contexts to be defined. They are displayed as a select box in 
the page.  Choosing a context from the list loads the associated context 
and resets the legend/view extents and projection appropriately.

* added new MapTitle widget that displays the title of the current 
mapfile, useful with the ContextSelector widget or any app that allows 
changing map files.  Uses metadata wms_title over map name, if possible.

* bug 583: added new LayerOrder widget based on code provided by GeoDan, 
allows user to promote and/or demote layers in the application by 
combining with the SelectLayers widget and an appropriately crafted HTML 
legend template (LegendTemplate widget).

* bug 583: added new RemoveLayer widget, allows users to permanently 
remove a layer from the view/map file by combining with the SelectLayers 
widget and an appropriately crafted HTML legend template (LegendTemplate 
widget).

* added an implementation of the ZoomSelectedLayers widget (previously 
unfinished).  Requires MapServer 4.3 (4.4).

* bug 629: created a generic JavaScript event management system 
(implemented in cwc_event.js).

* added new widget, ExtractSR, that allows the user to download the 
contents of a SharedResource as a CSV file.  To be useful, this needs to 
be used with a widget that populates a SharedResource (such as SQLQuery) 
and a SharedResource widget that both point to.

Changes
=======

* removed some deprecated files.

* refactoring of duplicated code.

* added getRemoteFile and loadContext to Chameleon core class to 
simplify widgets that work with remote files.

* streamlined and simplified all code that loads files to seamlessly 
detect and load remote files and local files in a consistent manner. 
(That is, all local relative paths are considered relative to the 
application now).

* modified TemplateParser to allow default values to be specified in the 
preprocessor engine.  New format is [$<value>|<default>$].  Now, if 
<value> is not set in POST/GET then <default> will be substituted 
instead of just leaving the [$ $] tag.  It is valid to specify an empty 
string using [$<value>|$].

* enhanced some of the internal error handling code to be more 
descriptive in a number of cases.

* bug 424: LegendTemplate
     added a CONTROLVISIBILITY="<true|false>" attribute to allow 
template designers to work around a problem combining multiple legend 
templates (and, specifically, LayerManager2).

* bug 621: UIManager
     added global handling of ENABLED="false" in widgets.

* moved the contents of the chameleon/html directory into the new docs 
directory under html.  New structure allows for multiple formats since 
we are maintaining the core documentation in DocBook (xml) format.  Core 
documents will now go in chameleon/docs/xml and html documents generated 
from them are in chameleon/docs/html.

* bug 454: php_geocoder
     updated watershed lookup service code to point to the new home of 
the watershed lookup service.

* added zip to the common directories used by Chameleon.

* bug 520: HelpWidget
     updated for new help file structure, renamed to EmbeddedHelp.

* bug 635: Language
     deprecated Language widget by moving language capability into the 
core of Chameleon - it is now always in every application.  Updated 
samples accordingly.

* improved MapTips widget to allow for application-defined onmouseover 
and onmouseout events.

* updated sample applications to showcase the new widgets and new 
attributes on existing widgets.

* bug 659: added persistent queries to query capability, supported by 
the core of Chameleon and initial implementation in the Query widget. 
This feature uses the Mapscript functions saveQuery and loadQuery to 
persist query results.  The core of Chameleon simply looks for a query 
file in the session and restores it using loadQuery, if found.  The 
Query widget has additional attributes to make queries persistent and it 
saves the results of a query in the session, if appropriate.  This 
mechanism makes it possible for other query tools to generate the query 
files as well.  Also added ClearQueryResults widget to remove persistent 
queries.

* completely revamped the administration pages, including a number of 
bug fixes and reworking the interface to be more useable.  The admin 
pages have also been moved in CVS from htdocs_admin to admin/htdocs 
which is more in line with the structure of the rest of Chameleon.

* bug 782: added more template validation, now extraneous attributes 
(those not defined for the widget) are reported as errors through the 
error manager if template validation is turned on in the configuration 
file.

* added support for running from a CD or auto-mounted usb device. 
(experimental)

* bug 701: added support for maturity levels to the Chameleon core and 
existing widgets.  Developers must now indicate the maturity level of a 
given widget and application developers can choose an acceptable 
maturity level for their applications.  The Chameleon framework will 
then automatically restrict access to widgets that are below the 
acceptable maturity level.  This change will also help QA and 
documentation maintainers to provide a more robust product.


-- 
Cheers,

Paul

+-----------------------------------------------------------------+
|Paul Spencer                           pspencer at dmsolutions.ca   |
+-----------------------------------------------------------------+
|Applications & Software Development                              |
|DM Solutions Group Inc                 http://www.dmsolutions.ca/|
+-----------------------------------------------------------------+