Opened 13 years ago

Closed 11 years ago

#2971 closed task (fixed)

Need docs for VALIDATION in layerObj and webObj

Reported by: dmorissette Owned by: jmckenna
Priority: normal Milestone: 5.6 release
Component: Documentation - MapServer Version: unspecified
Severity: normal Keywords:
Cc: sdlime, jmckenna, dougrenwick, havatv

Description

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

Change History (6)

comment:1 by dougrenwick, 13 years ago

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.

comment:2 by dougrenwick, 13 years ago

Cc: jmckenna added
Owner: changed from jmckenna to dougrenwick

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

comment:3 by sdlime, 13 years ago

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

comment:4 by dougrenwick, 13 years ago

Type: defecttask
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

comment:5 by dmorissette, 13 years ago

Cc: dougrenwick added
Owner: changed from dougrenwick to jmckenna

Reassigned to Jeff to review and apply proposed updates to docs

comment:6 by havatv, 11 years ago

Cc: havatv added
Resolution: fixed
Status: newclosed

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.

Note: See TracTickets for help on using tickets.