ol-ishare: OpenLayers client for iShare

Overview

ol-ishare provides a modern mapping interface to Astun Technology's iShare product. Built on OpenLayers (currently ol@6.5.0), it aims to be easily embeddable and modular for ease of deployment and development.

Common scenarios

Along with the core Javascript modules, ol-ishare also includes a compiled module and pre-built applications for typical use-cases.

oli module

The ol-ishare core Javascript code is compiled to a single UMD module to allow for straightforward inclusion in other projects. This can be included in a page and all features will then be available under a global oli reference. CSS rules for default styling of the few UI elements included in the code are also supplied.

Including files in your project

While you can download the above pre-built files (and any of the others linked on this site) and include that copy in the pages of your project, it is strongly recommended that Astun's hosted versions are linked to directly. That will ensure that you get all fixes and updates as soon as they are released.

Examples

To show the ways in which the oli library can be used, ol-ishare comes with several examples.

Apps

These apps have been created to avoid having to compile JS for a range of scenarios. Unless you want to optimize for size, or have particular legacy browser support requirements, these are probably the best way to make use of ol-ishare.

LiteMap

This lightweight iShare map has been designed to be able to be integrated directly into other web applications.

Include the JS and CSS files in a web application that might benefit from having maps with user interaction. Some configuration is required, principally the iShare web application URL and the names of the required layers.

Spotlight

For creation and embedding of iShare maps without requiring writing code, Spotlight features a user-interface with ability to build up a map from scratch.

Point the app at an iShare web application URL and select layers and other UI options. Then generate <iframe> HTML to drop directly in a third-party app; or a link to a map page than can be used directly.

Customise user interface text

When using iShare v6.0.9 or above the text displayed in the Spotlight Map user interface is customisable via the iShare Studio Language Editor. The "iShare URL" determines which Language Override will be used, for example, Welsh customers typically publish two versions of a Spotlight Map, each using a domain name associated with the desired language. See Customise user interface text below for further details of customising the Spotlight Map UI text.

Logger

Logger is similar to LiteMap, but provides the additional ability for users to select a feature or location on a map. This is typically used to enhance a web app capturing other user feedback, such as reporting on street furniture or fly tipping.

In order to add Logger to a web application, include the JS and CSS files and then create a LoggerMap instance - see the Logger Tutorial for an overview of the concepts and a walk through of building a Logger map, or copy the app page to jump straight in. There is also a demo that gives an idea as to how Logger might work in practice.

Gazetteer

Standalone auto-complete address search useful for providing an address lookup when no map is required.

Technical documentation

Customise user interface text

ℹ️ Requires iShare v6.0.9

The text displayed in the ol-ishare user interface (UI) can be customised via the Language Editor in iShare Studio. Commonly the Language Editor is used to:

The text displayed by ol-ishare is customised by editing the keys in the Language Editor that start with oli for example oli.baseMapsTitle sets the title of the base maps group and oli.layerSwitcher.hideButtonTitle sets the tooltip for the button that hides the layer switcher.

ℹ️ To see changes made in the Language Editor, save your changes and close Studio then recycle the IIS Application Pool associated with the iShare Web website

Alternative languages (commonly Welsh)

Welsh iShare Maps customers commonly configure two Workspaces, one for the English website, the other for the Welsh website. Each Workspace is assocated with a domain, for instance the English website might be at en.example.gov.uk and the Welsh website at cy.example.gov.uk. In addition each Workspace is configured with a Language Override file. A Welsh Language Override file (E:\iShareData\LIVE\Config\webservice\config\LangWelsh.xml) is available which provides defaults for ol-ishare UI text in Welsh.

The Language used by ol-ishare is determined by the iShareUrl, if the iShareUrl was https://en.example.gov.uk/ then the English Workspace and hence English Language would be used while setting the iShareUrl to https://cy.example.gov.uk/ would use the Welsh Workspace and Language. The same goes for Spotlight, the language of the Spotlight Map UI is determined by the "iShare URL".

Customising UI text - Spotlight Map

When Spotlight Maps are created, they automatically load the UI text string lookups from iShare.

The keys in the Language Editor that start with oli.apps.spotlight support overriding UI text specifically within Spotlight. For example to override the gazetteer search placeholder for Spotlight, provide a value for oli.apps.spotlight.gazetteer.placeholder in your Language Override file. Within Spotlight this value will take precedence over oli.gazetteer.placeholder which will be used for all other ol-ishare applications.

Advanced: Override additional Spotlight Map UI text

By default the only Spotlight specific key is oli.apps.spotlight.gazetteer.placeholder. To override additional keys for Spotlight they must first be added to D:\Astun\iShare\LIVE\WebApps\WebService\xml\languageBase.xml after which they are available to override via the Language Editor.

For example to allow overriding the zoom button tooltips in Spotlight add the following to the bottom of languageBase.xml before the </root> element:

<key id="oli.apps.spotlight.zoom.zoomInTipLabel">Zoom in</key>
<key id="oli.apps.spotlight.zoom.zoomOutTipLabel">Zoom out</key>

Customising UI text - LiteMap

As with Spotlight, LiteMap instances automatically load UI text from iShare when created. If you are using the default controls then these are configured with the appropriate text when they are created by LiteMap. The UI text lookup is available once the 'load' event is dispatched so it is recommended to wait until the 'load' event to create custom controls in order that they can be configured with text from the lookup. For example when using the UMD bundle:

