Section 2: CGI variables and the User Interface

So far we have only looked at the mapfile when creating maps. In creating web mapping applications, it is usually our intention to make maps that can be changed by the user (of the application) interactively. That is, a user should be able to change the content of (or the information in) the map. To accomplish this interactivity, we use the MapServer HTML templates.

HTML Templates

A MapServer HTML template is essentially an HTML file with a few MapServer specific tags. These tags are the MapServer CGI variables and are enclosed in square brackets „[]“. When the MapServer CGI program processes an application, it first parses the query string and the mapfile, and produces the necessary output. Some of this output will need to be written to the HTML template file which you would have to also specify in the mapfile using the web template keyword (or in a separate HTML initialization file). The CGI program will replace all the variables in the HTML template with the proper value before sending it back to the web browser. If you are to directly view an HTML template in a web browser, there won’t be any maps rendered and you will instead get blank images and other junk.


MapServer provides several variables for web mapping: the „img“ variable which you’ve seen in Example 1.9 is but one example. There area few core CGI variables originally designed as part of the mapping interface but practically all the mapfile parameters can be defined as variables. The definitive reference to the MapServer CGI variables can be found here.

We can also define our own variables, which MapServer will pass along to our application. For example, we can create a variable called „root“ to represent the root directory of this tutorial, the value for „root“ will then be „/tutorial“. When the MapServer CGI program processes our HTML template, it will replace every instance of he „[root]“ tag with „/tutorial“. You will see this in action for each of the following examples.

Run-time Substitution

Since MapServer 8.0.1, this tutorial uses MapServer’s Run-time Substitution to pass the template name through the url, such as …&template=example2-2.html. The associated mapfile’s WEB object contains a %template% variable, and a VALIDATION object with a regular expression to allow the „template=“ variable’s possible values through the url.

  TEMPLATE  '%template%'
    "template" "example2*"


So, let’s build an interactive interface for our application…

Back to Section 1 index | Proceed to Section 3