ml-ol-maps-ng

AngularJS directives with OpenLayers Maps integration for use with MarkLogic REST-api.

View project on GitHub

Overview

Includes directives to display MarkLogic search results on a map.

Also includes a directive to display single item on a detailed map. The detail map directive also supports showing links between items.

Key Features:

  • Show multiple geospatial facets on one map
  • Fast display of cluster markers
  • Distinctly colored markers per facet
  • Mouse interaction:
    • Pan and zoom to limit geo search (optional)
    • Click on single point markers to show details

Quickstart

To start using OpenLayers Maps for MarkLogic, follow these steps to get started.

  1. Download ml-ol-maps-ng (minified version) and put it with your other scripts. Alternatively, you can use Bower to install it automatically:

    bower install [--save] ml-ol-maps-ng

  2. If using the link analysis portion of the detail map, you can use the default graphSearch and graphExpand functions, which return the node and link data. To use the default functions, you must install the mlpm module. If you want to create your own, this mlpm module code could be used as a starting point.

    
npm install -g mlpm
mlpm install map-links --save
mlpm deploy -H localhost -P 8040 -u admin -p admin
    Enable Triple Index

    Since this library works based on SPARQL queries against triples stored in your MarkLogic database, you need to enable the triple index.

  3. If using the link analysis portion of the detail map, you can use the default graphSearch and graphExpand functions, which return the node and link data. To use the default functions, you must install the mlpm module. If you want to create your own, this mlpm module code could be used as a starting point.

    
npm install -g mlpm
mlpm install map-links --save
mlpm deploy -H localhost -P 8040 -u admin -p admin

  4. Load ol.js, angular-openlayers-directive.min.js, ml-ol-maps-ng.js and ml-ol-maps-ng-tpls.js into your HTML page (typically in the end of the BODY of your HTML):

    Note: The ol.js file must be imported before the others as they are dependent upon the OpenLayers API.

    
<script src='/bower_components/openlayers/ol.js'></script>
<script src='/bower_components/angular-openlayers-directive/dist/angular-openlayers-directive.min.js'></script>
<script src='/bower_components/ml-ol-maps-ng/dist/ml-ol-maps-ng[.min].js'></script>
<script src='/bower_components/ml-ol-maps-ng/dist/ml-ol-maps-ng-tpls[.min].js'></script>

  5. Load OpenLayers stylesheet along with the ml-ol-maps-ng.css into your HTML page (typically in the end of the HEAD of your HTML):

    
<link rel="stylesheet" href="/bower_components/ml-ol-maps-ng/dist/ml-ol-maps-ng.css" />
<link rel="stylesheet" href="/bower_components/openlayers/ol.css" />

  6. Update your application module to depend on the openlayers-directive, ml.ol-maps and ml.ol-maps.tpls modules:

    angular.module('myApplicationModule', ['openlayers-directive', 'ml.ol-maps', 'ml.ol-maps.tpls']);

Directives

ml-ol-search-facets-map

Description:

The ml-ol-search-facets-map directive utilizes geospatial facet data to draw cluster markers on the map. The geospatial facet data is expected to have a box coordinates along with the count for the number of items contained in the box. When the facets data has multiple geospatial facets, each facet gets a unique color for the cluster markers (up to 5 different colors).

Attributes:

  • facets (required): The JSON object containing the facets to be used to create data on the map.
  • base-map (optional): The JSON object containing the definition of the base map. If not specified, the default base map is Open Street Map.
  • zoom (optional): A number indicating the zoom level. If not specified, the default is 5.
  • bounds-changed (optional): The callback function reference when the bounds of the map are changed.
  • single-click (optional): The callback function reference when the map is single clicked. When a feature (point) is clicked on the map, the feature URI is the function parameter.

Example:

To use the ml-ol-search-facets-map directive, you must first follow the steps in the Quickstart section to prepare your application. Then follow the steps below:

  1. Expose objects and call-back functions in your Angular controller:

    MyCtrl.$inject = ['$scope'];
