.. _section2:

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 
on a web browser, there won't be any maps rendered and you will instead get blank 
images and other junk.

Variables
#########

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 CGI variables can be 
found at :ref:`here <cgi>`.

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.

Examples
--------

So, let's build an interactive interface for our application...

- Users of a web mapping application should be able to pan and zoom on the map:
  `Example 2.1 - Pan and Zoom Controls <http://demo.mapserver.org/cgi-bin/mapserv?map=/osgeo/mapserver/tutorial/htdocs/example2.map&layer=states&zoom=0&mode=browse&root=/tutorial&program=/cgi-bin/mapserv&map_web=template+example2-1.html>`_  

- They also should be able to turn on and off layers on a map:
  `Example 2.2 - Layer Control <http://demo.mapserver.org/cgi-bin/mapserv?map=/osgeo/mapserver/tutorial/htdocs/example2.map&layer=states&zoom=0&mode=browse&root=/tutorial&program=/cgi-bin/mapserv&map_web=template+example2-2.html>`_  

- A map should always include a scalebar.
  `Example 2.3 - Adding a Scalebar <http://demo.mapserver.org/cgi-bin/mapserv?map=/osgeo/mapserver/tutorial/htdocs/example2.map&layer=states&zoom=0&mode=browse&root=/tutorial&program=/cgi-bin/mapserv&map_web=template+example2-3.html>`_  

- If users are to navigate through the map, a reference map should be provided:
  `Example 2.4 - Adding a Reference Map <http://demo.mapserver.org/cgi-bin/mapserv?map=/osgeo/mapserver/tutorial/htdocs/example2.map&layer=states&zoom=0&mode=browse&root=/tutorial&program=/cgi-bin/mapserv&map_web=template+example2-4.html>`_  

- The map should include a legend.
  `Example 2.5- Adding a Legend <http://demo.mapserver.org/cgi-bin/mapserv?map=/osgeo/mapserver/tutorial/htdocs/example2.map&layer=states&zoom=0&mode=browse&root=/tutorial&program=/cgi-bin/mapserv&map_web=template+example2-5.html>`_  

----
  
:ref:`Back to Section 1 index <section1>` | :ref:`Proceed to Section 3 <section3>`

----