I think it could be good to document the new mechanism to support deprecated
widget name.


We should also list somewhere widgets that are renamed:


MapDHTMLWidget -> MapDHTML
PrintWidget -> PrintProduction
HelpWidget -> EmbeddedHelp


---------------------------
Paul Spencer wrote:

> All,
>
> bugs 632 and 377 concern renaming widgets that have been in existance for
quite a while.  While the renaming itself is reasonably trivial, this will cause
existing templates to break immediately.
>
> To counteract this, I've added a widget renaming scheme in WidgetManager.php.
>
> I don't want to support old widget names indefinitely, so the widget renaming
is keyed to Chameleon versions.  There's no concept of a version in the code, so
I have added the following in chameleon.php:
>
> /*
>  * chameleon API version.
>  * The API version started with version 1.99.
>  * It is used by some components (starting with the widget name
>  * mapping in WidgetManger.php) to define an API version.  It
>  * can be expected that the API will be consistent between POINT
>  * versions but can change between MAJOR and MINOR versions.
>  *
>  * It could also be used for widgets that require a certain API
>  * version to work in the future.
>  *
>  * There are 5 values defined:
>  *
>  * CHAMELEON_MAJOR_VERSION - the major release number
>  * CHAMELEON_MINOR_VERSION - the minor release number, odd is dev, even is stable
>  * CHAMELEON_POINT_VERSION - a bugfix release within a minor version
>  * CHAMELEON_STATE_VERSION - a qualifier like ALPHA or BETA
>  * CHAMELEON_VERSION - a combination of the above, in the form:
>  *
>  * 1.99.0
>  * 2.2.0-beta3
>  *
>  *
>  */
> define( "CHAMELEON_MAJOR_VERSION", "1" );
> define( "CHAMELEON_MINOR_VERSION", "99" );
> define( "CHAMELEON_POINT_VERSION", "0" );
> define( "CHAMELEON_STATE_VERSION", "beta3" );
>
> define( "CHAMELEON_VERSION", CHAMELEON_MAJOR_VERSION.".".
>                              CHAMELEON_MINOR_VERSION.
>                              (CHAMELEON_POINT_VERSION == '' ? '' : "-" ).
>                              CHAMELEON_STATE_VERSION );
>
> Currently this is used only by the WidgetManager to associate versions with
deprecated widget names.  But I can see us using this in the future when we
distribute widget packs or individual widgets that might be installed into older
(or newer) chameleon installations.  The comments in the code say it all ...
>
> /*
>  * global mapping array for widgets that change their name
>  *
>  * widgets that get their name changed can be registered here to ensure
>  * backwards compatibility for several versions
>  *
>  * array uses old name as a key with new name and three version numbers:
>  * version 1 - the version that the name changed
>  * version 2 - the version at which warnings should appear
>  * version 3 - the version at which errors should appear
>  *
>  * at version 2, widgets will still work under the old name but a warning will
>  * be logged in the error manager
>  *
>  * at version 3, widgets will cease to work and will appear in RED in the
template.
>  *
>  * example:
>  * $GLOBALS['gaszRenamedWidgets']['MapDHTMLWidget'] =
>  *     array( "MapDHTML", "1.99", "2.2", "2.4" );
>  *
>  * NOTE that only the MAJOR and MINOR numbers are used in this comparison
>  */
>
> $GLOBALS['gaszRenamedWidgets'] = array();
>
> //bug MT 632: rename MapDHTML widget
> $GLOBALS['gaszRenamedWidgets']['MapDHTMLWidget'] =
>     array( "MapDHTML", "1.99", "2.2", "2.4" );
>
> so that existing templates will work without warning until we declare version
2.2 in the defines, and won't work when we declare 2.4 in the defines.
>
> Make sense?  This has all been committed to cvs (just now) so any problems
should be reported asap.
>
> Cheers,
>
> Paul
> _______________________________________________
> Chameleon-dev mailing list
> Chameleon-dev@lists.maptools.org
> http://lists.maptools.org/mailman/listinfo/chameleon-dev
>