|
|
Home | Docs | Issue Tracker | FAQ | Download |
|
|
| Author: | Steve Lime |
|---|---|
| Contact: | steve.lime at DNR.STATE.MN.US |
| Revision: | $Revision$ |
| Last Updated: | $Date$ |
Table of Contents
Run-time substitution for the MapServer CGI has been around since version 4.0 and it’s use has continued to expand. In short, it allows you to alter portions of a mapfile based on data passed via a CGI request. This functionality is only available via the standard CGI application. Within MapScript this is easy to do since the developer has complete control over how input is handled.
Let’s say you’d like the user to dynamically set a portion of an expression so they could highlight a certain land cover class, and you have a form element (called ctype) that allows them to choose between: forest, water, wetland and developed. You could then set up a layer like so:
LAYER
NAME 'covertypes'
...
VALIDATION
"ctype" "[a-z]+"
END
CLASSITEM 'type'
CLASS # highlighted presentation
EXPRESSION '%ctype%'
...
END
CLASS # default presentation
...
END
END
When a request is processed the value for ctype is substituted for the string %ctype% and the mapfile is processed as normal. If no ctype is passed in the EXPRESSION will never be true so it doesn’t really hurt anything except for a slight performance hit. Often you would set a default class to draw features that don’t match, but that is not required.
Not every mapfile parameter supports run-time substitution and care has been taken to try and support those that make the most sense. Remember, you also can do run-time configuration using the map_object_property type syntax detailed in Changing map file parameters via a form or a URL. Below is a list of properties that do allow run-time substitution (todo- add MapServer version):
CLASS: EXPRESSION
CLASS: TEXT
New in version 6.0.
LAYER: CONNECTION
LAYER: DATA (must validate against DATAPATTERN)
LAYER: FILTER
LAYER: TILEINDEX
OUTPUTFORMAT: FORMATOPTION: FILENAME (must have a MAP VALIDATION pattern)
New in version 6.2.
You can use runtime substitutions to change values within a FILTER as you go. For example your FILTER could be written like so:
FILTER ("multimedia='%multimedia%' and seats >= %nseats% and Sound= '%sound%')
Then (assuming you’re using the CGI interface) you could pass in variables named multimedia, nseats and sound with values defined by the user in an HTML form.
You should also define validation expressions on these variables to guard against unintentional SQL being submitted to postgis. Within the layer you’d do the following:
VALIDATION
'multimedia' '^yes|no$'
'sound' '^yes|no$'
'nseats' '^[0-9]{1,2}$'
END
The validation strings are regular expressions that are applied against the appropriate variable value before being added to the FILTER. The first two limit the value of multimedia and sound to yes or no. The third limits the value for nseats to a 2 digit integer.
The runtime substitution mechanism will usually create syntactically incorrect, and almost always semantically incorrect mapfiles if the substitution parameter was not provided in the calling URL.
Since version 5.6, you can provide a default value for any substitution parameter, that will be applied if the parameter was not found in the url. You do this by providing special entries inside the layer metadata :
METADATA
'default_sound' 'yes'
'default_nseats' '5'
'default_multimedia' 'yes'
END
In this example, the mapfile will be created as if the url contained “&sound=yes&nseats=5&multimedia=yes”
This behavior is also accessible in the shp2img utility, allowing you to test runtime substitution mapfiles without using a webserver.
Because runtime substitution affects potentially sensitive areas of your mapfile such as database columns and filenames, it is mandatory that you use pattern validation (since version 6.0)
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 CLASS, LAYER and WEB.
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
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.