.. _runsub:

*****************************************************************************
 Run-time Substitution
*****************************************************************************

:Author:        Steve Lime
:Contact:       steve.lime at DNR.STATE.MN.US
:Revision: $Revision$
:Date: $Date$
:Last Updated: 2005/12/12

.. contents:: Table of Contents
    :depth: 2
    :backlinks: top


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
for 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

FILTERs
..............................................................................

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
metadata you'd do the following:

.. code-block:: mapfile

    METADATA
        'multimedia_validation_pattern' '^yes|no$'
        'sound_validation_pattern' '^yes|no$'
        'nseats_validation_pattern' '^[0-9]{1,2}$'
        '... more metadata ...'
    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.

Default values if not provided in the URL
--------------------------------------------------------------------------------

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 :

.. code-block:: mapfile

    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.