[Chameleon] Chameleon 1.99 Beta 2
Paul Spencer
pagameba at magma.ca
Wed Jul 28 07:57:07 EDT 2004
All,
***********************************************************************
* *
* NOTE: if you are an existing user of Chameleon 1.99 beta1 or some *
* CVS version, it is very important to read the note on configuration *
* changes in the New Features section. *
* *
***********************************************************************
Chameleon 1.99 Beta 2 is now available, it is based on the CVS version
as of 9 July 2004.
It can be downloaded from the following locations:
Linux (tar.gz):
---------------
http://www.maptools.org/dl/chameleon-1.99beta2.tar.gz
Windows (zip):
--------------
http://www.maptools.org/dl/chameleon-1.99beta2.zip
Windows MS4W (zip):
-------------------
http://www.maptools.org/dl/chameleon_ms4w-1.99beta2.zip
New Features:
-------------
* bug 343: added a new Service Instance mode for Chameleon, called cwc2.
cwc2 is a subdirectory of the chameleon installation and is an
application built upon chameleon that allows remote users to create
applications without a local installation of chameleon. Documentation is
still coming for this, this should be considered an ALPHA feature for
this release. There is more information on the service instance at the
end of this email (see CWC2 Service Instance Notes below)
***********************************************
* *
* CONFIGURATION FILE CHANGES - VERY IMPORTANT *
* *
***********************************************
With the addition of the service instance (called cwc2), I have finally
fixed up the configuration files. The configuration file in beta1 was
called cwc2.xml for historical reasons (since chameleon was originally
called CWC2). It contained several parameters that were only really
needed by the service instance but I left them in because I knew that
this service instance was coming back at some point. So now that it is
back, I have split the configuration file into two separate files,
chameleon.xml and cwc2.xml. It is NOT sufficient to rename your
cwc2.xml to chameleon.xml. The splitting process resulted in the
removal of some completely unnecessary elements, the adding of new
parameters, and changing the names of some elements.
You MUST start from the xml-dist versions of these files. You will find
that you can copy some settings from the existing cwc2.xml into the
appropriate place in either chameleon.xml or the new cwc2.xml.
For ms4w users, the package comes pre-configured so you don't have to
worry about this at all.
For non-ms4w users, you may want to check out the ms4w version's
configuration files if you are having difficulty.
*** back to the release notes ***
* added sample xml and xsd documents for upcoming widget documentation
system.
* bug 478: updated the cwc2.xml file for ms4w installations
* bug 101: added a link to the service instance in the ms4w package
* added the picker common utilities to the chameleon build process
* added ms4w directory to cvs to house the ms4w configuration files,
updated the Makefile to allow creation of the ms4w distribution files
directly.
Changes:
--------
* KeyMapDHTML2 renamed to KeyMapDHTML
* updated CWC2_INSTALLATION.txt for version 1.99, still needs works and
should be renamed
* bug 367: added optional compression formats as widget attributes to
the ExtractWFSData widget, and added ZIP to the available formats.
Bug Fixes:
----------
* bug 440: removed session variables relating to the GD module and
FreeType version as part of cleaning up the configuration files.
* removed extraneous error messages
* added colorpicker to the build process for SECTPopup
* bug 443: fixed a problem with figuring out the application web path
under some circumstances
* bug 444: fixed a problem in popup dialogs if the requested
popupstyleresource was not also referenced as a styleresource somewhere
in the template
* bug 445: fixed a problem in popup dialogs if no styleresource or
popupstyle resource is used, buttons are now represented as HTML buttons
in this case.
* bug 446: fixed naming issue in many of the sample templates
(ReferenceLayer was incorrectly named InfoLayer)
* fixed include path problem in KeepSessionAlive widget
* bug 398: fixed problem with KeyMapDHTML widget when the aspect ratio
of the keymap was not the same as the main map
* bug 453: modifications to enable JSAPI mode again
* fixed bug 392
* bug 422: added widgetclass attribute to Scale widget
* bug 320: fixed a problem with getWFSConnection if the connection is
invalid
* Added GetAvailableWidgets function to list all available widgets
* bug 480: capture missing default context or template errors and
present as a service exception
* bug 501: fix a problem with Button.php, button names were being used
as the name/id of html elements but the button names were randomly
generated and could start with a number, which is invalid for use as a
name in HTML.
* bug 93: widgets can now exist on different forms by setting the
formindex attribute. This also fixed a problem with widgets not
respecting the visible and enabled attributes.
* bug 486: fixed syntax error in HelpWidget
* bug 104: fixed a bug related to widgets that should never be part of
toolsets, but were able to be.
* bug 190: fixed a bug in the ROIRenderer when drawing ROIs and the
session is expired, the ROI image became broken. Now it displays
"session expired".
* fixed a problem in the LegendTemplate widget where deleted layers
would be 'undeleted' if they were previously visible before deleting them.
CWC2 Service Instance Notes
---------------------------
In lieu of real documentation, I'm providing some working notes at this
time. This will eventually show up in one of the chameleon documents :)
**** CWC2 Users Guide ****
Installing the CWC2 Service Instance
====================================
The CWC2 Service Instance is installed with the Chameleon package by
default. To access the Service Instance, you will need to adjust your
system configuration and edit the Service Instance configuration file to
reflect your system's configuration.
Note that the Service Instance requires a properly installed and
configured Chameleon package, please follow the Chameleon installation
instructions and ensure that Chameleon is fully functional before
attempting to configure the Service Instance.
System Configuration
====================
You will need to configure your Web Server to grant access to at least
one directory in the service instance. Two other directories are
optional. The following table is a suggested configuration:
URL Required? Path
--------------------------- --------- -------------------------------
http://<myserver>/cwc2 YES <install-path>/chameleon/cwc2/htdocs/
http://<myserver>/templates NO
<install-path>/chameleon/cwc2/templates/
http://<myserver>/contexts NO
<install-path>/chameleon/cwc2/contexts/
Service Instance Configuration
==============================
You will need to make a copy of the cwc2.xml-dist file found in the
<install-path>/chameleon/config folder and name it cwc2.xml. You will
need to edit at least some of the settings found in this file. Each
configuration item is described in the xml document, but as a minimum
you should review the following items:
Config Item Set to ...
--------------------- -----------------------------------------------
service_instance_path URL to service instance htdocs folder (from above)
server_data_path <install-path>/chameleon/cwc2/data
default_context
<install-path>/chameleon/cwc2/contexts/world_context.xml
default_template
<install-path>/chameleon/cwc2/templates/sample_cwc2.html
context_root <install-path>/chameleon/cwc2/contexts/
template_root <install-path>/chameleon/cwc2/templates
fontlist_file <install-path>/chameleon/cwc2/etc/fonts.txt
symbol_file <install-path>/chameleon/cwc2/etc/symbols.sym
Testing the Service Instance
============================
Assuming that the above configuration is implemented correctly, the
Service Instance should now be fully functional. You can test your
Service Instance by connecting to the following URL:
http://<myserver>/cwc2/cwc2.php
You should receive the following message:
request URI was http://<myserver>/cwc2/cwc2.php
query string was
Missing mandatory SERVICE parameter
This error message means that the Web Server is correctly providing
access to the Service Instance.
Normally, the Service Instance is configured to provide a default
application and context. If you followed the instructions above, you
can access the default application and context by connecting to the
following URL:
http://<myserver>/cwc2/cwc2.php?service=VCG&request=GetApplication&version=0.1.0
Please read the CWC2 Service Instance Users Guide to find out more about
communicating with and using the features of the Service Instance
Getting Help
============
The CWC2 Service Instance is part of the Chameleon package available
from http://www.maptools.org. Please visit the Chameleon web site at
http://www.maptools.org/chameleon to access information about using
Bugzilla and the Chameleon users mailing list.
**** CWC2 USERS GUIDE ****
CWC2 Service Instance Users Guide
=================================
Getting Started
===============
Please refer to the CWC2 Service Instance Installation Guide for
instructions on getting your Service Instance installed and tested.
This document assumes that you have a fully functional and correctly
configured Service Instance.
Terms and Definitions
=====================
CWC2 - TBD
Service Instance - TBD
Chameleon - TBD
CWC2 Service Instance Server - TBD
Application - TBD
...
Basic Concepts
==============
The CWC2 Service Instance is an application built on top of the
Chameleon engine that allows application developers to create web
mapping applications by creating an Application Template and a Web Map
Context document. It will only work with WMS layers.
The CWC2 Service Instance is a web service that can be invoked by
clients using only a web browser.
Service Exceptions
==================
A Service Exception is the term used to describe the result of an error
that happens in the CWC2 Service Instance. The CWC2 Service Instance is
designed to capture internal errors and report them in a standard,
machine-parsable way using structured XML documents. Whenever an error
is trapped internally, CWC2 will generate and return a Service Exception
instead of the application. The intention is to provide sufficient
information to the user to allow for troubleshooting of the problem that
caused the Service Exception to be triggered. Service Exceptions can
happen at any time and for a wide variety of reasons.
<NOTE: service exceptions are currently just plain text>
Common Request Parameters
=========================
This section describes parameters that are common to every invocation of
the Service Instance.
REQUEST
-------
The REQUEST parameter indicates which operation is being invoked and its
value is one of the names of the operations supported by the service
instance. The REQUEST parameter is mandatory in every invocation of the
service instance.
VERSION
-------
The VERSION parameter indicates the protocol version number and is
mandatory in every invocation of the service instance.
SERVICE
-------
The SERVICE parameter indicates the service that is being requested.
Some web services can be configured to provide multiple services through
the same base URL. In the case of CWC2, this is not yet possible,
however, this parameter is provided for compatibility with existing
services and for possible future requirements. The SERVICE parameter is
mandatory in every invocation of the service instance.
Supported REQUESTs
==================
The CWC2 Service Instance supports two REQUESTs, described below.
GetCapabilities
===============
<NOTE: not yet implemented>
The purpose of the GetCapabilities operation is to describe the
operating parameters of a particular Service Instance to enable clients
to use the service in an effective manner.
GetCapabilites Request Parameters
---------------------------------
The GetCapabilities operation has three mandatory paramters, SERVICE,
REQUEST and VERSION, described in the following table:
Parameter Required/ Description
Optional
SERVICE=VCG R Service name, must be VCG.
REQUEST=GetCapabilities R request name, must be GetCapabilities
VERSION=<version> R supported protocol version number
GetCapabilities Reponse
-----------------------
The response to the GetCapabilities request is an XML document. This
feature is not yet implemented.
GetApplication
==============
The purpose of the GetApplication operation is to generate a client
application based on the parameters provided when invoking the service.
GetCapabilites Request Parameters
---------------------------------
The GetApplication operation has three mandatory paramters and six
optional parameters described in the following table:
Parameter Required/ Description
Optional
SERVICE=VCG R Service name, must be VCG.
REQUEST=GetApplication R request name, must be GetApplication
VERSION=<version> R supported protocol version number
LANGUAGES=<list> O a list of languages
TEMPLATES=<list> O a list of application template paths or
URLs
CONTEXTS=<list> O a list of context paths or URLs
LANGUAGE=<lang> O the language to display
BBOX=<list> O a comma separated list of coordinates
that describe the initial spatial
extents
to be displayed to the user
SRS=<srs> O a spatial reference system, must be
a valid
EPSG code, to be used for the
initial map
view.
LANGUAGES
---------
A list of language specifiers separated by commas. Languages are
specified in the form of a two-character language code followed by a
dash and a two character country code. Service instances will list
supported languages in the capabilities document. Unsupported languages
may be requested, but the service instance will use the default language
for unsupported languages.
This parameter is optional unless TEMPLATES is set, in which case it is
mandatory.
TEMPLATES
---------
A list of application template paths or URLs separated by commas. A
template is identified by either a relative path on the server (relative
to the template root directory specified in the service instance
configuration) or a URL to a web-accessible template. The templates are
listed in the same order as the LANGUAGES, with one template required
for each supported language (even if the same template supports every
language). URLs must be in the standard
http://<server>/path/template.html format and must be URL-encoded.
This parameter is optional unless LANGUAGES is set, in which case it is
mandatory. The service instance defines a default template in its
configuration file.
CONTEXTS
--------
A list of web map context paths or URLs separated by commas. A
context is identified by either a relative path on the server (relative
to a directory specified in the service instance configuration) or a URL
to a web-accessible context. The contexts are loaded in the order in
which they appear in this value, and the projection and spatial extents
are taken from the last context loaded (see Common Problems below). The
order of the contexts determines the order in which the layers of each
context are drawn. Layers from the first context in the list are drawn
first, layers from later contexts are drawn 'on top' of earlier ones.
URLs must be in the standard http://<server>/path/template.html format
and must be URL-encoded.
This parameter is optional. The service instance defines a default
value in its configuration file.
LANGUAGE
--------
The lanuage to use to display the application. This will cause one of
the templates to be selected from the available TEMPLATES.
This parameter is optional. The service instance defines a default
value in its configuration file.
BBOX
----
The BBOX provides a mechanism to define a different set of initial
spatial extents that the default. By default, the Service Instance will
use the extents defined in the last context opened. This may not be
appropriate in all cases, especially when providing multiple contexts.
The format for this parameter is to provide a comma-separated list of
values in the following order:
BBOX=<MINX>,<MINY>,<MAXX>,<MAXY>
The values are specified in georeferenced coordinates and depend on the
spatial reference system of the initial view.
SRS
---
The SRS provides a mechanism to define a different spatial reference
system that the default. By default, the Service Instance will use the
SRS defined in the last context opened. This may not be appropriate in
all cases, especially when providing multiple contexts. This parameter
must use EPSG codes in the following format:
SRS=EPSG:XXXXX
Common Problems
===============
Paths to TEMPLATES and CONTEXTS
-------------------------------
When specifying a template or a context, you must do so in relation to
the Service Instance server. This means that if the context or template
that you wish to access is on the Service Instance server, then it must
reside in the Service Instances defined template directory or context
directory (or a subdirectory of these). If the context or template is
not on the Service Instance server, then you must refer to it using a
valid URL. It is very important to note that the URL will be opened
from the Service Instance server, so a URL that refers to localhost:
http://localhost/mytemplates/app1.html
will most likely NOT work. This is because the Service Instance, when
it tries to open this URL, will be pointing to itself, most likely not
the situation you intended.
Multiple CONTEXTS appear wrong
------------------------------
When specifying multiple CONTEXTS, the Service Instance will load them
sequentially and use the BBOX and SRS defined in the last context it
loads. It is quite possible that the BBOX and SRS in the last context
you want to load are not valid for all the contexts that you are trying
to load. For instance, if you try to load the world_context.xml and the
gmap_context.xml (in that order) that come with the service instance,
the world data will be displayed in LCC projection and will not appear
to 'line up' with the gmap data. The problem is that the projection is
invalid for extents beyond Canada. To fix this problem, you can
manually provide a BBOX and SRS as part of the request. In this case,
changing the SRS to EPSG:4326 displays everything correctly.
Limitations
===========
The CWC2 Service Instance will only work with data that is accessible
via WMS
The CWC2 Service Instance does not allow applications to define and
access custom widgets unless they are installed in the Chameleon
instance that the CWC2 Service Instance is configured to use.
*** end CWC2 USERS GUIDE ***
Some example invocations:
The base URL to the service instance is (note this is an invalid request):
http://localhost/chameleon/cwc2/cwc2.php
The URL to get the Service Instance capabilities is (note this doesn't
do anything yet):
http://localhost/chameleon/cwc2/cwc2.php?service=VCG&request=GetCapabilities&version=0.1.0
The URL to get the default template, context and language is (note this
is the most basic valid request):
http://localhost/chameleon/cwc2/cwc2.php?service=VCG&request=GetApplication&version=0.1.0
The URL to get a single local template for a given language is:
http://localhost/chameleon/cwc2/cwc2.php?request=GetApplication&version=0.1.0&LANGUAGES=en-CA&TEMPLATES=sample_cwc2.html
The URL to get a single remote template for a given language is:
http://localhost/chameleon/cwc2/cwc2.php?request=GetApplication&version=0.1.0&LANGUAGES=en-CA&TEMPLATES=http://localhost/chameleon/cwc2/templates/sample_cwc2.html
The URL to get a bilingual application using local templates is:
http://localhost/chameleon/cwc2/cwc2.php?request=GetApplication&version=0.1.0&LANGUAGES=en-CA,fr-CA&TEMPLATES=sample_cwc2_en.html,sample_cwc2_fr.html
The URL to get a bilingual application using remote templates is:
http://localhost/chameleon/cwc2/cwc2.php?request=GetApplication&version=0.1.0&LANGUAGES=en-CA,fr-CA&TEMPLATES=http://localhost/chameleon/cwc2/templates/sample_cwc2_en.html,http://localhost/chameleon/cwc2/templates/sample_cwc2_fr.html
The URL to get a single local context using default template and
language is:
http://localhost/chameleon/cwc2/cwc2.php?service=VCG&request=GetApplication&version=0.1.0&CONTEXTS=gmap_context.xml
The URL to get a single remote context using default template and
language is:
http://localhost/chameleon/cwc2/cwc2.php?service=VCG&request=GetApplication&version=0.1.0&CONTEXTS=http://localhost/chameleon/cwc2/contexts/gmap_context.xml
The URL to get multiple local contexts using default template and
language is:
http://localhost/chameleon/cwc2/cwc2.php?service=VCG&request=GetApplication&version=0.1.0&CONTEXTS=world_context.xml,gmap_context.xml
The URL to get multiple remote context using default template and
language is:
http://localhost/chameleon/cwc2/cwc2.php?service=VCG&request=GetApplication&version=0.1.0&CONTEXTS=http://localhost/chameleon/cwc2/contexts/world_context.xml,http://localhost/chameleon/cwc2/contexts/gmap_context.xml
The URL to get a fully remote, bilingual application using multiple
contexts is:
http://localhost/chameleon/cwc2/cwc2.php?service=VCG&request=GetApplication&version=0.1.0&LANGUAGES=en-CA,fr-CA&TEMPLATES=http://localhost/chameleon/cwc2/templates/sample_cwc2_en.html,http://localhost/chameleon/cwc2/templates/sample_cwc2_fr.html&CONTEXTS=http://localhost/chameleon/cwc2/contexts/world_context.xml,http://localhost/chameleon/cwc2/contexts/gmap_context.xml
The URL to get a fully remote, bilingual application using multiple
contexts, and defining an SRS and BBOX:
http://localhost/chameleon/cwc2/cwc2.php?service=VCG&request=GetApplication&version=0.1.0&LANGUAGES=en-CA,fr-CA&TEMPLATES=http://localhost/chameleon/cwc2/templates/sample_cwc2_en.html,http://localhost/chameleon/cwc2/templates/sample_cwc2_fr.html&CONTEXTS=http://localhost/chameleon/cwc2/contexts/world_context.xml,http://localhost/chameleon/cwc2/contexts/gmap_context.xml&srs=epsg:4326&BBOX=-180,-90,180,90
Cheers
Paul
--
-----------------------------------------------------------------
|Paul Spencer pspencer at dmsolutions.ca |
|-----------------------------------------------------------------|
|Applications & Software Development |
|DM Solutions Group Inc http://www.dmsolutions.ca/|
-----------------------------------------------------------------
More information about the Chameleon
mailing list