function MyCtrl($scope) {
  var ctrl = this;

  var ctrl.mapOptions = {
    zoom: 10,
    baseMap: {
      name: 'Esri Maps',
      source: {
        type: 'EsriBaseMaps',
        layer: 'NatGeo_World_Map'
      }
    }
  };

  ctrl.myFacets = {
    facets: {
      locations: {
        boxes: [
          {
            count: 180,
            s: -9.819211,
            w: -38.94669,
            n: -0.08639,
            e: -2.864274
          },
          {
            count: 60,
            s: 0.272045,
            w: -38.15781,
            n: 31.38252,
            e: -0.228349
          },
          {
            count: 53,
            s: 1.871073,
            w: 0.74539,
            n: 31.72132,
            e: 38.02885
          }
        ]
      }
    }
  };

  ctrl.mapBoundsChanged = function(bounds) {
    // place your geospatial search code here, and make that update $scope.myFacets
    //
    // The <bounds> parameter has an object structure like:
    //
    // {
    //    south: 51.0,
    //    west: 4.11,
    //    north: 53.0,
    //    east: 5.25
    // }
    //
  };

  ctrl.mapSingleClick = function(featureUri) {
    // place your code to do something with the clicked feature (e.g. - go to details page)
  };

}

  2. Add ml-ol-search-facets-map element in your template:

    <ml-ol-search-facets-map facets="ctrl.myFacets.facets" zoom="ctrl.mapOptions.zoom" base-map="ctrl.mapOptions.baseMap" bounds-changed="ctrl.mapBoundsChanged(bounds)" single-click="ctrl.mapSingleClick(featureUri)"></ml-ol-search-facets-map>

ml-ol-search-feature-map

Description:

The ml-ol-search-feature-map directive is used to display individual search results on a map. Each item to be displayed on the map must be created as a GeoJSON feature object.

It is recommended that the 'properties' property of the feature object is used to store important attributes of the feature. Specifically, the 'name' and 'uri' properties are used display data on the map. The 'name' property is used to label the point on the map. The 'uri' property is used when a point is clicked on the map.

Attributes:

  • features (required): The JSON object containing the GeoJSON feature objects to be used to create data on the map.
  • base-map (optional): The JSON object containing the definition of the base map. If not specified, the default base map is Open Street Map.
  • zoom (optional): A number indicating the zoom level. If not specified, the default is 5.
  • bounds-changed (optional): The callback function reference when the bounds of the map are changed.
  • single-click (optional): The callback function reference when the map is single clicked. When a feature (point) is clicked on the map, the feature URI is the function parameter.

Example:

To use the ml-ol-search-feature-map directive, you must first follow the steps in the Quickstart section to prepare your application. Then follow the steps below:

  1. Expose objects and call-back functions in your Angular controller:

    MyCtrl.$inject = ['$scope'];
function MyCtrl($scope) {
  var ctrl = this;

  var ctrl.mapOptions = {
    zoom: 10,
    baseMap: {
      name: 'OpenStreetMap',
      source: {
        type: 'OSM'
      }
    }
  };

  ctrl.myFeatures = [
    {
      type: 'Feature',
      properties: {
        name: 'Fred Blackstone',
        uri: '/data/fred-blackstone.json'
      },
      geometry: {
        type: 'Point',
        coordinates: [3.999297, 5.676913]
      }
    },
    {
      type: 'Feature',
      properties: {
        name: 'James Gray',
        uri: '/data/james-gray.json'
      },
      geometry: {
        type: 'Point',
        coordinates: [2.019297, 3.136382]
      }
    },
    {
      type: 'Feature',
      properties: {
        name: 'Jason Fitzgerald',
        uri: '/data/jason-fitzgerald.json'
      },
      geometry: {
        type: 'Point',
        coordinates: [5.0297, 6.6382]
      }
    }
  ];

  ctrl.mapBoundsChanged = function(bounds) {
    // place your geospatial search code here, and make that update $scope.myFacets
    //
    // The <bounds> parameter has an object structure like:
    //
    // {
    //    south: 51.0,
    //    west: 4.11,
    //    north: 53.0,
    //    east: 5.25
    // }
    //
  };

  ctrl.mapSingleClick = function(featureUri) {
    // place your code to do something with the clicked feature (e.g. - go to details page)
  };

}

  2. Add ml-ol-search-feature-map element in your template:

    <ml-ol-search-feature-map features="ctrl.myFeatures" zoom="ctrl.mapOptions.zoom" base-map="ctrl.mapOptions.baseMap" bounds-changed="ctrl.mapBoundsChanged(bounds)" single-click="ctrl.mapSingleClick(featureUri)"></ml-ol-search-feature-map>

ml-ol-detail-map

Description:

