@terrestris/ol-describe-map

ol-describe-map

The purpose of the ol-describe-map library is to provide configurable means of getting a textual description of an OpenLayers map.

This description could enhance OpenLayers map applications by

• providing additional information
• adding semantics
• making them more accessible (e.g. for visually impaired users)

The library ships with the most basic functionality to describe maps, which most applications will most likely adjust to their specific purpose. It is easy to configure more specific describers that take care of the specialties of your actual application.

By default a gathered map description is added to the aria-description-attribute of the div-element of the map.

Usage

Install as dependency:

npm install @terrestris/ol-describe-map

Use it to describe your map, e.g. in a moveend-handler:

// import the describe function
import { describe } from '@terrestris/ol-describe-map';

// initialise your map as usual
const map = new Map({ /* configuration left-out for brevity */ });

// whenever the map's moveend event occurs, get a description
map.on('moveend', async () => {
  let desc = await describe(map);
  console.log(desc.text);
  // …by default the aria-description attribute of the map-div is automatically
  // updated with the description. This can be configured, of course.
});

// call the describe-function with a configuration object to adjust for your specific
// needs, see the examples below.

The library ships with some textual describers, and they can be quite useful as they are. But applications might have more specific ways of describing the map content, and you can easily pass your own describer:

// instead of the following line from the above example…
let desc = await describe(map);

// …you can create…
const myDescriber = async () => {
  return 'HumptyDumpty';
};
// …and pass your own textual describer, e.g.
let desc = await describe(map, {textualDescriber: myDescriber});

Your own myDescriber function will receive objects with details of the view and all layers that were described.

Examples

These examples are all based on the main-branch:

• Basic usage
• Nominatim describer
• It's OK to useGeographic()
• Describing a vector layer
• Basic WMS layer example
• More detailed and verbose WMS layer example

API

Typedoc for all exported types and functions again for the main-branch

Development

# install dependencies
npm install

# run tests (also lints & does a typecheck)
npm test

# run tests in watch mode
npm run test:watch

# preview examples
npm run serve-examples
# examples are now listed under http://localhost:5173/

# build (library only)
npm run build

# build (examples only, rarely used)
npm run build-examples

# build (examples and library)
npm run build:all
# check the contents of the dist-folder

# cleanup build or coverage artifacts
npm run clean

TODOs

• OGC!