[mapserver-commits] r8148 - trunk/docs/development/rfc
svn at osgeo.org
svn at osgeo.org
Sun Nov 30 16:12:36 EST 2008
Author: hobu
Date: 2008-11-30 16:12:36 -0500 (Sun, 30 Nov 2008)
New Revision: 8148
Modified:
trunk/docs/development/rfc/ms-rfc-32.txt
trunk/docs/development/rfc/ms-rfc-33.txt
trunk/docs/development/rfc/ms-rfc-35.txt
trunk/docs/development/rfc/ms-rfc-36.txt
Log:
styling, break at 80, formatting
Modified: trunk/docs/development/rfc/ms-rfc-32.txt
===================================================================
--- trunk/docs/development/rfc/ms-rfc-32.txt 2008-11-30 21:05:00 UTC (rev 8147)
+++ trunk/docs/development/rfc/ms-rfc-32.txt 2008-11-30 21:12:36 UTC (rev 8148)
@@ -11,24 +11,54 @@
Overview
~~~~~~~~
+Presently MapServer supports GD (www.libgd.org) as its primary raster
+rendering backend. While GD is sufficient in many instances it is not capable
+of high quality output especially with regards to anti-aliased line work.
+MapServer does support pseudo anti-aliased wide lines using variable opacity
+"fuzzy" buffers, but the results are not as good as they could be.
-Presently MapServer supports GD (www.libgd.org) as its primary raster rendering backend. While GD is sufficient in many instances it is not capable of high quality output especially with regards to anti-aliased line work. MapServer does support pseudo anti-aliased wide lines using variable opacity "fuzzy" buffers, but the results are not as good as they could be.
+AGG has emerged as one of the premier software-only rendering solutions and it
+holds the promise of superior output quality with little or no apparent loss
+in performance. In fact, AGG may well be faster than GD in some instances even
+with the higher quality output.
-AGG has emerged as one of the premier software-only rendering solutions and it holds the promise of superior output quality with little or no apparent loss in performance. In fact, AGG may well be faster than GD in some instances even with the higher quality output.
+That said, we are still heavily vested in GD for many things. Text positioning
+and raster rendering in particular use GD functions directly. On the other
+hand, AGG does not have built in functions to read or write popular graphics
+formats such as GIF, JPEG or PNG. It makes sense then to consider a hybrid
+solution wherein we can take advantage of aspects of GD that make sense such
+as buffer management and I/O capabilities, and let AGG worry about rendering
+features. That's exactly what is proposed- AGG rendering into a GD managed
+image buffer. A secondary benefit is that AGG functionality can be added
+incrementally as time and resources permit. For example, since an AGG imageObj
+is really just a gdImagePtr we can use current code that renders to a GD image
+along side any AGG routines.
-That said, we are still heavily vested in GD for many things. Text positioning and raster rendering in particular use GD functions directly. On the other hand, AGG does not have built in functions to read or write popular graphics formats such as GIF, JPEG or PNG. It makes sense then to consider a hybrid solution wherein we can take advantage of aspects of GD that make sense such as buffer management and I/O capabilities, and let AGG worry about rendering features. That's exactly what is proposed- AGG rendering into a GD managed image buffer. A secondary benefit is that AGG functionality can be added incrementally as time and resources permit. For example, since an AGG imageObj is really just a gdImagePtr we can use current code that renders to a GD image along side any AGG routines.
-
Technical Solution
~~~~~~~~~~~~~~~~~~
-The goal of this initial implementation is to be able to render the symbol and style definitions the same way as GD does. That is, the AGG renderer should produce output similar to GD but of a higher quality. No attempts are made at this stage to introduce rendering capabilities specific to AGG unless otherwise noted. As a result no additions to the MapServer symbolObj or styleObj are necessary at this point.
+The goal of this initial implementation is to be able to render the symbol and
+style definitions the same way as GD does. That is, the AGG renderer should
+produce output similar to GD but of a higher quality. No attempts are made at
+this stage to introduce rendering capabilities specific to AGG unless
+otherwise noted. As a result no additions to the MapServer symbolObj or
+styleObj are necessary at this point.
-For the most part, the AGG renderer can ingest processed shapeObj's, styleObj's and symbolObj's just as GD. That said, since AGG uses sub-pixel computations to render features it does not want feature coordinates rounded to integer values, so a special AGG-only map to image coordinate conversion function msTransformShapeAGG. Note, that it may be that GD could also make use of the non-rounded features and could just cast the doubles to ints when passing x's and y's to GD (in fact the code already does this), but further testing will be necessary.
+For the most part, the AGG renderer can ingest processed shapeObj's,
+styleObj's and symbolObj's just as GD. That said, since AGG uses sub-pixel
+computations to render features it does not want feature coordinates rounded
+to integer values, so a special AGG-only map to image coordinate conversion
+function msTransformShapeAGG. Note, that it may be that GD could also make use
+of the non-rounded features and could just cast the doubles to ints when
+passing x's and y's to GD (in fact the code already does this), but further
+testing will be necessary.
C API Changes
~~~~~~~~~~~~~
-In reality adding a new renderer has little or no effect on the MapServer core. The following files are to be modified to add AGG specific processing blocks that are basically straight copies of GD support:
+In reality adding a new renderer has little or no effect on the MapServer
+core. The following files are to be modified to add AGG specific processing
+blocks that are basically straight copies of GD support:
mapdraw.c
mapdrawgdal.c
@@ -41,7 +71,10 @@
No new functionality is added to these files, rather just else-if blocks.
-The bulk of the AGG functionality can be found in a new source file, mapagg.cpp. For better or worse it mimics the rendering API found in mapgd.c. So, for example msDrawLineSymbolGD has a counter part in msDrawLineSymbolAGG. Various helper functions/methods can also be found in that file.
+The bulk of the AGG functionality can be found in a new source file,
+mapagg.cpp. For better or worse it mimics the rendering API found in mapgd.c.
+So, for example msDrawLineSymbolGD has a counter part in msDrawLineSymbolAGG.
+Various helper functions/methods can also be found in that file.
MapScript
~~~~~~~~~
@@ -64,13 +97,26 @@
Issues and Caveats
~~~~~~~~~~~~~~~~~~
-- The AGG driver only supports RGB output at this time. A fundamental difference in how GD and AGG interpret alpha channel values (GD is backwards) means that AGG cannot write to a GD alpha channel and have the output interpreted correctly. This really shouldn't be a deal breaker though since vector rendering in MapServer does not write to the alpha channel except when dealing with layer transparency, otherwise alpha blending occurs. In addition, GD is back under active development and there are plans to define a proper RGBA buffer.
+- The AGG driver only supports RGB output at this time. A fundamental
+ difference in how GD and AGG interpret alpha channel values (GD is
+ backwards) means that AGG cannot write to a GD alpha channel and have the
+ output interpreted correctly. This really shouldn't be a deal breaker though
+ since vector rendering in MapServer does not write to the alpha channel
+ except when dealing with layer transparency, otherwise alpha blending
+ occurs. In addition, GD is back under active development and there are plans
+ to define a proper RGBA buffer.
+
+- Text and raster layers are drawn using GD. While text placement could
+ certainly benefit from sub-pixel placement there are not enough resources to
+ complete that support at this time. Hopefully it can be addressed soon.
+ Raster layer rendering doesn't appear to benefit from AGG and will remain a
+ GD function at this time.
-- Text and raster layers are drawn using GD. While text placement could certainly benefit from sub-pixel placement there are not enough resources to complete that support at this time. Hopefully it can be addressed soon. Raster layer rendering doesn't appear to benefit from AGG and will remain a GD function at this time.
-
- The following symbol, style combinations do not work under AGG: TODO
-- The AGG license was changed between versions 2.4 (BSD style) and 2.5 (GPL) (http://www.antigrain.com/license/index.html). MapServer should use version 2.4 of the library until all implications of this change are clarified.
+- The AGG license was changed between versions 2.4 (BSD style) and 2.5 (GPL)
+ (http://www.antigrain.com/license/index.html). MapServer should use version
+ 2.4 of the library until all implications of this change are clarified.
Bug ID
~~~~~~
@@ -81,4 +127,3 @@
~~~~~~~~~~~~~~
None
-
\ No newline at end of file
Modified: trunk/docs/development/rfc/ms-rfc-33.txt
===================================================================
--- trunk/docs/development/rfc/ms-rfc-33.txt 2008-11-30 21:05:00 UTC (rev 8147)
+++ trunk/docs/development/rfc/ms-rfc-33.txt 2008-11-30 21:12:36 UTC (rev 8148)
@@ -14,20 +14,42 @@
Overview
~~~~~~~~
-The function msLayerWhichItems() is a function in maplayer.c that determines exactly which feature attributes need to be retrieved from a given data source. All item-based properties (e.g. CLASSITEM, bound properties, EXPRESSIONs, etc...) are checked and a master list (an array) is compiled. At the same time index references are made (e.g. classitemindex, labelitemindex, etc...). The item indexes are used instead of names to access attribute values at runtime.
+The function msLayerWhichItems() is a function in maplayer.c that determines
+exactly which feature attributes need to be retrieved from a given data
+source. All item-based properties (e.g. CLASSITEM, bound properties,
+EXPRESSIONs, etc...) are checked and a master list (an array) is compiled. At
+the same time index references are made (e.g. classitemindex, labelitemindex,
+etc...). The item indexes are used instead of names to access attribute values
+at runtime.
-The problem with this method is that a feature (a shapeObj) used for drawing or the first pass of a query is not the same as that used for presentation (the second pass of a query). The second pass of a query uses msLayerGetShape() which by default requests all attributes of a feature since we don't know ahead of time which attributes might be output.
+The problem with this method is that a feature (a shapeObj) used for drawing
+or the first pass of a query is not the same as that used for presentation
+(the second pass of a query). The second pass of a query uses
+msLayerGetShape() which by default requests all attributes of a feature since
+we don't know ahead of time which attributes might be output.
-By removing msLayerWhichItems() and always retrieving all attributes a feature is a feature whether drawing, querying or outputing via a template so caching features now becomes practical.
+By removing msLayerWhichItems() and always retrieving all attributes a feature
+is a feature whether drawing, querying or outputing via a template so caching
+features now becomes practical.
Technical Solution
~~~~~~~~~~~~~~~~~~
-As mentioned earlier msLayerWhichItems() does a couple of things. Some of these functions would need to be retained somehow and are described below.
+As mentioned earlier msLayerWhichItems() does a couple of things. Some of
+these functions would need to be retained somehow and are described below.
-1) Layer items array: this array normally would be populated by the msLayerWhichItems() call. Instead it should be populated as a layer is opened in msLayerOpen. (makes sense?)
+1) Layer items array: this array normally would be populated by the
+ msLayerWhichItems() call. Instead it should be populated as a layer is opened
+ in msLayerOpen. (makes sense?)
-2) Index references: linking a attribute name to an index value would have to happen during the course of rendering or querying instead of ahead of time. Basically code that uses attributes would have to first check if the parameter is not NULL, and then if the index reference is not set it would have to call a function like that shown below. While this affects a good number of places in the code base the change is relatively minor. The use of attribute binding isolates much of this code so this change is smaller for version 5.0 that it otherwise would have been.
+2) Index references: linking a attribute name to an index value would have to
+ happen during the course of rendering or querying instead of ahead of time.
+ Basically code that uses attributes would have to first check if the parameter
+ is not NULL, and then if the index reference is not set it would have to call
+ a function like that shown below. While this affects a good number of places
+ in the code base the change is relatively minor. The use of attribute binding
+ isolates much of this code so this change is smaller for version 5.0 that it
+ otherwise would have been.
::
@@ -41,22 +63,38 @@
return -1; /* failure */
}
+
+3) Logical expression handling: expressions maintain their own individual list
+ of items to process so like 2 above this list would have to be created during
+ processing. The code to do this exists as part of msLayerWhichItems() and
+ would be retained under some other name.
-3) Logical expression handling: expressions maintain their own individual list of items to process so like 2 above this list would have to be created during processing. The code to do this exists as part of msLayerWhichItems() and would be retained under some other name.
+.. note::
-Note that this RFC does not address single pass queries, but rather sets the stage for them. Subsequent drawing, query and template output processes would remain unaltered.
+ this RFC does not address single pass queries, but rather sets the
+ stage for them. Subsequent drawing, query and template output processes would
+ remain unaltered.
General C API Changes
~~~~~~~~~~~~~~~~~~~~~
-maplayer.c - msLayerWhichItems() goes away. msLayerOpen() now sets the layer->items array.
-maputil.c - Binding functions now must assign index references when executed. Same goes for the functions to assign a classObj to a feature.
-mapdraw.c - Layeritemindex and classitemindex must now be dynamically assigned values.
+maplayer.c - msLayerWhichItems() goes away. msLayerOpen() now sets the
+layer->items array.
+maputil.c - Binding functions now must assign index references when executed.
+Same goes for the functions to assign a classObj to a feature.
+
+mapdraw.c - Layeritemindex and classitemindex must now be dynamically assigned
+values.
+
Input Driver Changes
~~~~~~~~~~~~~~~~~~~~
-It is unclear how each driver made use of the output of msLayerWhichItems(). It may be as easy as calling msLayerGetItems() instead of using msLayerGetItemInfo() in msLayerOpen() in which case we'd loose the msLayerGetItemInfo() function for each driver too (and the main wrapper function). TODO...
+It is unclear how each driver made use of the output of msLayerWhichItems().
+It may be as easy as calling msLayerGetItems() instead of using
+msLayerGetItemInfo() in msLayerOpen() in which case we'd loose the
+msLayerGetItemInfo() function for each driver too (and the main wrapper
+function). TODO...
mapshape.c -
mapsde.c -
Modified: trunk/docs/development/rfc/ms-rfc-35.txt
===================================================================
--- trunk/docs/development/rfc/ms-rfc-35.txt 2008-11-30 21:05:00 UTC (rev 8147)
+++ trunk/docs/development/rfc/ms-rfc-35.txt 2008-11-30 21:12:36 UTC (rev 8148)
@@ -13,30 +13,60 @@
Overview
--------
-This RFC introduces a mechanism to tell mapserver to enforce OGC standards compliance, or alternatively to be permissive. MapServer should continue to implement the standards as closely as possible, but it has been found that in some cases strict compliance reduces interoperability instead of increasing it.
+This RFC introduces a mechanism to tell mapserver to enforce OGC standards
+compliance, or alternatively to be permissive. MapServer should continue to
+implement the standards as closely as possible, but it has been found that in
+some cases strict compliance reduces interoperability instead of increasing
+it.
-One example of this is the the requirement for the STYLES parameter in WMS GetMap requests which has been enforced in MapServer 5.0.0. Enforcing this requirement effectively prevented a number of WMS client implementations from connecting to MapServer because they did not include the required STYLES parameter in their GetMap request. This RFC also details short term adjustments to handling of the STYLE= required parameter in MapServer 5.
+One example of this is the the requirement for the STYLES parameter in WMS
+GetMap requests which has been enforced in MapServer 5.0.0. Enforcing this
+requirement effectively prevented a number of WMS client implementations from
+connecting to MapServer because they did not include the required STYLES
+parameter in their GetMap request. This RFC also details short term
+adjustments to handling of the STYLE= required parameter in MapServer 5.
OWS_COMPLIANCE METADATA
-----------------------
-This will be achived by introducing a new MAP level metadata item named "ows_compliance" with the possible values "pedantic" and "permissive", with the default being "permissive" if not specified. Variations for specific protocols will also be supported in the usual fashion for OWS metadata (ie. wms_compliance, wfs_compliance, wcs_compliance, sos_compliance).
+This will be achived by introducing a new MAP level metadata item named
+"ows_compliance" with the possible values "pedantic" and "permissive", with
+the default being "permissive" if not specified. Variations for specific
+protocols will also be supported in the usual fashion for OWS metadata (ie.
+wms_compliance, wfs_compliance, wcs_compliance, sos_compliance).
-If this keyword value is "permissive", then when practical and unambiguous MapServer may attempt to be forgiving of missing or otherwise non-compliant requests and input in the interest of increasing MapServer's usability in real life interoperability scenarios.
-This may include things such as allowing protocol parameters to be omitted in requests that are required by the OGC specifications, allowing services to operate even if metadata is missing from the mapfile to fill required fields in capabilities.
+If this keyword value is "permissive", then when practical and unambiguous
+MapServer may attempt to be forgiving of missing or otherwise non-compliant
+requests and input in the interest of increasing MapServer's usability in real
+life interoperability scenarios. This may include things such as allowing
+protocol parameters to be omitted in requests that are required by the OGC
+specifications, allowing services to operate even if metadata is missing from
+the mapfile to fill required fields in capabilities.
-If this keyword value is "pedantic", then to the extent practical MapServer will attempt to generate an error if it's input (WxS protocol requests, mapfile incomplete, etc) is not in full compliance with the requirements of the OGC specifications.
+If this keyword value is "pedantic", then to the extent practical MapServer
+will attempt to generate an error if it's input (WxS protocol requests,
+mapfile incomplete, etc) is not in full compliance with the requirements of
+the OGC specifications.
-It is foreseen that users wishing to encourage good standards compliance behavior in clients, and to ensure they don't accidentally put up web services with incomplete metadata will use the "pedantic" mode. It is anticipated that "pedantic" mode will also be used when MapServer is run through OGC CITE and similar test suites.
+It is foreseen that users wishing to encourage good standards compliance
+behavior in clients, and to ensure they don't accidentally put up web services
+with incomplete metadata will use the "pedantic" mode. It is anticipated that
+"pedantic" mode will also be used when MapServer is run through OGC CITE and
+similar test suites.
-It is foreseen that "permissive" mode will be used by those wishing to ensure their service is accessable by the broadest set of possible clients, even if they are not strictly operating to the standards.
+It is foreseen that "permissive" mode will be used by those wishing to ensure
+their service is accessable by the broadest set of possible clients, even if
+they are not strictly operating to the standards.
-Developers should keep in mind that adding more exceptions in the permissive mode should not be taken lightly as this encourages misuse of the specs and bloats the code with unnecessary exceptions.
+Developers should keep in mind that adding more exceptions in the permissive
+mode should not be taken lightly as this encourages misuse of the specs and
+bloats the code with unnecessary exceptions.
msOWSLookupMetadata()
---------------------
-In actual code, the compliance keyword might be tested using msOWSLookupMetadata() in a manner similar to this:
+In actual code, the compliance keyword might be tested using
+msOWSLookupMetadata() in a manner similar to this:
::
@@ -55,41 +85,59 @@
MapServer 5.0.1
---------------
-For MapServer 5.0.1 the only change anticipated to be made in the code is the above example, requiring the STYLES parameter only in pedantic mode.
+For MapServer 5.0.1 the only change anticipated to be made in the code is the
+above example, requiring the STYLES parameter only in pedantic mode.
-If other standards enforcement issues are discovered to be unnecessarily interfering with use of MapServer in real life interoperability they may also be changed in 5.0.x to be based off this keyword.
+If other standards enforcement issues are discovered to be unnecessarily
+interfering with use of MapServer in real life interoperability they may also
+be changed in 5.0.x to be based off this keyword.
MapServer 5.1
-------------
-In MapServer 5.1, and the future, if other standards enforcement issues are discovered to be unnecessarily interfering with use of MapServer in real life interoperability scenarios they may also be changed to be based off this keyword.
+In MapServer 5.1, and the future, if other standards enforcement issues are
+discovered to be unnecessarily interfering with use of MapServer in real life
+interoperability scenarios they may also be changed to be based off this
+keyword.
-Once again, developers should keep in mind that adding more exceptions in the permissive mode should not be taken lightly as this encourages misuse of the specs and bloats the code with unnecessary exceptions.
+Once again, developers should keep in mind that adding more exceptions in the
+permissive mode should not be taken lightly as this encourages misuse of the
+specs and bloats the code with unnecessary exceptions.
-As part of implementation of this RFC the authors will review all "WARNING:" entries emitted in capabilities documents in places like mapwms.c to see if they ought to be turned into fatal errors when operating in "pedantic" mode.
+As part of implementation of this RFC the authors will review all "WARNING:"
+entries emitted in capabilities documents in places like mapwms.c to see if
+they ought to be turned into fatal errors when operating in "pedantic" mode.
Documentation
-------------
-The ows_compliance keyword will be added to the MapServer 5 reference documentation.
+The ows_compliance keyword will be added to the MapServer 5 reference
+documentation.
Implementation
--------------
-The described changes will be made in MapServer 5.0 and MapServer 5.1 by Frank Warmerdam and/or Daniel Morissette with the MapServer 5.0 changes in time for a 5.0.1 release. It is hoped that all OWS service developers will apply the permissive/pedantic tests in OWS services in the future as required and as issues come up.
+The described changes will be made in MapServer 5.0 and MapServer 5.1 by Frank
+Warmerdam and/or Daniel Morissette with the MapServer 5.0 changes in time for
+a 5.0.1 release. It is hoped that all OWS service developers will apply the
+permissive/pedantic tests in OWS services in the future as required and as
+issues come up.
MapScript
---------
-No changes are anticipated in mapscript as it already has metadata setting methods.
+No changes are anticipated in mapscript as it already has metadata setting
+methods.
Backwards Compatibility Issues
------------------------------
-Implementation of this feature should restore backward compatible default behavior in MapServer 5 with MapServer 4.x. No other compatability issues are anticipated.
+Implementation of this feature should restore backward compatible default
+behavior in MapServer 5 with MapServer 4.x. No other compatability issues are
+anticipated.
Bug ID
------
@@ -99,4 +147,7 @@
Voting History
--------------
-There was a first vote around 2007/11/08 which was veto'd... and after further discussion the RFC has been withdrawn in favor of simply restoring the behavior of MapServer 4.10 with respect to the STYLES= parameter (i.e. make it optional again). See ticket #2427 about this.
+There was a first vote around 2007/11/08 which was veto'd... and after further
+discussion the RFC has been withdrawn in favor of simply restoring the
+behavior of MapServer 4.10 with respect to the STYLES= parameter (i.e. make it
+optional again). See ticket #2427 about this.
Modified: trunk/docs/development/rfc/ms-rfc-36.txt
===================================================================
--- trunk/docs/development/rfc/ms-rfc-36.txt 2008-11-30 21:05:00 UTC (rev 8147)
+++ trunk/docs/development/rfc/ms-rfc-36.txt 2008-11-30 21:12:36 UTC (rev 8148)
@@ -15,13 +15,17 @@
Problem:
-1) Currently a driver like GML isn't available to the CGI as a means of presenting query results
+1) Currently a driver like GML isn't available to the CGI as a means of
+ presenting query results
-2) The templating scheme (HEADER/TEMPLATE/FOOTER) for queries isn't user friendly nor is it ammenable to multple presentation formats. That is, one layer => one template set
+2) The templating scheme (HEADER/TEMPLATE/FOOTER) for queries isn't user
+ friendly nor is it ammenable to multple presentation formats. That is, one
+ layer => one template set
Solution:
-1) Use output format objects to define formats that can be used to output query results in addition to drawing images. For example:
+1) Use output format objects to define formats that can be used to output
+ query results in addition to drawing images. For example:
::
@@ -31,13 +35,24 @@
MIMETYPE 'text/xml; subtype=gml/3.2.1'
END
-Might need to extend that object to discriminate between map rendering and query formatters but that can happen in mapdraw.c and mapserv.c too. That is, drivers are explicitly referenced in those places so if someone tries to draw a map with a GML3 driver it would throw an error.
+Might need to extend that object to discriminate between map rendering and
+query formatters but that can happen in mapdraw.c and mapserv.c too. That is,
+drivers are explicitly referenced in those places so if someone tries to draw
+a map with a GML3 driver it would throw an error.
-2) Use the webObj QUERYFORMAT property to reference formats: 'QUERYFORMAT gml3'. Right now that property carries a mime-type but it could be used to reference a format too.
+2) Use the webObj QUERYFORMAT property to reference formats:
+ 'QUERYFORMAT gml3'. Right now that property carries a mime-type but it
+ could be used to reference a format too.
-3) Also allow applicable modes (i.e. WFS, WMS, SOS), to utilize DRIVER/TEMPLATE type formats (i.e. advertise in GetCapabilities responses, support through API [e.g. request=GetFeature&outputFormat=text/xml; subtype=gml/3.2.1]), mapped from OUTPUTFORMAT/MIMETYPE. Presently the WCS driver requires the developer to explicitly define supported output formats, other services could do the same and could reference templated output.
+3) Also allow applicable modes (i.e. WFS, WMS, SOS), to utilize
+ DRIVER/TEMPLATE type formats (i.e. advertise in GetCapabilities responses,
+ support through API [e.g. request=GetFeature&outputFormat=text/xml;
+ subtype=gml/3.2.1]), mapped from OUTPUTFORMAT/MIMETYPE. Presently the WCS
+ driver requires the developer to explicitly define supported output formats,
+ other services could do the same and could reference templated output.
-4) Define a TEMPLATE driver. Basically this would just invoke the normal query templating scheme. For example:
+4) Define a TEMPLATE driver. Basically this would just invoke the normal query
+ templating scheme. For example:
::
@@ -55,7 +70,11 @@
TEMPLATE 'myTemplate.js'
END
-5) Note that in the above examples we reference a file, so I'm thinking of supporting a single template system for queries in addition to the current mechanism. To do this I'd propose 4 new template tags: [resultset], [feature], [join] (for one-to-many joins), and [include] (to support code sharing between templates). All but the include tag would be blocks. An example might be:
+5) Note that in the above examples we reference a file, so I'm thinking of
+ supporting a single template system for queries in addition to the current
+ mechanism. To do this I'd propose 4 new template tags: [resultset], [feature],
+ [join] (for one-to-many joins), and [include] (to support code sharing between
+ templates). All but the include tag would be blocks. An example might be:
::
@@ -145,46 +164,90 @@
}
[/resultset]
-This would allow for relatively complex text files of any sort to be built from multiple layers. All the normal template tags would still be supported but those normally available for query results would only be valid inside a [feature]...[/feature]. These tags would work with existing system too but just wouldn't be as useful as with the 1 template idea.
+This would allow for relatively complex text files of any sort to be built
+from multiple layers. All the normal template tags would still be supported
+but those normally available for query results would only be valid inside a
+[feature]...[/feature]. These tags would work with existing system too but
+just wouldn't be as useful as with the 1 template idea.
-Note 1: that it is often a problem to have trailing record separator characters after the final record. For example, in the JSON template above the trailing comma in the [feature] block causes problems with Internet Explorer. So I propose supporting a "trim" attribute that tells the template processor to remove that string from the end of the output for the last feature processed.
+.. note::
+ It is often a problem to have trailing record separator
+ characters after the final record. For example, in the JSON template above the
+ trailing comma in the [feature] block causes problems with Internet Explorer.
+ So I propose supporting a "trim" attribute that tells the template processor
+ to remove that string from the end of the output for the last feature
+ processed.
-Note 2: a resultset could be applied to multiple layers so the name attribute will take a comma delimited list of layers. The order listed is the order they results will be presented. It's possible that groups could be used as well but at this point that seems like a fairly rare use case.
+.. note::
+ A resultset could be applied to multiple layers so the name attribute
+ will take a comma delimited list of layers. The order listed is the order they
+ results will be presented. It's possible that groups could be used as well but
+ at this point that seems like a fairly rare use case.
-Note 3: a resultset will also take a maxresults attribute so that the number of features processed can be limited.
+.. note::
+ A resultset will also take a maxresults attribute so that the number
+ of features processed can be limited.
+
Additional Mapfile Changes
--------------------------
-By moving templates out of a layer we lose the ability mark layers as queryable. Dan proposed adding a QUERYABLE TRUE/FALSE option to layerObj's. That could be put in place as part of this RFC, although it is not required. We could continue to leverage dummy template values. Adding it would require the normal changes to support a new keyword, and a small change to function in mapquery.c that tests to see if a layer is queryable. Basically a layer would be queryable if: 1) it has a template or 2) QUERYABLE is TRUE (default would be FALSE).
+By moving templates out of a layer we lose the ability mark layers as
+queryable. Dan proposed adding a QUERYABLE TRUE/FALSE option to layerObj's.
+That could be put in place as part of this RFC, although it is not required.
+We could continue to leverage dummy template values. Adding it would require
+the normal changes to support a new keyword, and a small change to function in
+mapquery.c that tests to see if a layer is queryable. Basically a layer would
+be queryable if: 1) it has a template or 2) QUERYABLE is TRUE (default would
+be FALSE).
Documentation
-------------
-Documentation detailing the new templated output capabilities will be added to the mapfile reference guide (OUTPUTFORMAT and WEB objects) and to the template reference guide (new [resultset], [feature], [join] and [include] tags).
+Documentation detailing the new templated output capabilities will be added to
+the mapfile reference guide (OUTPUTFORMAT and WEB objects) and to the template
+reference guide (new [resultset], [feature], [join] and [include] tags).
Implementation
--------------
-mapoutput.c: No changes necessary (I think), no need to define a default format, nor do I think we need to extend the outputFormatObj structure.
+mapoutput.c: No changes necessary (I think), no need to define a default
+format, nor do I think we need to extend the outputFormatObj structure.
-mapfile.c/maplexer.l: Allow changing webObj QUERYFORMAT from a URL. (todo: add support for setting a layer as queryable)
+mapfile.c/maplexer.l: Allow changing webObj QUERYFORMAT from a URL. (todo: add
+support for setting a layer as queryable)
-maptemplate.c: Add processor functions for the new tags. Update process line to recognize the [resultset] and [join] tags (the [feature] tag would only be valid within a [resultset] block. Write a new single template processing function similar to msReturnQuery() in that same source file, something like msReturnSingleTemplateQuery().
+maptemplate.c: Add processor functions for the new tags. Update process line
+to recognize the [resultset] and [join] tags (the [feature] tag would only be
+valid within a [resultset] block. Write a new single template processing
+function similar to msReturnQuery() in that same source file, something like
+msReturnSingleTemplateQuery().
-mapserv.c: Add code at the end of the query processing switch statement to look at the value of web->queryformat. If it references an existing output format by name then use the file the format points to with msReturnSingleTemplateQuery(), otherwise process as currently done.
+mapserv.c: Add code at the end of the query processing switch statement to
+look at the value of web->queryformat. If it references an existing output
+format by name then use the file the format points to with
+msReturnSingleTemplateQuery(), otherwise process as currently done.
-Caveats: to simplify tag parsing (at least initially) I propose requiring that start and end tags exist on their own lines in the template file (is this a requirement for legend templates?). Depending on the legend template block parsing this requirement could be removed once some implementation work is done.
+Caveats: to simplify tag parsing (at least initially) I propose requiring that
+start and end tags exist on their own lines in the template file (is this a
+requirement for legend templates?). Depending on the legend template block
+parsing this requirement could be removed once some implementation work is
+done.
MapScript
---------
-No changes are anticipated in mapscript at this time although we may choose to expose templated output as an option at a later date.
+No changes are anticipated in MapScript at this time although we may choose to
+expose templated output as an option at a later date.
Backwards Compatibility Issues
------------------------------
-No other compatibility issues are anticipated. The current templating mechanism would continue to function. In the event the QUERYFORMAT does not reference an outputFormatObj the current system would kick in. In fact, the current system can use several of the new proposed tags, specifically [join] and [include] tags.
+No other compatibility issues are anticipated. The current templating
+mechanism would continue to function. In the event the QUERYFORMAT does not
+reference an outputFormatObj the current system would kick in. In fact, the
+current system can use several of the new proposed tags, specifically [join]
+and [include] tags.
Bug ID
------
@@ -194,4 +257,4 @@
Voting History
--------------
-None
\ No newline at end of file
+None
More information about the mapserver-commits
mailing list