The ml-ol-detail-map directive is used to display explicit point(s) on a map. This directive has two attributes (features, geometry) that could be used to display points on the map. It is recommended that only one of these attributes be used at a time however if both attributes are used, data from each will be displayed on the map.

If using the features attribute, the data must be created as a GeoJSON feature object. It is recommended that the 'properties' property of the feature object is used to store important attributes of the feature. Specifically, the 'name' and 'uri' properties are used display data on the map. The 'name' property is used to label the point on the map. The 'uri' property is used when a point is clicked on the map.

The ml-ol-detail-map directive has the ability to display links between the default node by calling a service to get link data. The enable-links attribute is used to activate the displaying of links. When active, a node can be double-clicked to invoke the service to get linked data. When the enable-properties-view attribute is activated, a single-click on a node on the map will display the metadata for that point.

Attributes:

  • features (required): The JSON object containing the GeoJSON feature object(s) to be used to create data on the map.
  • geometry (required): The array of coordinates is used to create data on the map. For the coordinate arrays, the longitude is first followed by the latitude. An example of two points is: [[52.3881895, 4.8447237], [52.388, 9.844]].
  • base-map (optional): The JSON object containing the definition of the base map. If not specified, the default base map is Open Street Map.
  • zoom (optional): A number indicating the zoom level. If not specified, the default is 5.
  • enable-links (optional): A boolean value representing whether link data should be displayed. If not specified, the default is 'true'.
  • enable-properties-view (optional): A boolean value representing whether feature/point metadata should be displayed when single-clicked. If not specified, the default is 'true'.
  • groups (optional): An array of objects that specify colors for groups of data when link data is shown. The 'group' property of the feature/point is used to determine the color used to represent it on the map. If not specified, the default color (red) is used for all nodes.
  • single-click (optional): The callback function reference when the map is single-clicked. When a feature (point) is clicked on the map, the feature URI is the function parameter.
  • double-click (optional): The callback function reference when the map is double-clicked. When a feature (point) is clicked on the map, the feature URI is the function parameter.

Example:

To use the ml-ol-detail-map directive, you must first follow the steps in the Quickstart section to prepare your application. Then follow the steps below:

  1. Expose objects and call-back functions in your Angular controller:

    MyCtrl.$inject = ['$scope'];
function MyCtrl($scope) {
  var ctrl = this;

  var ctrl.mapOptions = {
    zoom: 10,
    baseMap: {
      name: 'OpenStreetMap',
      source: {
        type: 'OSM'
      }
    },
    groups: [
      { name: 'http://xmlns.com/foaf/0.1/Person', color: 'blue'},
      { name: 'http://xmlns.com/foaf/0.1/Organization', color: 'orange'},
    ]
  };

  ctrl.myFeatures = [
    {
      type: 'Feature',
      properties: {
        name: 'Fred Blackstone',
        uri: '/data/fred-blackstone.json',
        group: 'http://xmlns.com/foaf/0.1/Person'
      },
      geometry: {
        type: 'Point',
        coordinates: [3.999297, 5.676913]
      }
    },
    {
      type: 'Feature',
      properties: {
        name: 'James Gray',
        uri: '/data/james-gray.json',
        group: 'http://xmlns.com/foaf/0.1/Person'
      },
      geometry: {
        type: 'Point',
        coordinates: [2.019297, 3.136382]
      }
    },
    {
      type: 'Feature',
      properties: {
        name: 'Jason Fitzgerald',
        uri: '/data/jason-fitzgerald.json',
        group: 'http://xmlns.com/foaf/0.1/Person'
      },
      geometry: {
        type: 'Point',
        coordinates: [5.0297, 6.6382]
      }
    },
    {
      type: 'Feature',
      properties: {
        name: 'Acme',
        uri: '/data/acme.json',
        group: 'http://xmlns.com/foaf/0.1/Organization'
      },
      geometry: {
        type: 'Point',
        coordinates: [4.0970, 6.6382]
      }
    }
  ];

  ctrl.mapSingleClick = function(featureUri) {
    // place your code to do something with the clicked feature (e.g. - go to details page)
  };

}

  2. Add ml-ol-detail-map element in your template:

    <ml-ol-detail-map features="ctrl.myFeatures" zoom="ctrl.mapOptions.zoom" base-map="ctrl.mapOptions.baseMap" groups="ctrl.mapOptions.groups" enable-properties-view="false" single-click="ctrl.mapSingleClick(featureUri)"></ml-ol-detail-map>