.. _openlayers.basics.dissect:

Dissecting Your Map
===================

As demonstrated in the :ref:`previous section <openlayers.basics.map>`, a map is
generated by bringing together :ref:`markup <openlayers.basics.dissect.markup>`,
:ref:`style declarations <openlayers.basics.dissect.style>`, and
:ref:`initialization code <openlayers.basics.dissect.code>`. We'll look at each
of these parts in a bit more detail.


.. _openlayers.basics.dissect.markup:

Map Markup
----------

The markup for the map in the :ref:`previous example <openlayers.basics.map.example>`
generates a single document element:

.. code-block:: html

    <div id="map-id"></div>

This ``<div>`` element will serve as the container for our map viewport. Here we
use a ``<div>`` element, but the container for the viewport can be any
block-level element.

In this case, we give the container an ``id`` attribute so we can reference it
easily elsewhere.


.. _openlayers.basics.dissect.style:

Map Style
---------

OpenLayers comes with a default stylesheet that specifies how map-related
elements should be styled. We've explicitly included this stylesheet in the
``map.html`` page (``<link rel="stylesheet"
href="openlayers/theme/default/style.css" type="text/css">``).

OpenLayers doesn't make any guesses about the size of your map. Because
of this, following the default stylesheet, we need to include at least one
custom style declaration to give the map some room on the page. 

.. code-block:: html

    <link rel="stylesheet" href="openlayers/theme/default/style.css" type="text/css">
    <style>
        #map-id {
            width: 512px;
            height: 256px;
        }
    </style>

In this case, we're using the map container's ``id`` value as a selector, and we
specify the width (``512px``) and the height (``256px``) for the map container.

The style declarations are directly included in the ``<head>`` of our document.
In most cases, your map related style declarations will be a part of a larger
website theme linked in external stylesheets.

.. note::

    OpenLayers enforces zero margin and padding on the element that you use for
    the viewport container. If you want your map to be surrounded by some
    margin, wrap the viewport container in another element with margin or
    padding.
    

.. _openlayers.basics.dissect.code:

Map Initialization
------------------

The next step in generating your map is to include some initialization code. In
our case, we have included a ``<script>`` element at the bottom of our document
``<body>`` to do the work:

.. code-block:: html

    <script>
        var map = new OpenLayers.Map("map-id");
        var imagery = new OpenLayers.Layer.WMS(
            "Global Imagery",
            "/geoserver/wms",
            {layers: "topp:bluemarble"}
        );
        map.addLayer(imagery);
        map.zoomToMaxExtent();
    </script>

.. note::

    The order of these steps is important. Before the our custom script can be
    executed, the OpenLayers library must be loaded. In our example, the
    OpenLayers library is loaded in the ``<head>`` of our document with
    ``<script src="openlayers/lib/OpenLayers.js"></script>``.
    
    Similarly, our custom map initialization code (above) cannot run until the
    document element that serves as the viewport container, in this case ``<div
    id="map-id"></div>``, is ready. By including the initialization code at the
    end of the document ``<body>``, we ensure that the library is loaded and the
    viewport container is ready before generating our map.

Let's look in more detail at what the map initialization script is doing. The
first line of our script creates a new ``OpenLayers.Map`` object:

.. code-block:: javascript

    var map = new OpenLayers.Map("map-id");

We use the viewport container's ``id`` attribute value to tell the map
constructor where to render the map. In this case, we pass the string value
``"map-id"`` to the map constructor. This syntax is a shortcut for convenience.
We could bee more explicit and provide a direct reference to the element (e.g.
``document.getElementById("map-id")``).

The next several lines create a layer to be displayed in our map:

.. code-block:: javascript

    var imagery = new OpenLayers.Layer.WMS(
        "Global Imagery",
        "/geoserver/wms",
        {layers: "topp:bluemarble"}
    );
    map.addLayer(imagery);

Don't worry about the syntax here if this part is new to you. Layer creation
will be covered in another module. The important part to understand is that our
map view is a collection of layers. In order to see a map, we need to include at
least one layer.

The final step is to set the geographical limits (xmin,ymin,xmax,ymax) of the
map display. This *extent* specifies the minimum bounding rectangle of a map
area. There are a number of ways to specify the initial extent. In our example,
we use a simple request to zoom to the maximum extent. By default, the maximum
extent is the world in geographic coordinates:

.. code-block:: javascript

    map.zoomToMaxExtent();

You've successfully dissected your first map! Next let's :ref:`learn more
<openlayers.basics.resources>` about developing with OpenLayers.
