Dissecting Your Map Window

As demonstrated in the previous section, a map window is generated by bringing together a minimal html document, application initialization code, and configuration objects. We’ll look at each of these parts in a bit more detail.

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:

<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:

<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:

<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.

Application Initialization Code

Application initialization usually consists of two stages:

  • initialize the application itself
  • initialize the user interface
<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 configuration objects deserve their own section.

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:

{
    title: "My Map Window",
    height: 290,
    width: 528,
    layout: "fit",
    items: [{
        xtype: "gx_mappanel",
        layers: [new OpenLayers.Layer.WMS(
            "World",
            "/geoserver/ows?",
            {layers: "world"}
        )]
    }
}

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 object. If we want our MapPanel to zoom to the first layer’s maximum extent, there is nothing else we need to configure.

Note

The following two notations are equivalent:

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

Ext JS keeps a registry of available components, 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 learn more about developing with GeoExt.