[Chameleon-dev] code reorg and skinning support

[Paul Spencer]

All,

I am going to undertake a reorganization of the chameleon code.  The 
motivation is to enable easier management and maintainence of widgets. 
Currently there exist 92 widgets in cvs, most with 3 or more files.  It 
is becoming very difficult to manage.  This is a major change just 
before a beta release, but I feel it is necessary to ensure that anyone 
that adopts chameleon will be forward compatible in the most likely 
scenario.

I expect to break a lot of code doing this ... comments on that to 
follow ...

The change I am going to make is to move widgets into widget-specific 
sub-directories.

For instance, the BoundingBoxPopup widget and all associated files will 
be moved into a BoundingBoxPopup directory in the 
chameleon/htdocs/widgets directory.

The things I expect to have trouble with are:

* identifying all the files for each widget :( - which is partly why I 
am doing this now

* modifying the widget javascript code that launches popups to 
accomodate the change in web path to the widget popup page

* modifying complex (multipage) popups to accomodate this change also

* figuring out what to do with common code shared between several 
widgets.  I expect to leave these in the widgets directory.  This will 
include:

  - Widget.php
  - Button.php
  - common.dbf
  - CWC2ButtonCache.php
  - geomath.php
  - Label.php
  - NavTool.php
  - Popup.php
  - session.inc.php
  - utils.php

We also have a problem with other types of files like .js, .css, and 
.sld files required by widgets.  In these cases I will make a decision 
on a case by case basis.  There will still be a js directory in the 
widgets directory but it will only contain common code such as 
cwc_dhtml.js.  Other js files (like cwc_roi.js) will likely go with the 
widget ...

In addition to reorganizing the code base for widgets in this way, we 
will also be restructuring (hopefully for the final time) how images are 
handled and loaded.  This is necessary for a number of very good 
technical reasons, some of which are:

* file location is currently done in many places in *almost* the same 
way but with sometimes subtle differences.  This is very hard to 
maintain so we need a consolidated API for locating files

* there needs to be a mechanism to search for files in multiple 
locations including relative to the application, relative to chameleon, 
and possibly relative to other arbitrary locations.

* there is a desire to support skinning of applications via a simple to 
use protocol.  The intention is to provide a file location registry in 
the core of chameleon plus a file location API to return absolute paths.

The end result will be the replacement of the images directory in 
chameleon with a 'skins' directory.  Chameleon will likely ship with a 
default skin (called 'default' ;)) which will be the fallback if images 
and other files are not found anywhere else.  It will also likely ship 
with at least one other skin, and several more are in the works.

The skins/<skin-name> directory will contain (at least) 6 subdirectories 
as follows:

  - fonts
  - css
  - images
  - buttons
  - icons
  - borders

The application will automatically register the application path, the 
chameleon skins/default path, and the chameleon path with the file 
location registry.  For instance:

/ms4w/apps/chameleon/htdocs/
/ms4w/apps/myapp/htdocs/

The application developer can quickly change the look and feel of an 
application by including a (yet to be developed) widget called Skin that 
registers a new directory for searching.  This would look something like:

<cwc2 type="Skin" path="skins/myskin"/>

This would cause the following paths to be searched:

/ms4w/apps/myapp/htdocs/skins/myskin
/ms4w/apps/chameleon/htdocs/skins/myskin
/ms4w/apps/chameleon/htdocs/skins/default

Note that skins/default will be searched relative to chameleon if an 
image is not found elsewhere.

In order to take advantage of this capability, an application developer 
will specify images, fonts, css files etc using the subdirectory name 
followed by the resource name, for instance:

<cwc2 type=... image="icons/icon_refresh.png".../>

The naming convention that we will be using will provide for ease of use 
and ease of customization.  In addition, the widgets themselves will 
still be capable of using images and other resources specified using 
absolute paths (then no searching will take place).  Developers are free 
to make their own choices for naming but I suspect that our initial 
distribution will become the defacto standard for building skins.

The nice thing about having standard naming conventions between skins is 
that it enables switching skins by simply adding a different search path.

Another note about performance and searching.  It is expected that this 
will add some overhead to the initial load of the application, although 
I suspect that the overhead will actually be very small for most 
applications.  There is reasonably aggressive caching of image paths in 
most cases so the performance hit should only be incurred once in most 
cases.  If problems are identified we will look at more extensive 
caching mechanisms and possibly utilities for preprocessing templates to 
resolve all image paths prior to deployment (for example).

The overall goal is to provide a flexible but easy to use system for 
developers.  We want to enable rapid deployment of applications in the 
default case, but provide maximum capability to adopt chameleon in any 
environment regardless of UI restrictions ...

I expect the above changes to delay the beta release by at most one 
week.  At this point most major bugs have been cleared up and we are 
starting on lower priority items.  We would like to release a beta 
version that will have no significant changes planned, however, so hence 
the delay,

Thanks for your patience ...

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