Client-side scripting

Submitted by Pieter De Graef on Tue, 17/03/2009 - 10:14

 

The geomajas HTML headers

All geomajas pages needed a few specific headers, CSS files and Javascript files in order to work properly. We can roughly split up the necessities in 2 parts:

  • VML specific header: geomajas tries to use native browser technologies, and for Internet Explorer this means VML.
  • geomajas specific include files. Geomajas is based on the Dojo technology, and rougly initializes in the same way Dojo does. We need a few CSS and Javascript files to have the GeoMajas technology available in our HTML page.

First up are the VML headers. Note that the HTML tag itself requires 2 VML specific attributes:

<html xmlns:vml="urn:schemas-microsoft-com:vml"
       xmlns:o="urn:schemas-microsoft-com:office:office">

<!-- VML specific stuff -->
<style type="text/css">
    vml\:* { behavior: url(#VMLRender); position:absolute }
</style>
<object id="VMLRender" codebase="vgx.dll"
      classid="CLSID:10072CEC-8CC1-11D1-986E-00A0C955B42E"
      style="width:0px;height:0px"></object>

Next is the geomajas part, in which we first load a file called "majas-constants.js". This file contains relative paths to all other needed files, and it therefore the perfect place to start. When this file is loaded, we can include all the necessary CSS and Javascript files.

<!-- Everyting needed to start up GeoMajas -->
<script type="text/javascript" src="../../majas-constants.js"></script>
<script type="text/javascript">
    document.write("<link rel='stylesheet' href='"+majasConfig.dojoHome
        +"/dojo/resources/dojo.css'>"); 
    document.write("<link rel='stylesheet' href='"+majasConfig.dojoHome
        +"/dijit/themes/"+majasConfig.dijitTheme+"/"
        +majasConfig.dijitTheme+".css'>"); 
    document.write("<link rel='stylesheet' href='"+majasConfig.majasHome
        +"/widget/themes/"+majasConfig.dijitTheme+"/"
        +majasConfig.dijitTheme+".css'>");  

    document.write("<scr"+"ipt src='http://maps.google.com/maps?file=api&v=2&key="
        +majasConfig.gKey+"'></scr"+"ipt>");
    document.write("<scr"+"ipt src='"+majasConfig.dojoHome
        +"/dojo/dojo.js'></scr"+"ipt>");
    document.write("<scr"+"ipt src='"+majasConfig.majasScript+"'></scr"+"ipt>");
</script>

 

The onLoad functionality

As said before, geomajas is an extension of the Dojo technology (client side at least). Therefore we need to follow the Dojo rules on how to initialize an application. Dojo does this by overriding the onLoad event of a page, and so does geomajas. An example, taken from the very first helloworld example HTML file, can be seen here:

<!-- Add functionality on the onLoad event -->
<script type="text/javascript">
    dojo.addOnLoad(function() {
        // Necessary initialization of geomajas:
        majasConfig["applicationUrl"] = "helloworld"; // Name of the application

        // Client-server communication through commands.
        majasConfig["dispatcher"] = new CommandDispatcher ();

        // Interpreter for the XML configurations
        var configManager = new ConfigManager (majasConfig["dispatcher"]); 

        // Fetch the configuration for application "helloworld".
        configManager.getConfigWithJson();


        // Extra's: setting a pan-controller and a scroll-controller on the map:
        var map = dijit.byId("helloMap"); // Dojo function to fetch a dojo widget.
        // "hellomap" is a mapwidget you'll find in the body tag.

        // Add a PanController to the map.
        map.addController(new PanController(map,true)); 

        // Create a subject for mousescroll listeners on the map's domNode.
        var subject = new MouseScrollListenerSubject (map.domNode); 

        // Add a mousescroll listener to the subject.
        subject.addListener (new ZoomOnScrollController(map.getMapView(), 0.2)); 
    });
</script>

So what does all of this do? First we define the name of the application, and save it in a variable called 'majasConfig["applicationUrl"]'. This name is needed when asking the server for the correct configuration, but more on that later. Next we initialize a CommandDispatcher and a ConfigManager. The CommandDispatcher (also stored in majasConfig!), is the central point for client-server communication on the client side. All communication between client and server goes through a command pattern that uses JSON as communication language. The ConfigurationManager is an interpreter for GeoMajas application configurations.

The call "configManager.getConfigWithJson();" will fetch the configuration with the name "majasConfig["applicationUrl"]" from the server, and interprete it. At this point, the geomajas application is essentially loaded. The next 4 lines of code are meant to set 2 mouselisteners (also called controllers) on the map. One for panning and one for zooming on mousescroll.

 

The BODY tag

We will dive right into it, and show you the very extensive body of the helloworld HTML file:

<body class="soria">
    <div id="helloMap" dojoType="geomajas.widget.MapWidget"
        style="margin: 0px; padding: 0px; width:100%; height:100%;"></div>
</body>

First things first. Each Dojo page needs a theme. A Dojo theme is stored in a series of CSS files, which were loaded in the header of the HTML file earlier. To specifiy which theme to load, we have included an extra rule in the majas-constants.js file. But now we need to activate this theme, by setting it's class on the body tag. As you can see, we opted for the "soria" theme in this example. If you want to switch themes, change both the value in the majasConfig variable in Javascript and the class value on the body tag. At the moment of writing, geomajas supports 2 themes: "soria" and "tundra".

Inside the body-tag there is only one simple DIV to be found. This one simple DIV represents a geomajas map. We discern 3 attributes that are all vital to showing a map. The first is an "ID" attribute. This attribute gives the MapWidget it's identifying name. A simple proof of why this attribute is needed, lies in the server side configurations. The helloworld application (and any other geomajas application) has an XML configuration for a map named "helloMap". When the ConfigManager receives the configuration for an application names "helloworld", it will find in there, a specific configuration for a map named "helloMap". The ConfigManager then tries to find this map in the body tag, and if it can find it, applies that specific map configuration.

The second attribute is the name of the widget. A geomajas map is defined in a widget called "geomajas.widget.MapWidget". This basically is the classname of the Javascript class that embodies the widget. A widget in Dojo can always be returned by calling the Dojo method "dijit.byId". Together with the ID attribute, this means that the MapWidget Javascrfipt object can be found by calling "dijit.byId("helloMap")". Remember that in the previous section of this document, we used this to set a "PanController" on the map. A "PanController" is simply a MouseListener that allows panning on the map. Finally we have given the map a certain width and height that will make sure it is visible.