Mapworks Mouseover, Mouse-click and Zoom-to Example (Angular)

Developers
, ,
1

Mapworks Mouseover, Mouse-click and Zoom-to Example (Angular)

Introduction

This example illustrates writing a Mapworks Studio web application to customise:

  1. Mouseover, tooltip and mouse-click events & display customisation; and
  2. The webapp initiated zoom to feature operation with a custom marker to
    highlight the point feature centred on the map.
    In this example, each time this operation s a random feature is chosen

The use case also includes Mapworks user auth within the Angular framework.

Please see GitHub - mapworksio/mapworks-mouseover-zoomto-angular-example: Mapworks Mouseover, Mouse-click and Zoom-to Example (Angular).

The example works locally and in CodeSandbox (though be aware that if you fork it you will need to update the app configuration as at least the return to URL will need to change).

The map is viewable as guest but you can login to test as well. Specific details for the Mapworks org/app/map used are in a section below.

As noted in the README, you can use the MapworksMapService code (copy into your project - we will provide via npm package later) as per the example.

Running in CodeSandbox

This example may be run in CodeSandbox:

Application configuration

As configured, this example web application makes use of the following Mapworks resources:

The application configuration (in src/app/app.config.ts) is as follows:

export const appConfig = {
  mapworksOrgUrl: 'https://app.mapworks.io',
  client_id: '3mvor82v8k8f6nbi4f8bpihsom',
  mapRef: 'map-osm-public',
  layerRef: 'ne_10m_populated_places',
};

Notes:

  1. This application has been configured in the to operation when running locally
    (http://localhost:4200) and when running on CodeSandbox (link above).

  2. If the CodeSandbox application is forked (and as a result, will be accessed on a
    different web application URL) the Mapworks Application client_id will need to
    updated to an application configured in your Mapworks Organisation.

Map “feature” events

A Mapworks map provides a multitude of events relating to the user’s interaction
with the map. These may be listened to by applications.

We focus on three in this example, being:

  1. feature:mouseover - an instantaneous event emitted when the mouse pointer passes
    over a feature on the map. These are emitted at high volume during map interaction
    and it is often necessary to throttle the rate depending on the application.

    In this example webapp, the mouseover events are captured, throttled to a rate of 10/second
    and displayed above the map (see (1) below).

  2. feature:tooltip - a “brief” on-map tooltip, displayed after the mouse pointer is hovered
    (paused in the same location) for a small period. The default tooltip makes use of the
    features queryable fields and the Tooltip Text Format string (set in Layer Styles).

  3. feature:mouseclick - a “fuller” on map display which is shown after the user clicks on
    a feature on the map. The default mouse click display loads all fields for the feature (from
    the Mapworks server) and displays them in tabular form.

As well as the default displays on the map, as described above, each of these events are
available in code in this example, and the webapp displays them as follows:

mapworks-mouse-event-display
mapworks-mouse-event-display1260Ă—274 43 KB

Refer to the following in the code:

The following screenshots demonstrate the out-of-the-box behaviour of the Studio map application for
a simple tooltip and mouse-click display for the OSM Populated Places layer (as used throughout
this example):

default-tooltip
default-tooltip1660Ă—935 121 KB

default-mouseclick
default-mouseclick1660Ă—935 129 KB

Mouseover and tooltip customisation

The on-map display for both tooltips and mouse-click display may be customised.

Additionally, the mouse-click display may include a deferred/asynchronous update which
enable web applications to obtain further data before updating the display.

In order to perform this customisation, it is neccessary to obtain the instance of the
MapworksStudioTooltipControl instance associated with the Studio map, and listen to the
before:render event. This enables access to the context object (containing details
of the feature being displayed etc) to be accessed and the templates to be used for
display to be replaced or modified.

In this example web application:

  1. The tooltip display utilises an Angular component displayed within the tooltip utilising
    Angular elements. See more below.

  2. The mouse-click display utilises a simulated asychronous load (in this case a 2 second delay)
    and modifies the default tabular display by inserting the Mapworks logo.

The produces:

custom-tooltip
custom-tooltip2214Ă—1246 166 KB

custom-mouseclick-loading
custom-mouseclick-loading2214Ă—1246 165 KB

custom-mouseclick-loaded
custom-mouseclick-loaded2214Ă—1246 180 KB

Note that in all cases, Mapworks take care of the correct positioning the displayed element
with respect to the feature on the map.

Refer to the following in the code:

  • src/app/main-app/main-app.component.ts - the
    wiring for listening to the before:render events, customising the display templates
    and providing the context object to the custom element via MouseoverDataProvider.

Angular elements

To achieve Angular component-level integration for this example, Angular elements
(web custom elements, also called Web Components) are utilised.

Mapworks utilises HTML text (as string’s within the API) to provide content
for tooltip and mouse-click displays. The use of custom elements enables
the use of Angular components to be used for this use case.

Refer to the following in the code:

  • src/app/mapworks-map.service.ts - registers the custom
    element and binds an injector for the MouseoverDataProvider class to provide
    the context object supplied by the Studio map event to the Angular component.

  • src/app/mouseover/mouseover.component.ts - the
    Angular elements component displayed in the tooltip and mour-click displays.

  • src/app/main-app/main-app.component.ts - the
    wiring for listening to the before:render events, customising the display templates
    and providing the context object to the custom element via MouseoverDataProvider.

Standard templates

It may be helpful to refer to the standard Studio templates for tooltips and mouse-click
displays:

Webapp initiated Zoom to feature

This part of the the example webapp performs the following:

  1. Random selection of a map feature from within the OSM Populated Places layer.

  2. Initiation of a smooth, animated zoom to feature operation to centre the map
    on the location of the selected feature.

  3. Placement of a custom marker, utilising an animated SVG, to highlight the
    feature on the map. Refer to the SVG marker icon used:

    marker-example

Refer to the following in the code:

Using the Mapworks code

The src/app/mapworks subfolder may be copied and used directly in web application code.

  • src/app/mapworks - this contains the MapworksMapService class used to manage auth and map initialisation.
  • src/main.ts - contains code to handle the OAuth2/OIDC callback used as part of the sign in process (this will need to be incorporated or use login-callback.html)
  • src/assets/login-callback.html - this handles the OAuth2/OIDC callback used as part of the sign in process (preferred in non-CodeSandbox environments)

Note that due to constraints of the CodeSandbox environment, the OAuth2/OIDC callback is handled in src/main.ts - for non-CodeSandbox you are probably better utilising the static login-callback.html (app-config.ts needs to be updated to reflect this).

Other Examples

Please also see the following related examples:

  1. Mapworks Auth Example - User Sign In before loading map
  2. Mapworks Auth Example (Angular)
1 Like