Need docs for VALIDATION in layerObj and webObj

[dmorissette]

The VALIDATION block was added to the layerObj and webObj in MS 5.4 but it still lacks documentation.

[dougrenwick]

Important note - UNDOCUMENTED FEATURE

The CGI parameter "id" is treated specially: It must fit the regex IDPATTERN This is regardless of later processing using VALIDATION blocks or validation_pattern METADATA

Reference: mapserv.c line 418

In my opinion, this is very not-nice! But if it must be, it must be documented.

[dougrenwick]

I volunteer to take over this ticket, and am reassigning it to myself.

[sdlime]

I agree on the "needs to be documented" comment. However, the id parameter is a CGI parameter just like map, mode, mapext and so on. They are essentially reserved words and should not be used for runtime substitutions or anything like that.

We certainly could open "id" up to validation against the web validation block, but need a default expression (IDPATTERN) regardless. That's another ticket however.

Thanks for volunteering to document. I'd be glad to help translate the changes I've put in place without you having to go to the code. Perhaps you could start with a trac wiki page and then transition to svn?

Steve

[dougrenwick]

http://mapserver.org/mapfile/index.html
New item: VALIDATION
links to http://mapserver.org/mapfile/layer.html#VALIDATION

http://mapserver.org/mapfile/layer.html
New item: VALIDATION

Signals the start of a VALIDATION object.

As of MapServer 5.4.0, VALIDATION objects are the preferred mechanism for specifying validation patterns for CGI param runtime substitutions.

Link to http://mapserver.org/cgi/runsub.html

http://mapserver.org/mapfile/layer.html
Edit to item METADATA

Add this:

In MapServer versions < 5.4.0 METADATA can also specify validation patterns for CGI param runtime substitutions.

Link to http://mapserver.org/cgi/runsub.html

http://mapserver.org/cgi/runsub.html
New subsection for Table of Contents: 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.

http://mapserver.org/cgi/runsub.html
New subsection for Table of Contents: 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
    # %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

Previous to MapServer 5.4.0 (and still available in 5.4.0) this was done via validation_pattern METADATA in the LAYER definition.

  METADATA
    # %firstname% substitutions can only have letters and hyphens
    firstname_validation_pattern      '^[a-zA-Z\-]+$'

    # %parcelid% must be numeric and between 5 and 8 characters
    parcelid_validation_pattern      '^[0-9]{5,8)$'

    # %taxid% must be two capital letters and six digits
    taxid_validation_pattern      '^[A-Z]{2}[0-9]{6}$'
  END

[dmorissette]

Reassigned to Jeff to review and apply proposed updates to docs

[havatv]

Documentation for cgi-controls, cgi-runsub, mapfile-class, mapfile-layer and mapfile-web added (mostly by copy and paste) in r11991. I did not include the pre 5.4.0 behaviour. I was not able to create an index entry in mapfile.index. I did add general index entries for VALIDATION.

Please reopen and comment if more needs to be done.