Documentation


Tutorials

Provided that Dracones was successfully installed, I will explain its use here through a set of simple tutorials. The aspects covered are inspired by the actual functions and services of DraconesPH, a complex public health monitoring application that was built using the Dracones framework, and is actually being used at the Direction de santé publique de Montréal (Montreal Public Health).

Steps common to all applications

Let's first perform the steps that are common to all types of applications that can be created with Dracones.

Create the application codebase

As is explained in the installation documentation, a Dracones application is composed of two interoperating web components: the core part, in charge of serving the client JS code, and executing the default Python AJAX requests, and the part for the application itself, where the content specific to it will reside. The Dracones Test App mini-application that was used for testing the installation is an example of such an application, so let's generalize the process.

The minimum application codebase would be structured as follow:

<app_location>/conf.json
<app_location>/index.html

The conf.json file would contain:

{
  "app_name": "<app_name>",
  "mapfile_path": "<app_location>"
}

A minimal index.html file would be something like:

<html>
  <head>
    <script type="text/javascript" 
               src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script>
    <script type="text/javascript" src="/dracones_core/javascript/jquery.ajaxq-0.0.1.js"></script>
    <script type="text/javascript" src="/dracones_core/javascript/jquery.mousewheel.min.js"></script>
    <script type="text/javascript" src="/dracones_core/javascript/dracones.js"></script>
  </head>
  <body>
    <div id="anchor_div" style="border: 1px solid black; width: 500px; height: 400px"></div>
  </body>
  <script type="text/javascript">
    jQuery(document).ready(function() {

      var map_widget = new dracones.MapWidget({
        anchor_elem: 'anchor_div', 
        app_name: '<app_name>', 
        mid: 'instance1', 
        map: '<mapfile>', 
        init_dlayers: ['<layer_name>']
      });

    });
  </script>
</html>

There are many aspects to note: first the client part runs with JQuery, that we load through Google Libs. We also make use of jquery-ajaxq and Mouse Wheel Extension, two small JQuery extensions that allow simple queuing of AJAX requests and mousewheel manipulation. The Dracones JS module itself is of course also included.

Next is the very important anchor_div, to which the map widget must be attached. Important: the dimensions of the anchor element (width and height) must be explicitly defined, because they will serve to calculate the map size. Finally, the JS map widget is instantiated, with a couple of mandatory parameters. Among those, the mid (Map Widget ID) would be especially important for an application that would use more than one map widget on a single page.

Configure Apache

You will also need to create an Apache configuration file, to serve the application codebase. For instance:

Alias /<app_name> <app_location>

<Directory <app_location> >
  Order allow,deny
  Allow from all
</Directory>
      

If you are using Dracones-Python, notice that no specific mod_wsgi directives are present in that particular configuration file, because for the simplest applications, all the required Python requests can be handled by our already available Dracones Core application, which is configured for WSGI. More complex applications will however make use of their own WSGI code, to carry customized operations, with the help of the Dracones Python module.