.. _geoext.basics.dissect:

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

As demonstrated in the :ref:`previous section <geoext.basics.map>`, a map
window is generated by bringing together a
:ref:`minimal html document <geoext.basics.dissect.document>`,
:ref:`application initialization code <geoext.basics.dissect.code>`,
and :ref:`configuration objects <geoext.basics.dissect.configuration>`.
We'll look at each of these parts in a bit more detail.

.. _geoext.basics.dissect.document:

Minimal HTML Document
---------------------

Since the mother of all web browser content is still HTML, every web
application needs at least a basic HTML document as container. It does not
contain human readable markup, so it has an empty body. But it makes sure that
all required script and style resources are loaded. These usually go in the
document's head:

.. code-block:: html

    <script type="text/javascript" src="ext/adapter/ext/ext-base.js"></script>
    <script type="text/javascript" src="ext/ext-all.js"></script>

Ext JS can be used standalone, or together with JavaScript frameworks like
JQuery. Depending on this environment, an appropriate adapter has to be loaded
first. We use Ext JS standalone, so we need the ``ext-base.js`` adapter. In the
second line, we load the main library.

Next, we load the stylesheet required by Ext JS:

.. code-block:: html

    <link rel="stylesheet" type="text/css" href="ext/resources/css/ext-all.css" />

This loads all CSS that Ext JS needs to use the default theme. For other or
custom themes, additional CSS resources would have to be added.

GeoExt not only relies on Ext JS, but also on OpenLayers. So we also have to
load OpenLayers. And finally, we can load GeoExt:

.. code-block:: html

    <script src="openlayers/lib/OpenLayers.js"></script>

    <script type="text/javascript" src="geoext/lib/GeoExt.js"></script>

.. note::

    When using GeoExt, you also benefit from all the functionality that plain
    Ext JS and OpenLayers provide. You can add GeoExt to your existing Ext JS
    and OpenLayers applications without breaking anything.

.. _geoext.basics.dissect.code:

Application Initialization Code
-------------------------------

Application initialization usually consists of two stages:

* initialize the application itself
* initialize the user interface

.. code-block:: html

    <script type="text/javascript">
    Ext.BLANK_IMAGE_URL = "ext/resources/images/default/s.gif";
            
    Ext.onReady(function() {
        new Ext.Window({
            /* configuration object goes here */
        }).show();
    });
    </script>

As an example for the former, we just set a local URL for the blank image that
Ext JS uses frequently. The latter requires that the DOM (Document Object
Model) of our HTML document is accessible, because Ext JS adds content to it
dynamically. So we build the user interface inside a function that we pass as
argument to the special ``Ext.onReady()`` hook, which gets called when the DOM
is ready. In our example, the user interface is simple. We just create a new
``Ext.Window`` and call its ``show()`` method, which will open the window. In
a more complex application, we would have multiple components with attached
event handlers so they can interact.

The interesting part is the one that is replaced with a ``/* configuration
object goes here */`` comment above. In Ext JS, we will find ourselves creating
configuration objects instead of writing code for most basic tasks, which
usually makes application development easier and faster. This is why
:ref:`configuration objects <geoext.basics.dissect.configuration>` deserve
their own section.

.. _geoext.basics.dissect.configuration:

Configuration Objects
---------------------

In Ext JS, all constructors take a single argument, which we will be referring
to as "configuration object". Like all JavaScript objects, this configuration
object is wrapped in curly braces, and contains ``key: value`` pairs. Let's
have a look at the configuration object for our map window:

.. code-block:: javascript

    {
        title: "My Map Window",
        height: 290,
        width: 528,
        layout: "fit",
        items: [{
            xtype: "gx_mappanel",
            layers: [new OpenLayers.Layer.WMS(
                        "Tasmania",
                        "/geoserver/wms?",
                        {layers: "tasmania"}
            )],
            extent: new OpenLayers.Bounds(
                143.83482400000003, -43.648056,
                148.47914100000003, -39.573891
            )
        }]
    }

We set some properties, like the ``title``, ``height`` and ``width`` of our window. 
We also set the ``layout`` to "fit", which means that the window will have one item
that fills up the entire window space.

Since other layouts can position more than just one item, we use an array
(square braces) for a list of the window's items -- in our case just one: the
map.

Above this point, we were only talking about HTML, JavaScript, CSS and Ext JS.
Now, finally, we configure our ``GeoExt.MapPanel``. To do this, we start a
nested object by declaring an ``xtype`` of "gx_mappanel".

The MapPanel configuration takes another property: an array of ``layers``. For
our simple map window, we just want to show a single WMS layer. As in plain
OpenLayers, we do this by instantiating an `OpenLayers.Layer.WMS
<http://dev.openlayers.org/apidocs/files/OpenLayers/Layer/WMS-js.html>`_ object.
If we want our MapPanel to zoom to the first layer's maximum extent, there is
nothing else we need to configure.

The last property ``extent`` is here to tell the OpenLayers map to zoom to the
given extent when initialized.

.. note::

    The following two notations are equivalent:

    * ``new GeoExt.MapPanel({layers: [/* ... */]});``
    * ``{xtype: "gx_mappanel", layers: [/* ... */]});``

    Ext JS keeps a registry of available
    `components <http://www.extjs.com/deploy/dev/docs/?class=Ext.Component>`_,
    called "xtypes". GeoExt adds its components to this registry. To make them
    distinguishable from others, their names start with the "gx\_" prefix.
    
    Using xtypes is useful when "lazy-loading" configurations. In that case,
    the configuration has to be JSON compliant, and may only contain numbers,
    strings and boolean values.

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