[mapserver-commits] r11991 - branches/branch-6-0/docs/en/cgi branches/branch-6-0/docs/en/mapfile trunk/docs/en/cgi trunk/docs/en/mapfile

svn at osgeo.org svn at osgeo.org
Thu Aug 4 08:04:43 EDT 2011 

Author: havatv
Date: 2011-08-04 05:04:43 -0700 (Thu, 04 Aug 2011)
New Revision: 11991

Modified:
   branches/branch-6-0/docs/en/cgi/controls.txt
   branches/branch-6-0/docs/en/cgi/runsub.txt
   branches/branch-6-0/docs/en/mapfile/class.txt
   branches/branch-6-0/docs/en/mapfile/layer.txt
   branches/branch-6-0/docs/en/mapfile/web.txt
   trunk/docs/en/cgi/controls.txt
   trunk/docs/en/cgi/runsub.txt
   trunk/docs/en/mapfile/class.txt
   trunk/docs/en/mapfile/layer.txt
   trunk/docs/en/mapfile/web.txt
Log:
Added documentation for VALIDATION (#2971 and #3754) - cgi-runsub, cgi-controls, mapfile-layer, mapfile-class, mapfile-web

Modified: branches/branch-6-0/docs/en/cgi/controls.txt
===================================================================
--- branches/branch-6-0/docs/en/cgi/controls.txt	2011-08-04 10:04:31 UTC (rev 11990)
+++ branches/branch-6-0/docs/en/cgi/controls.txt	2011-08-04 12:04:43 UTC (rev 11991)
@@ -267,7 +267,8 @@
 value from a form or a URL. The syntax for this is fairly straight forward,
 and depends on what version of MapServer you are using. One potentially very 
 powerful use of this ability to change mapfile parameters through a URL 
-involves changing class expressions on-the-fly.  Try it out.
+involves changing class expressions on-the-fly.  `VALIDATION` can be used to
+control run-time substition (see :ref:`RUNSUB`).  Try it out.
 
 
 Using MapServer version >= 5

Modified: branches/branch-6-0/docs/en/cgi/runsub.txt
===================================================================
--- branches/branch-6-0/docs/en/cgi/runsub.txt	2011-08-04 10:04:31 UTC (rev 11990)
+++ branches/branch-6-0/docs/en/cgi/runsub.txt	2011-08-04 12:04:43 UTC (rev 11991)
@@ -67,7 +67,7 @@
 * LAYER: TILEINDEX 
 * LAYER: CONNECTION
 * LAYER: FILTER
-* CLASS EXPRESSION
+* CLASS: EXPRESSION
 
 FILTERs
 ..............................................................................
@@ -124,5 +124,47 @@
 This behavior is also accessible in the shp2img utility, allowing you to test 
 runtime substitution mapfiles without using a webserver.
 
+.. index::
+   single: VALIDATION
 
+VALIDATION
+-----------------------------------------------------------------------------
 
+Because runtime substitution affects potentially sensitive areas of
+your mapfile such as database columns and filenames, it is *STRONGLY*
+recommended that you use pattern validation.
+
+Pattern validation uses regular expressions, which are strings that
+describe how to compare strings to patterns. The exact functionality
+of your systems' regular expressions may vary, but you can find a lot
+of general information by a Google search for "regular expression
+tutorial".
+
+As of MapServer 5.4.0 the preferred mechanism is a `VALIDATION` block in
+the `LAYER` definition. This is only slightly different than the older
+`METADATA` mechanism.  `VALIDATION` blocks can be with :ref:`CLASS`,
+:ref:`LAYER` and :ref:`WEB`.
+
+.. code-block:: mapfile
+
+    VALIDATION
+      # %firstname% substitutions can only have letters and hyphens
+      firstname     '^[a-zA-Z\-]+$'
+
+      # %parcelid% must be numeric and between 5 and 8 characters
+      parcelid      '^[0-9]{5,8)$'
+
+      # %taxid% must be two capital letters and six digits
+      taxid         '^[A-Z]{2}[0-9]{6}$'
+    END
+
+Magic values
+-----------------------------------------------------------------------------
+
+Some runtime substitutions have special caveats.
+
+* ID
+
+  In addition to any defined `METADATA` or `VALIDATION`, the 'id'
+  parameter will be subjected to a special check. It must be
+  alphanumeric and cannot be longer than 63 characters.

Modified: branches/branch-6-0/docs/en/mapfile/class.txt
===================================================================
--- branches/branch-6-0/docs/en/mapfile/class.txt	2011-08-04 10:04:31 UTC (rev 11990)
+++ branches/branch-6-0/docs/en/mapfile/class.txt	2011-08-04 12:04:43 UTC (rev 11991)
@@ -238,3 +238,13 @@
 - OVERLAYMINSIZE
 - OVERLAYMAXSIZE
 - OVERLAYSYMBOL
+
+.. index::
+   pair: VALIDATION; CLASS
+
+VALIDATION
+    Signals the start of a `VALIDATION` block.
+
+    As of MapServer 5.4.0, `VALIDATION` blocks are the preferred
+    mechanism for specifying validation patterns for CGI param runtime
+    substitutions.  See :ref:`RUNSUB`.

Modified: branches/branch-6-0/docs/en/mapfile/layer.txt
===================================================================
--- branches/branch-6-0/docs/en/mapfile/layer.txt	2011-08-04 10:04:31 UTC (rev 11990)
+++ branches/branch-6-0/docs/en/mapfile/layer.txt	2011-08-04 12:04:43 UTC (rev 11991)
@@ -678,3 +678,13 @@
 UNITS [feet|inches|kilometers|meters|miles|nauticalmiles|dd|pixels|percentages]
     Units of the layer. `Percentages` was added in MapServer 4.10 and is mostly
     geared for inline features. `Nauticalmiles` was added in MapServer 5.6.
+
+.. index::
+   pair: VALIDATION; LAYER
+
+VALIDATION
+    Signals the start of a `VALIDATION` block.
+
+    As of MapServer 5.4.0, `VALIDATION` blocks are the preferred
+    mechanism for specifying validation patterns for CGI param runtime
+    substitutions.  See :ref:`RUNSUB`.

Modified: branches/branch-6-0/docs/en/mapfile/web.txt
===================================================================
--- branches/branch-6-0/docs/en/mapfile/web.txt	2011-08-04 10:04:31 UTC (rev 11990)
+++ branches/branch-6-0/docs/en/mapfile/web.txt	2011-08-04 12:04:43 UTC (rev 11991)
@@ -140,3 +140,13 @@
 TEMPLATE [filename|url]
     Template file or URL to use in presenting the results to the user in an 
     interactive mode (i.e. map generates map and so on ... )
+
+.. index::
+   pair: VALIDATION; WEB
+
+VALIDATION
+    Signals the start of a `VALIDATION` block.
+
+    As of MapServer 5.4.0, `VALIDATION` blocks are the preferred
+    mechanism for specifying validation patterns for CGI param runtime
+    substitutions.  See :ref:`RUNSUB`.

Modified: trunk/docs/en/cgi/controls.txt
===================================================================
--- trunk/docs/en/cgi/controls.txt	2011-08-04 10:04:31 UTC (rev 11990)
+++ trunk/docs/en/cgi/controls.txt	2011-08-04 12:04:43 UTC (rev 11991)
@@ -267,7 +267,8 @@
 value from a form or a URL. The syntax for this is fairly straight forward,
 and depends on what version of MapServer you are using. One potentially very 
 powerful use of this ability to change mapfile parameters through a URL 
-involves changing class expressions on-the-fly.  Try it out.
+involves changing class expressions on-the-fly.  `VALIDATION` can be used to
+control run-time substition (see :ref:`RUNSUB`).  Try it out.
 
 
 Using MapServer version >= 5

Modified: trunk/docs/en/cgi/runsub.txt
===================================================================
--- trunk/docs/en/cgi/runsub.txt	2011-08-04 10:04:31 UTC (rev 11990)
+++ trunk/docs/en/cgi/runsub.txt	2011-08-04 12:04:43 UTC (rev 11991)
@@ -67,7 +67,7 @@
 * LAYER: TILEINDEX 
 * LAYER: CONNECTION
 * LAYER: FILTER
-* CLASS EXPRESSION
+* CLASS: EXPRESSION
 
 FILTERs
 ..............................................................................
@@ -124,5 +124,47 @@
 This behavior is also accessible in the shp2img utility, allowing you to test 
 runtime substitution mapfiles without using a webserver.
 
+.. index::
+   single: VALIDATION
 
+VALIDATION
+-----------------------------------------------------------------------------
 
+Because runtime substitution affects potentially sensitive areas of
+your mapfile such as database columns and filenames, it is *STRONGLY*
+recommended that you use pattern validation.
+
+Pattern validation uses regular expressions, which are strings that
+describe how to compare strings to patterns. The exact functionality
+of your systems' regular expressions may vary, but you can find a lot
+of general information by a Google search for "regular expression
+tutorial".
+
+As of MapServer 5.4.0 the preferred mechanism is a `VALIDATION` block in
+the `LAYER` definition. This is only slightly different than the older
+`METADATA` mechanism.  `VALIDATION` blocks can be with :ref:`CLASS`,
+:ref:`LAYER` and :ref:`WEB`.
+
+.. code-block:: mapfile
+
+    VALIDATION
+      # %firstname% substitutions can only have letters and hyphens
+      firstname     '^[a-zA-Z\-]+$'
+
+      # %parcelid% must be numeric and between 5 and 8 characters
+      parcelid      '^[0-9]{5,8)$'
+
+      # %taxid% must be two capital letters and six digits
+      taxid         '^[A-Z]{2}[0-9]{6}$'
+    END
+
+Magic values
+-----------------------------------------------------------------------------
+
+Some runtime substitutions have special caveats.
+
+* ID
+
+  In addition to any defined `METADATA` or `VALIDATION`, the 'id'
+  parameter will be subjected to a special check. It must be
+  alphanumeric and cannot be longer than 63 characters.

Modified: trunk/docs/en/mapfile/class.txt
===================================================================
--- trunk/docs/en/mapfile/class.txt	2011-08-04 10:04:31 UTC (rev 11990)
+++ trunk/docs/en/mapfile/class.txt	2011-08-04 12:04:43 UTC (rev 11991)
@@ -238,3 +238,13 @@
 - OVERLAYMINSIZE
 - OVERLAYMAXSIZE
 - OVERLAYSYMBOL
+
+.. index::
+   pair: VALIDATION; CLASS
+
+VALIDATION
+    Signals the start of a `VALIDATION` block.
+
+    As of MapServer 5.4.0, `VALIDATION` blocks are the preferred
+    mechanism for specifying validation patterns for CGI param runtime
+    substitutions.  See :ref:`RUNSUB`.

Modified: trunk/docs/en/mapfile/layer.txt
===================================================================
--- trunk/docs/en/mapfile/layer.txt	2011-08-04 10:04:31 UTC (rev 11990)
+++ trunk/docs/en/mapfile/layer.txt	2011-08-04 12:04:43 UTC (rev 11991)
@@ -678,3 +678,13 @@
 UNITS [feet|inches|kilometers|meters|miles|nauticalmiles|dd|pixels|percentages]
     Units of the layer. `Percentages` was added in MapServer 4.10 and is mostly
     geared for inline features. `Nauticalmiles` was added in MapServer 5.6.
+
+.. index::
+   pair: VALIDATION; LAYER
+
+VALIDATION
+    Signals the start of a `VALIDATION` block.
+
+    As of MapServer 5.4.0, `VALIDATION` blocks are the preferred
+    mechanism for specifying validation patterns for CGI param runtime
+    substitutions.  See :ref:`RUNSUB`.

Modified: trunk/docs/en/mapfile/web.txt
===================================================================
--- trunk/docs/en/mapfile/web.txt	2011-08-04 10:04:31 UTC (rev 11990)
+++ trunk/docs/en/mapfile/web.txt	2011-08-04 12:04:43 UTC (rev 11991)
@@ -140,3 +140,13 @@
 TEMPLATE [filename|url]
     Template file or URL to use in presenting the results to the user in an 
     interactive mode (i.e. map generates map and so on ... )
+
+.. index::
+   pair: VALIDATION; WEB
+
+VALIDATION
+    Signals the start of a `VALIDATION` block.
+
+    As of MapServer 5.4.0, `VALIDATION` blocks are the preferred
+    mechanism for specifying validation patterns for CGI param runtime
+    substitutions.  See :ref:`RUNSUB`.

More information about the mapserver-commits mailing list