Introduction

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.

Basic Example

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'
  ...
  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 fot a slight performance hit. Often you would set a default class to draw features that don't match, but that is not required.

Parameters Supported

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 elsewhere (todo- add link). Below is a list of properties that do allow run-time substitution (todo- add MapServer version):

• LAYER: DATA (must validate against DATAPATTERN)
• LAYER: TILEINDEX
• LAYER: CONNECTION
• LAYER: FILTER
• CLASS EXPRESSION