.. _tutorial_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 in 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 MapServer  CGI variables can
be found :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 <https://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 <https://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 <https://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 <https://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 <https://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 <tutorial_section1>` | :ref:`Proceed to Section 3 <tutorial_section3>`
