Mapping

Mapping

The mapping system allows administrators to define new map-based reports rapidly through the interface, and for them to be viewed on-line.

Defining a new map

Maps are defined in the same way as other reports, using the Administration | Reports menu. There are two key differences compared to other reports: requirements for the SQL data definition, and style information (Mapfile code)

SQL

The SQL is similar to all other reports, and should be a single SELECT query. However, there are several particular requirements

Required fields

Every query must return two required fields:

  • gid - this is a 'geographic ID' and is a unique integer for each spatial unit returned. Often, this can just be the id from the locations table, but if there can be multiple reports per location, you need to choose another unique ID value. It doesn't matter which. If nothing else is available, you can also use the row number window function:
select row_number() over () as gid, 
  • the_geom: this is the spatial data and must be included in every report. It should always come from the projected version of the locations table spatial data. That is:
    • For polygon data (administrative units) this should be geom_proj (e.g. select geom_proj as the_geom, )
    • For point data (village locations etc) this should be centroid_proj (e.g. select centroid_proj as the_geom, )

Don't use the standard geom and centroid columns, or the data will not be in the right projection and won't appear on the map.

Field names

Any fields generated in the query will be available to the user with a map query (where they click on a feature, and further information pops up). So that this feature works nicely, you should include all the data that a user might want to see, and name each field with a user-friendly name. For example

SELECT
  sum(total) as "Julah hewan"

Example

An example of a simple query to display infrastructure:

SELECT
  i.id as gid,
  l.centroid_proj as the_geom,
  i.shortname as "Nama infrastruktur",
from infrastructure i
join locations l on i.locationid = l.id
where not i.del

Mapfile code

The R code box of the Report definition interface is used to include mapfile code, which specifies the appearance of the output.

Most of the mapfile is automatically generated using fixed standards and the SQL previously defined, but you have to specify here how the map should appear.

The contents of the R code box is inserted into the mapfile in a LAYER block. Full documentation of what is permitted can be found in the Mapserver documentation

Two sections are required (TYPE and CLASS) and there are some optional sections

TYPE (required)

This can be POINT, LINE or POLYGON, depending on the map to be produced. For example, for a point map:

TYPE POINT

Other types can be used including CHART, CIRCLE, RASTER but these are uncommon advanced features.

CLASS (required)

This defines the appearance of the data, as well as the legend. A typical class block for a point map

 CLASS
     NAME "Kasus"
     STYLE
         SYMBOL "reddot"
     END # STYLE
 END # CLASS

This will produce a layer with a single symbol (reddot) for all features, and a legend with 'Kasus'.

For a polygon layer, you can define the colour of the outline and the fill:

 CLASS
     NAME "Pelatihan"
     STYLE
       COLOR 255 0 0
       OUTLINECOLOR 255 0 0
       SIZE 6
     END # STYLE
 END

The style options are very powerful. See the Mapserver CLASS documentation for more information.

Standard SYMBOLs are pre-defined in a symbol file. For more symbols, this file will have to be manually edited.

It is also possible to define multiple levels of shading, by referring to data from the query. For example:

 CLASS
     NAME "Belum gunakan"
     EXPRESSION ([laporan] = 0)
     STYLE
       COLOR 237 248 251
     END # STYLE
 END # CLASS

 CLASS
     NAME "1 - 5 laporan"
     EXPRESSION ([laporan] > 0  AND [laporan] < 6)
     STYLE
       COLOR 178 226 226
     END # STYLE
 END # CLASS

 CLASS
     NAME "6 - 50 laporan"
     EXPRESSION ([laporan] > 5  AND [laporan] < 50)
     STYLE
       COLOR 102 194 164
     END # STYLE
 END # CLASS

 CLASS
     NAME "> 50 laporan"
     EXPRESSION ([laporan] > 50)
     STYLE
       COLOR 35 139 69
     END # STYLE
 END # CLASS

In this case, the query must have a field called "laporan" which has an integer (the number of reports submitted).

The COLOR and OUTLINECOLOR lines require a RGB (red green blue) colour code. The ColorBrewer web site is an excellent tool for picking good map colours and finding their RGB code.

CLASSITEM (optional)

This specifies that one field in the query will be used to determine the style of different features. For example:

 CLASSITEM "Hasil"
 CLASS
     NAME "Positif"
       EXPRESSION "Pos"
     STYLE
       SYMBOL "reddot"
     END
 END

 CLASS
     NAME "Negatif"
     EXPRESSION "Neg"
     STYLE
       SYMBOL "bluedot"
     END
 END

This means that there must be a field in the query called "Hasil" and it will return values of either "Positif" or "Negatif"

Viewing maps

Maps must be viewed using the 'root' interface.

  • If there are no special parameters (the normal situation)
    • Set up a menu entry as usual, and set the URL to: root/index/reportid. For example
/root/index/216
  • If there are parameters to produce a pre-configured report (different from the default) you need to remove the first '/' and add the parameters. For example:
root/index/216&param[diagnosis]=13