const lite = new oli.litemap.LiteMap({
  target: 'map',
  iShareUrl: 'https://maps.demo.astuntechnology.com/',
  profile: 'mapsources/ol-ishare',
  layers: [
    { name: 'Primary_Schools', visible: true },
    { name: 'Secondary_Schools', visible: false }
  ]
});

lite.on('load', function (evt) {
  // Create a LayerSwitcher control showing legend graphics
  lite.map.addControl(
    new oli.control.layerswitcher.LayerSwitcher({
      activationMode: 'click',
      startActive: true
    })
  );
});

In the above example, simply creating the LayerSwitcher control within the 'load' event is enough for the UI text to be configured based on the values set via the Language Editor as ol-ishare control attempt to configure their UI text using the UI text lookup if it has been loaded.

It's also possible to override the values set via the Language Editor by configuring the control with code, for example by setting the tipLabel and collapseTipLabel options of the LayerSwitcher:

lite.on('load', function (evt) {
  // Create a LayerSwitcher control showing legend graphics
  lite.map.addControl(
    new oli.control.layerswitcher.LayerSwitcher({
      activationMode: 'click',
      startActive: true,
      tipLabel: 'Show the legend',
      collapseTipLabel: 'Hide the legend'
    })
  );
});

LiteMap instances have a lang property which is populated with the UI text lookup once it has been loaded. This can be used to read any UI text values for use within your application.

Customising UI text - Logger

As Logger is built on LiteMap, see Customising LiteMap UI text for details of customising the UI test for Logger controls.

Currently Logger doesn't have any unique UI text.

Standalone Gazetteer

The standalone Gazetteer makes use of the createGazetteer factory function which creates a UI Gazetteer instance pre-configured with UI text loaded from iShare Language Editor if available.

To override the default UI text for the Gazetteer control update the values for keys starting with oli.gazetteer in the Language Editor.

Custom development

For cases where the pre-built apps don't cover the requirement for a given set of requirements, ol-ishare comes with substantial API Documentation for developers wishing to create and compile their own applications.

Enable CORS

Several requests made by ol-ishare such as WFS GetFeature requests require the iShare Maps server to support CORS requests. To enable CORS add the following to WebApps\Web\Web.config as a child of <system.webServer>:

    <httpProtocol>
        <customHeaders>
            <remove name="Access-Control-Allow-Origin" />
            <add name="Access-Control-Allow-Origin" value="*" />
            <remove name="Access-Control-Allow-Headers" />
            <add name="Access-Control-Allow-Headers" value="Accept,Content-Type,X-Requested-With" />
            <remove name="Access-Control-Allow-Methods" />
            <add name="Access-Control-Allow-Methods" value="GET, OPTIONS" />
        </customHeaders>
    </httpProtocol>

Note: The remove entries prior to adding the headers are to ensure we don't end up inheriting a header of the same name from a parent site or virtual directory which causes IIS to crash.

Gotchas

Or: things that might trip up a developer or implementer, especially if coming from working with other maps.

Legacy iShare layers

The legacy iShare 'Classic' layer type is not officially supported by ol-ishare. Please use the current layer definitions, designed for use with OGC web services, instead. However, the maps may well still work, but with the following, non-exhaustive, list of caveats:

HOWTO: Configure Mapserver LAYER for ol-ishare info-click

In order for a Mapserver layer to be queryable by ol-ishare (which uses WMS GetFeatureInfo), the LAYER block needs to contain the following configuration items:

The following shows how these would appear in a typical layer, using values that should work for all iShare Mapserver .map files.

    LAYER
        TEMPLATE "globexml.xml"
        METADATA
            gml_include_items "all"
            gml_types "auto"
            (other metadata, if required)
        END
    (other layer configuration)
    END

This configuration is automatically generated for standard iShare Layers, but will need to be added manually to the Mapserver configuration for any iShare Classic Layers that are intended to be used with ol-ishare.

However, bear in mind that as Classic Layers are not officially supported by ol-ishare there may be additional issues, now, or in future, and the best solution is to convert them to standard iShare Layers.

Layer ordering

While OpenLayers maps by default order layers based on the order in which they are added to the map, ol-ishare explicitly sets a zIndex value on all layers loaded via an iSharejs profile, based on their geometry type. This is to provide a good level of visibility by default. See Profile#Layer for details.

Changelog

Notable changes to ol-ishare.

v1.1.5

Customise UI text via Studio Language Editor

When using iShare v6.0.9 or above the text displayed in the ol-ishare user interface (Spotlight, LiteMap, Logger etc.) is customisable via the iShare Studio Language Editor. The iShareUrl determines which language will be used. Commonly Welsh customers would publish two versions of each ol-ishare map each using the domain associated with the desired language.

See Customise user interface text for further details of customising the ol-ishare UI text.

WMTS base map support

Adds support for WMTS base maps in ol-ishare when using iShare v6.0.0 and above.

Spotlight accessibility improvements

Other fixes

Upgrading

Updating Spotlight Maps

Providing you are using the v1 release of Spotlight via https://ol-ishare.services.astuntechnology.com/v1/apps/spotlight/ no action is required to upgrade.

Upgrading UMD bundle (oli.js/oli.css)

If your application is using the oli.js/oli.css UMD bundle via https://ol-ishare.services.astuntechnology.com/v1/umd/ and loading OpenLayers in a separate script tag via https://ol-ishare.services.astuntechnology.com/v1/examples/assets/ then no changes are required to make use of the new functionality. This generally applies to applications using LiteMap, Logger and the standalone Gazetteer.

Upgrading ol-ishare package (ES modules)

To upgrade an application that makes use of the ol-ishare ES modules:

API Changes

Additions
Breaking changes