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.

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

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:

They do not receive a layer order and will appear below all others, regardless of geometry type.
Info-clicks may not work (depending on the configuration of the Mapserver mapfile used by iShare).

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:

TEMPLATE
METADATA
- gml_include_items
- gml_types

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.