Map Views

A map view displays query results visually on a map. It is comprised of one or more map elements that display data on top of a blank map. The screenshot below shows the appearance of the "Display As" section of the Queries & Reports page for map views.

The block for building a map view on the Queries & Reports page.

The left side of this section allows a user to configure the row guide for the current report, and the right side allows the user to add, edit, and delete map elements from the current view. There are four types of map elements, each with a distinct appearance, each of which is described in the following sections.

Add a Map View

Select the Design Mode check box and go to Configure > Queries and Reports
On the Queries and Reports page, select an existing query or create a new one.
Locate the Display As section and click the Add View Link.
On the Add Report View dialog, enter a label name.
Select Map for View Type and at least one Designation.
Select any additional formatting options.
Click Add to Add the Map View to the query.

Markers

The Markers map type is the default type of map element, in which each query result is rendered as an icon, or marker, on a map. This map element type contains three main attributes.

The "Location" attribute will nearly always be set to a Location-type field of one of the query targets, which will provide the GPS location of each query result, and therefore where the map will display each result.

The "Icon" attribute determines which icon the map uses to represent each query result; this can either be a Media-type target field, if one of the target object types stores an icon for each object, or the user can look up icons in the Media Library using Expression Language. Whenever a user clicks on one of these icons on the map, a popup appears identifying the selected query result and showing the address at which the result is located, if any.

The "Label" attribute of the map element controls the label that appears on this popup to identify the object.

There are also two advanced attributes for Markers-type map elements, where a map view can render a transparent area around each object of a Markers element. These attributes can be useful in displaying the area of influence of each object on the map.

The "Area Radius" and "Area Color" attributes (in XML, "area-radius" and "area-color", respectively) control the radius of the circle displayed around each marker and the color of this circle.

Decorators It can be useful to set different radii or colors for different markers, bases on some field(s) of their associated query results. To accomplish this, the user can also add Decorators to the map element similar in function to column decorators, which can be applied conditionally to a marker and override its area radius and color. Note: Applying conditional decorators is considered advanced functionality and can only be added using XML. Contact your account manager for more information.

Dots

The Dots map element type is a simplified version of the Markers type, useful in displaying a great number of results on a map simultaneously.

Instead of rendering a custom icon for each query result, the map will simply render a dot at each result's location. As such, this map element type requires the same "Location" field as the Markers type, but does not require an "Icon" field. Instead, the "Dot Size" and "Dot Color" attributes control the appearance of all dots on the map. These attributes can be conditionally changed for certain dots by adding decorators to the map element through XML; these decorators contain only "size" and "color" attributes, as well as a condition under which the decorator will be applied to the element.

Clicking on one of these dots also brings up an identifying popup, and so this element type requires the same "Label" field as the Markers type.

When a map renders markers that are sufficiently close together at the current zoom level, it will render one cluster icon that displays the number of markers it represents; clicking on this cluster icon will bring up a popup showing the icons and labels of each marker it contains.

A user can zoom in on the map to differentiate markers unless they are at the exact same location (or so close that the closest zoom level of the map cannot differentiate their locations), in which case the markers will always form a cluster.

The Dots type is typically used when it is important to quickly know where all objects exist, but not to differentiate them on the map with individual icons; this goal can run in conflict to the idea of clustering, so the "Zoned" flag of a Dots element instructs the system not to cluster objects on the map, and simply render each dot, even if they overlap. As a matter of good practice, this flag should always be set for a Dots element.

The "Max Nodes" attribute caps the number of dots that the map can display at once, as the map takes longer to load if it tries to render too many query results simultaneously; by default, this value is set to 3500.

If there are too many dots located on the current zoom level of the map, the system will log an error message, and the "Category" attribute controls how the error message refers to each query object, as either a "Map Element" (default) or "Endpoint". The user need only zoom in on the map further, such that the number of objects in the viewing space is lower than the Max Nodes attribute, and the map will render these dots.

Decorators- Dot Size and Color can be conditionally changed for certain dots by adding decorators to the map element through XML; these decorators contain only "size" and "color" attributes, as well as a condition under which the decorator will be applied to the element, contact your account manager for more detail.

Add a New Map Element

Select the Design Mode check box and go to Configure > Queries and Reports
On the Queries and Reports page, select an existing query or create a new one.
Locate the Display As section and click the Add Map Element Link.
On the New Map Element dialog select the element type.

