{"id":18517731,"url":"https://github.com/projectblacklight/blacklight-maps","last_synced_at":"2026-03-02T23:38:43.518Z","repository":{"id":14655619,"uuid":"17373888","full_name":"projectblacklight/blacklight-maps","owner":"projectblacklight","description":"Map search results view for Blacklight","archived":false,"fork":false,"pushed_at":"2025-02-21T19:00:06.000Z","size":2717,"stargazers_count":14,"open_issues_count":20,"forks_count":6,"subscribers_count":26,"default_branch":"master","last_synced_at":"2026-01-14T01:42:46.179Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/projectblacklight.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-03-03T17:32:27.000Z","updated_at":"2025-02-21T16:58:07.000Z","dependencies_parsed_at":"2025-04-10T01:42:43.565Z","dependency_job_id":"7dc33078-faa5-4438-834c-abdb934d45cf","html_url":"https://github.com/projectblacklight/blacklight-maps","commit_stats":null,"previous_names":["sul-dlss/blacklight-maps"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/projectblacklight/blacklight-maps","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projectblacklight%2Fblacklight-maps","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projectblacklight%2Fblacklight-maps/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projectblacklight%2Fblacklight-maps/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projectblacklight%2Fblacklight-maps/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/projectblacklight","download_url":"https://codeload.github.com/projectblacklight/blacklight-maps/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projectblacklight%2Fblacklight-maps/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30025316,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-02T23:36:48.274Z","status":"ssl_error","status_checked_at":"2026-03-02T23:33:36.569Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T17:08:12.597Z","updated_at":"2026-03-02T23:38:43.501Z","avatar_url":"https://github.com/projectblacklight.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Blacklight::Maps\n\n![CI](https://github.com/projectblacklight/blacklight-maps/workflows/CI/badge.svg) | [![Coverage Status](https://coveralls.io/repos/projectblacklight/blacklight-maps/badge.svg?branch=master)](https://coveralls.io/r/projectblacklight/blacklight-maps?branch=master)\n\nProvides map views for Blacklight for items with geospatial coordinate (latitude/longitude) metadata.\n\nBrowse all records by 'Map' view:\n![Screen shot](docs/blacklight-maps_map-view.png)\n\nMap results view for search results (coordinate data as facet):\n![Screen shot](docs/blacklight-maps_index-view.png)\n\nMaplet widget in item detail view:\n![Screen shot](docs/blacklight-maps_show-view.png)\n\n## Installation\n\n(See [Blacklight Version Compatibility](#blacklight-compatibility) below to make sure you're using a version of the gem that works with the version of Blacklight you're using.)\n\nAdd this line to your application's Gemfile:\n\n    gem 'blacklight-maps'\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install blacklight-maps\n    \nRun Blacklight-Maps generator:\n    \n    $ rails g blacklight_maps:install\n\n## Usage\n\nBlacklight-Maps integrates [Leaflet](http://leafletjs.com/) to add map view capabilities for items with geospatial data in their corresponding Solr record.\n\nIn the map views, locations are represented as markers (or marker clusters, depending on the zoom level). Clicking on a marker opens a popup which (depending on config settings) displays the location name or coordinates, and provides a link to search for other items with the same location name/coordinates.\n\nUsers can also run a search using the map bounds as coordinate parameters by clicking the ![search control](docs/blacklight-maps_search-control.png) search control in the map view. Any items with coordinates or bounding boxes that are contained within the current map window will be returned.\n\nIn the catalog#map and catalog#index views, the geospatial data to populate the map comes from the facet component of the Solr response. Bounding boxes are represented as points corresponding to the center of the box.\n\nIn the catalog#show view, the data simply comes from the main document. Points are represented as markers and bounding boxes are represented as polygons. Clicking on a polygon opens a popup that allows the user to search for any items intersecting the bounding box.\n\n### Solr Requirements\n\nBlacklight-Maps requires that your Solr index include at least one (but preferably BOTH) of the following two types of fields:\n\n1. A `location_rpt` field that contains coordinates or a bounding box. For more on `location_rpt` see [Solr help](https://cwiki.apache.org/confluence/display/solr/Spatial+Search). This field can be multivalued.\n\n  ```\n  # coordinates: lon lat or lat,lon\n  # bounding box: ENVELOPE(minX, maxX, maxY, minY)\n  coordinates_srpt: \n   - 78.96288 20.593684\n   - 20.593684,78.96288\n   - ENVELOPE(68.162386, 97.395555, 35.5044752, 6.7535159)\n  ```\n\n2. An indexed, stored string field containing a properly-formatted [GeoJSON](http://geojson.org) feature object for a point or bounding box that includes the coordinates and (preferably) location name. This field can be multivalued.\n\n  ```\n  # first example below is for coordinate point, second is for bounding box\n  geojson_ssim:\n   - {\"type\":\"Feature\",\"geometry\":{\"type\":\"Point\",\"coordinates\":[78.96288,20.593684]},\"properties\":{\"placename\":\"India\"}}\n   - {\"type\":\"Feature\",\"geometry\":{\"type\":\"Polygon\",\"coordinates\":[[[68.162386, 6.7535159], [97.395555, 6.7535159], [97.395555, 35.5044752], [68.162386, 35.5044752], [68.162386, 6.7535159]]]},\"bbox\":[68.162386, 6.7535159, 97.395555, 35.5044752]}\n  ```\n\n  If you have #2 above and you want the popup search links to use the location name as a search parameter, you also need:\n\n3. An indexed, stored text or string field containing location names. This field can be multivalued.\n\n  ```\n   subject_geo_ssim: India\n  ```\n\n##### Why so complicated?\nBlacklight-Maps can be used with either field type (#1 or #2), however to take advantage of the full feature set, it is preferred that both field types exist for each item with geospatial metadata.\n\n* The GeoJSON field (#2 above) provides reliable association of place names with coordinates, so the map marker popups can display the location name\n* The Location name field (#3 above) allows users to run meaningful searches for locations found on the map\n* The Coordinate field (#1 above) provides for the \"Search\" function on the map in the catalog#map and catalog#index views\n\n\n**Important:** If you are NOT using the geojson field (#2), you should create a `copyField` in your Solr schema.xml to copy the coordinates from the `location_rpt` field to a string field that is stored, indexed, and multivalued to allow for proper faceting of the coordinate values in the catalog#map and catalog#index views.\n\n```\n  \u003c!-- Solr location_rpt field for coordinates, shapes, etc. --\u003e\n  \u003cdynamicField name=\"*_srpt\" type=\"location_rpt\" indexed=\"true\" stored=\"true\" multiValued=\"true\" /\u003e\n  \u003c!-- copy geospatial to string field for faceting --\u003e\n  \u003ccopyField source=\"coordinates_srpt\" dest=\"coordinates_ssim\" /\u003e\n```\n\nSupport for additional field types may be added in the future.\n\n### Configuration\n\n#### Required\nBlacklight-Maps expects you to provide these configuration options:\n\n+ `facet_mode`  = the type of field containing the data to use to display locations on the map (values: `'geojson'` or `'coordinates'`)\n  - if `'geojson'`:\n    + `geojson_field` = the name of the Solr field containing the GeoJSON data\n    + `placename_property` = the key in the GeoJSON properties hash representing the location name\n  - if `'coordinates'`\n    + `coordinates_facet_field` = the name of the Solr field containing coordinate data in string format (`\u003ccopyField\u003e` of `coordinates_field`)\n+ `search_mode` = the type of search to run when clicking a link in the map popups (values: `'placename'` or `'coordinates'`)\n  - if `'placename'`:\n    + `placename_field` = the name of the Solr field containing the location names\n+ `coordinates_field` = the name of the Solr `location_rpt` type field containing geospatial coordinate data\n\nIn addition, you must add the geospatial facet field to the list of facet fields in `app/controllers/catalog_controller.rb`, for example:\n```ruby\nconfig.add_facet_field 'geojson_ssim', :limit =\u003e -2, :label =\u003e 'Coordinates', :show =\u003e false\n```\n\n#### Optional\n\n- `show_initial_zoom` = the zoom level to be used in the catalog#show view map (zoom levels for catalog#map and catalog#index map views are computed automatically)\n- `maxzoom` =  the maxZoom [property of the map](http://leafletjs.com/reference.html#map-maxzoom)\n- `tileurl` = a [tileLayer url](http://leafletjs.com/reference.html#tilelayer-l.tilelayer) to change the basemap\n- `mapattribution` = an [attribution string](http://leafletjs.com/reference.html#tilelayer-attribution) to describe the basemap layer\n- `spatial_query_dist` = the radial distance, in kilometers, to search from a supplied coordinate point in a spatial search. This corresponds to the `d` [Spatial Filter](https://cwiki.apache.org/confluence/display/solr/Spatial+Search) parameter in Solr. \n\n\nAll of these options can easily be configured in `CatalogController.rb` in the `config` block.\n\n```ruby\n...\n  configure_blacklight do |config|\n    ## blacklight-maps configuration default values\n    config.view.maps.geojson_field = \"geojson\"\n    config.view.maps.placename_property = \"placename\"\n    config.view.maps.coordinates_field = \"coordinates\"\n    config.view.maps.search_mode = \"placename\" # or \"coordinates\"\n    config.view.maps.spatial_query_dist = 0.5\n    config.view.maps.placename_field = \"placename_field\"\n    config.view.maps.coordinates_facet_field = \"coordinates_facet_field\"\n    config.view.maps.facet_mode = \"geojson\" # or \"coordinates\"\n    config.view.maps.tileurl = \"http://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png\"\n    config.view.maps.mapattribution = 'Map data \u0026copy; \u003ca href=\"http://openstreetmap.org\"\u003eOpenStreetMap\u003c/a\u003e contributors, \u003ca href=\"http://creativecommons.org/licenses/by-sa/2.0/\"\u003eCC-BY-SA\u003c/a\u003e'\n    config.view.maps.maxzoom = 18\n    config.view.maps.show_initial_zoom = 5\n\n    config.add_facet_field 'geojson', :limit =\u003e -2, :label =\u003e 'Coordinates', :show =\u003e false\n...\n\n```\n\n### Implementation\n\nThe catalog#map and catalog#index map views are available by default. The \"browse everything\" Map view will be available in your app at `/map`, and in your app using routing helper `map_path`. \n\nHowever, the catalog#show maplet widget must be included manually, via one of two ways:\n\n1. Include the catalog/show_maplet_default partial explicitly. This option gives you the most flexibility, as you can choose where the partial gets rendered.\n\n  ```ruby\n    \u003c%= render partial: 'catalog/show_maplet_default' %\u003e\n  ```\n\n2. Add `:show_maplet` to the list of partials to be rendered automatically by Blacklight in `CatalogController.rb` in the `config` block. This option is less work up front, but it may be more difficult to customize how the maplet is integrated into the page layout. \n\n  ```\n  ...\n    configure_blacklight do |config|\n      # add :show_maplet to the show partials array\n      config.show.partials \u003c\u003c :show_maplet\n  ...\n  ```\n\n### Customization\n\nThe ```blacklight_map_tag``` helper takes an options hash as one of its arguments that can be used to provide customization options for the Leaflet map functionality via data attributes. (See ```app/views/catalog/index_map``` for an example.) The available options include:\n\nOption | Type | Default | Description\n------ | ---- | ------- | -----------\n`initialview` | Array | `null` | the initial extend of the map as a 2d Array (e.g. `[[minLat, minLng], [maxLat, maxLng]]`)\n`searchcontrol` | Boolean | `false` | display the search control on the map\n`catalogpath` | String | `'catalog'` | the search path for the search control\n`placenamefield` | String | `'placename_field'` | the name of the Solr field containing the location names\n`searchctrlcue` | String | `'Search for all items within the current map window'` | the hover text to display when the mouse hovers over the ![search control](docs/blacklight-maps_search-control.png) search control\n`searchresultsview` | String | `'list'` | the view type for the search results on the catalog#index page after the map ![search control](docs/blacklight-maps_search-control.png) search control is used\n`singlemarkermode` | Boolean | `true` | whether locations should be clustered\n`clustercount` | String | `'locations'` | whether clusters should display the location count or the number of hits (`'hits'` or `'locations'`)\n`maxzoom` | Integer | 18 | the maxZoom [property of the map](http://leafletjs.com/reference.html#map-maxzoom)\n`tileurl` | String | `'http://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png'` | a [tileLayer url](http://leafletjs.com/reference.html#tilelayer-l.tilelayer) to change the basemap\n`mapattribution` | String | ``Map data \u0026copy; \u003ca href=\"http://openstreetmap.org\"\u003eOpenStreetMap\u003c/a\u003e contributors, \u003ca href=\"http://creativecommons.org/licenses/by-sa/2.0/\"\u003eCC-BY-SA\u003c/a\u003e'` | an [attribution string](http://leafletjs.com/reference.html#tilelayer-attribution) to describe the basemap layer\n`nodata` | String | `'Sorry, there is no data for this location.'` | a message to display in the Leaflet popup when the \"popup\" member is not present in the properties hash in the GeoJSON Feature for a location.\n\n### \u003ca name=\"blacklight-compatibility\"\u003e\u003c/a\u003eBlacklight Version Compatibility\nThe table below indicates which versions of Blacklight Maps are compatible with which versions of Blacklight.\n\nBlacklight Maps version | works with Blacklight version\n----------------------- | ---------------------\n1.2.* | \u003e= 7.35.0, \u003c 8\n1.1.* | \u003e= 7.8.0, \u003c 8\n0.5.* | \u003e= 6.1.0, \u003c 7\n0.4.* | \u003e= 5.12.0, \u003c 6.*\n\u003c= 0.3.3 | \u003e= 5.1, \u003c= 5.11.2\n\n## Contributing\n\nWe encourage you to contribute to Blacklight-Maps. Please see the [contributing guide](/CONTRIBUTING.md) for more information on contributing to the project.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprojectblacklight%2Fblacklight-maps","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprojectblacklight%2Fblacklight-maps","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprojectblacklight%2Fblacklight-maps/lists"}