ADF DVT: Creating a Thematic Map using a Custom Base Map with hotspots

One of the interesting new features in ADF DVT 12.1.3 is the option to use a custom image as the base map for the Thematic Map component. This enables us to visualize information and support interaction in a wide variety of visual contexts. The custom image we use can represent a geographical layout, but it can really be anything we like. A map of the shopping mall, a picture of a mannequin, a map of the galaxy, a chess board: any image on which we can meaningfully present information will do. We can define the hotspots in the image where the thematic map component may render markers. The markers through shape, color, orientation and size visualize information associated with the hotspot (position).

In this article a very simple example is described of using the Thematic Map with a custom base map.

The steps are (assuming an ADF application is already created):

• find image to use for base map and add it to the application (for example public html/images)
• describe the custom base map in an XML file that references the image and defined all hotspot through x,y coordinates and a logical identifier
• add Thematic Map to a page, references the custom basemap – through a reference to the map and the XML file that contains the custom base map’s definition
• configure the Thematic Map’s pointDataLayer and marker – associating the data set to the hotspots set up for the custom base map

In this example, I will take an artist’s impression of a playground and plot the incident rate on it for each of various contraptions and areas. On top of the image, I will define hotspots for all areas and equipment for which incidents were registered. The final result looks a little like this:

The magenta bars indicate the number of occurrences of incidents on that particular spot in the playground. It turns out that the step near the very entrance into the playground is by far the most dangerous part.

Step 1 – find and download image

Just a simple Google search:

Download and save – then move to project folder images:

Step 2 – Create Custom Base Map XML file

The custom XML file has to contain the specifications for the image to be used and for each of the hotspots. I have used good old Paint to determine the x,y coordinates for my hotspots (simply move your mouse to the hotspot and read x and y on the bottom of the Paint window).

I have created the file in the Web Content (root) directory. Note the URL to the image source.

The name attribute for each of the points represents the logical identifier. The data set used to stamp out the markers will provide a matching value.

Step 3 – Add Thematic Map to a page

Assuming we already have a JSF page, simply drag the Thematic Map component to the right location.

Choose whatever shipped base map you like – we are going to overwrite that selection anyways:

In the page source, configure the thematicMap with the basemap set to playgroundBaseMap and the source referencing the XML file we created earlier on: /playground-map/xml

Step 4 – Create the data set providing the data [on the playground incidents] for the hotspots

In this case, I have set up classes PlaygroundIncident – with the details for the occurrences for a single location in the playground – and PlayGroundIncidentStatistics, that returns a collection of all locations and their incidents.

Configure a managed bean for the latter class:

Step 5 – Configure the pointDataLayer and the markers

With the managed bean at our disposal to provide the data on which we can base the markers in the thematic map for the playground, we can now configure the pointDataLayer, the pointLocation and the marker to be stamped at each location. Note how the pointDataLayer is associated with the collection (List) returned by the managed bean. This could also have been a tree-data binding to an ADF Data Control.

The pointLocation’s pointName attribute associates the location value in each incident retrieved from the collection with the logical names of the points in the custom base map (the XML file). When there is a match, the Thematic Map knows where on the image to position the marker. The marker finally has a shape, a vertical scale factor based on the number of incidents and a shortDesc – or tooltip – derived from the number of occurrences, the comment in the bean (and the long label set in the custom base map XML file.

With all this in place, we can run the application, see the end result and reconsider perhaps the color used for the “bars” in the custom map.

Here is an alternative, with triangleUp as shape and blue as the fill color:

Resources

Find the sources for this simple sample in GitHub: https://github.com/lucasjellema/ADF_DVT_CustomBaseMapSample_PlaygroundIncidents.