Enter the values that you want to Map and configure any other options.
Click Add to add the new map element.

Paths

The Markers and Dots types are best for displaying the current state and location of objects, as they display all objects on the map simultaneously, with no consideration of time.

However, these types are less well-suited to displaying activity records; simply displaying each activity on the map as an object would be misleading since the time an activity record was created provides important context to its location.

For example, consider the case of a truck monitoring application. A map could display every GPS activity record simultaneously and accurately describe every location a truck has visited, but without any indication of the time or order in which the truck visited those locations, the map would be relatively meaningless.

The Paths element type provides this missing context by rendering records as a set of chronological chains of actions. The "Key" attribute of this element type determines how the system groups records into distinct chains; all records with the same value of the Key field or EL expression form one chain.

The system orders records within a chain from earliest to latest based on the field or EL expression supplied for the "Time" attribute, which is typically set to the *Time field of the target activity type. The "Location" field, like that of the Dots and Markers types, determines where each record is placed on the map.

With these attributes, the map is then able to render each chain on a map. Each record itself is displayed as an arrow icon pointing towards the next record in the chain, with a number indicating that record's index within the chain. A record is connected to the next record in the chain by a line, punctuated by arrows indicating of the direction of the chain. The Paths type contains an optional "Icon" field, which replaces the default arrow icon of the final record in the crumb trail. Clicking on any crumb in the trail brings up a popup that brings up a popup with options allowing a user to customize the display of the crumb trail, but it also identifies the selected crumb, and so this element type also has a required "Label" field.

Process

The Paths type groups activities together based on a specified Key, but activities are often already grouped together into Process objects.

The Process element type behaves in almost the exact same way as the Paths type, except that it takes in only a Process-type target, instead of a Key, Location, Time, and Icon.

Each process returned by the query is represented as a chain on the map, and all activities within that process are represented as the nodes in that chain. The system will automatically use the Location and Time fields of those activities (fields which are shared by all activity types) to determine the placement and order of those nodes.

Lastly, the system will automatically use an Icon field of the process to replace the standard arrow icon of the final node in each chain, if one exists. A Process element does also have a required "Label" field like all the other element types.

Row Guides

A map view essentially displays all objects on a map at once, and if a user cannot immediately recognize each object by its location and icon, then he or she has no way of finding one specific object on this list but to click on each object to view its label. To address this issue, each map view is accompanied by a Row Guide.

A Row Guide contains a list of all objects that appear on the map, and represents them by an Icon, Label, and Description. These values are independent of the Icon and Label fields of the map elements of the view, and must be set separately using the box to the left of the list of row elements on the Queries & Reports page. The title of this box is the "Caption" field of the row guide, which also appears as the header of the guide at runtime.

For the Markers and Dots element types, a row guide will list all query results equally in the list, in the order in which they are returned by the query. For the Paths type, however, the results are sorted into their respective groups and listed in descending order.

To differentiate the different chains in this list, the row guide will display the first result in a chain as a sort of header, with a larger icon and a label identifying the chain itself; in contrast, it displays all other results in the chain with a smaller icon and a label identifying each record. The Group Key and Group Label fields serve as the identifiers for the first and other crumbs in the trail, respectively, and override the standard Label and Description fields. The Group Key and Group Label are also benign for any other map element type or view in the report.

Lastly, for the Process element type, each process object is listed on the row guide, but the individual activities are not. Within each cell for a process object, however, the row guide also displays the time range and maximum number of nodes; these values are used to filter the activities within the process that appear on the map.

The row guide lists these values as a link, and by clicking on this link, you can access a panel allowing you to change the range of times and maximum number of nodes displayed on the map.

Three row guides, for a Markers-type map element, a Paths-type element, and a Process-type element, respectively.

The above screenshot shows the standard "List" style of row guide, but you can choose one of two different styles on the Admin > Settings page; these other types are described on the Settings and Skins page.

Finally, it should be noted that all map views (and gauge views, as will be covered later in this guide) in a report use the same row guide, so if you change the guide while one view is selected, those changes will be reflected in every map and gauge view in the report.

Multiple Map Elements

In most cases, a map view will contain only a single map element with different application data sets separated into different reports for display. Although it is possible for a map view to contain more than one set of query results, this is considered advanced functionality and requires the use of a Sub-query configured via XML. Contact your account manager for more information.