About Features Downloads Getting Started Documentation Events Support GitHub

Love VuFind®? Consider becoming a financial supporter. Your support helps build a better VuFind®!

Site Tools


Warning: This page has not been updated in over over a year and may be outdated or deprecated.
configuration:geographic_features

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
configuration:geographic_features [2018/04/24 02:20] – [VuFind 5.0] lmgonzalesconfiguration:geographic_features [2023/10/24 19:25] (current) – [General Configuration Notes] lmgonzales
Line 1: Line 1:
-Starting with VuFind 3.1, a new set of modules were introduced for displaying geographic data at the record level, as well as a geographic search interface.  +====== Geographic Features ======
-  - Provided the option for displaying multiple geographic features (points and/or rectangles) for a record. +
-  - Provided a geographic search interface. +
-  - Added configuration options for the geographic search and display interfaces.+
  
-To properly configure the Geographic Search & Display modules, you will need to ensure that your data is indexed properlyand then you will need to configure the module options in the associated .ini files+VuFind® contains modules for displaying geographic data at the record levelas well as a geographic search interface
  
-For an overview of these features as they were originally developed for VuFind 3.1, you can [[https://vufind.org/docs/summit2016/geo.pptx|download the presentation slides]] from the VuFind 2016 Summit for more information. +Features:
  
-===== Changes from VuFind 4.x to 5.0 ===== +  - Can display multiple geographic features (points and/or rectangles) for a record
-:!: Starting in VuFind 4.0, the OpenLayers functionality has been removed and replaced with Leaflet. +  - Provides a geographic search interface. 
- +  - Includes configuration options for the geographic search and display interfaces.
-Other improvements include:  +
-  * Improved search results clustering +
-  * Streamlining of configuration parameters, which are now all located in geofeatures.ini +
- +
-===== Changes from VuFind 3.1 to 4.x ===== +
-The VuFind 3.1.x version of these modules preserved and upgraded the VuFind 2.x GoogleMap functionality, so that it was compliant with the new Google API key requirements. +
- +
-:!: Starting in VuFind 4.0, the GoogleMap functionality has been removed, some [[development:architecture:solr_index_schema#vufind_40|Solr schema details]] have been adjusted, and the Geographic Search & Display modules use OpenLayers exclusivelySee [[https://github.com/vufind-org/vufind/pull/995|pull request #995]] to review the Google Map code that was removed. +
- +
  
 +To properly configure the Geographic Search & Display modules, you will need to ensure that your data is indexed properly, and then you will need to configure the module options in the associated .ini files. 
  
 +This functionality was first introduced in VuFind® 3.1; it has subsequently evolved, as described in the [[configuration:geographic_features:changelog|geographic features changelog]].
  
 ===== Indexing Geographic Data ===== ===== Indexing Geographic Data =====
Line 29: Line 19:
 ==== Coordinates ==== ==== Coordinates ====
 The coordinate data will go into field 034 of your MARC record, in subfields $d,$e,$f, and $g.  The coordinate data will go into field 034 of your MARC record, in subfields $d,$e,$f, and $g. 
-You can format your coordinates as decimal degrees (DD) or degrees minutes seconds (DMS), and you can assign hemispheres by using either letters (N,S,E,W) or symbols (+,-).+You can format your coordinates as decimal degrees (DD) or degrees minutes seconds (DMS), and you can assign hemispheres by using either letters (N,S,E,W) or symbols (+,-). If you omit the + sign, it is considered the default.
 Note that the order for coordinates in the [[http://www.loc.gov/marc/bibliographic/concise/bd034.html|MARC 034 field]], is: Note that the order for coordinates in the [[http://www.loc.gov/marc/bibliographic/concise/bd034.html|MARC 034 field]], is:
 $d: West; $e: East; $f: North; $g: South $d: West; $e: East; $f: North; $g: South
  
-* Note, [[https://github.com/vufind-org/vufind/pull/1076|PR#1076]] upgrades the code to allow for unsigned DD coordinates. With this patch, positive values do not need to be prefixed with the + sign.  +If malformed coordinates are detected during indexing, an error message containing the record ID, coordinate values, and problems with the coordinate values will be displayed. Malformed coordinates will not be included in the indexed record
- +
-If malformed coordinates are detected during indexing, an error message containing the record ID, coordinate values, and problems with the coordinate values will be displayed. Malformed coordinates will not be indexed. +
  
 ==== Labels ==== ==== Labels ====
Line 61: Line 49:
  
 ==== Solr fields and files ==== ==== Solr fields and files ====
-Starting in VuFind 4.0, the following Solr fields are used store geographic data:  +Starting in VuFind® 4.0, the following Solr fields are used store geographic data:  
-  * **long_lat**: stores the coordinates as a bounding box field type and you can reference the Solr Spatial Guide (listed at the bottom of the slide) for more information on that.+  * **long_lat**: stores the coordinates as a bounding box field type and you can reference the [[https://solr.apache.org/guide/solr/latest/query-guide/spatial-search.html|Solr Spatial Guide]] for more information on that.
   * **long_lat_display**: used for storing the coordinates that are used in the record's geographic display.   * **long_lat_display**: used for storing the coordinates that are used in the record's geographic display.
   * **long_lat_label**: used for storing the labels that are used in the record's geographic display.    * **long_lat_label**: used for storing the labels that are used in the record's geographic display. 
  
-:!: //Note that VuFind 3.1 used the **long_lat** field differently and also relied on a **location_geo** field that was removed in 4.0. Details on the old 3.1 definitions are here:// +See the [[development:architecture:solr_index_schema#changelog|Solr Schema Changelog]] for details on how this changed from earlier versions.
- +
-  * **location_geo**stores the coordinates as a bounding box field type and you can reference the Solr Spatial Guide (listed at the bottom of the slide) for more information on that. +
-  * **long_lat**: used for the GoogleMaps record geographic display.+
  
 The following files handle the indexing of geographic data: The following files handle the indexing of geographic data:
   * **schema.xml**: Includes all the fields listed above, the _geo field type, and two dynamic fields: _geo and _geo_mv.   * **schema.xml**: Includes all the fields listed above, the _geo field type, and two dynamic fields: _geo and _geo_mv.
   * **marc_local.properties**: Includes all the fields listed above.   * **marc_local.properties**: Includes all the fields listed above.
-  * **GeoTools.java**: Contains the geographic indexing routines. (//This code was found in **VuFindIndexer.java** prior to release 4.0//).+  * **GeoTools.java**: Contains the geographic indexing routines.
  
  
 ===== Displaying Geographic Data ===== ===== Displaying Geographic Data =====
-Starting with VuFind 5.0, geographic features are //only// displayed with **Leaflet**. 
- 
-:!: In VuFind 4.x, geographic features are //only// displayed with **OpenLayers**. 
  
-:!: In VuFind 3.1you have two options for displaying the geographic features of those records: **OpenLayers** or **GoogleMaps**.+==== Underlying Technology ==== 
 +Starting with VuFind® 5.0, geographic features are displayed with **Leaflet**. For historical information about earlier implementations using OpenLayers and GoogleMaps, click the "Old revisions" button below to find earlier versions of this page.
  
-==== Leaflet - VuFind 5.0 only ==== 
 Leaflet provides a light-weight code base for displaying point and rectangle features, as well as their labels and coordinates.  Leaflet provides a light-weight code base for displaying point and rectangle features, as well as their labels and coordinates. 
 Features can be clicked on to show a popup window that will display the label and/or coordinates of that feature depending on how the [MapTab] section is configured in the **geofeatures.ini** file. Features can be clicked on to show a popup window that will display the label and/or coordinates of that feature depending on how the [MapTab] section is configured in the **geofeatures.ini** file.
  
-//Notes:// +==== General Configuration Notes ==== 
-  * The recordMap parameter in geofeatures.ini [MapTab] section has changed from a string to a boolean field in VuFind 5.0 so that it can be used to toggle the Map Tab display on and off.+  * The recordMap parameter in geofeatures.ini [MapTab] section can be used to toggle the Map Tab display on and off.
   * The basemap is set in the [Basemap] section of geofeatures.ini   * The basemap is set in the [Basemap] section of geofeatures.ini
  
Line 107: Line 89:
 Labels can be read from the long_lat_label field if they are stored in Solr, or assigned on the fly with a look-up table. If you use a look-up table, put it in your local/config/vufind/ directory, and in the geofeatures.ini file, set mapLabels = file:filename. Labels can be read from the long_lat_label field if they are stored in Solr, or assigned on the fly with a look-up table. If you use a look-up table, put it in your local/config/vufind/ directory, and in the geofeatures.ini file, set mapLabels = file:filename.
  
-==== OpenLayers - VuFind 3.1 and 4.x only ==== +:!: // Note:  Starting in VuFind® 7.0., the contentsecuritypolicy.ini file was implementedYou will need to modify this file to include the basemap tileserver domain
-OpenLayers allows you to display point and rectangle featuresas well as their labels and coordinates.  +
-Features can be clicked on to show a popup window that will display the label and/or coordinates of that feature depending on how Geographic Display section is configured in the [[.files:config.ini]] file. +
-The pop-up window uses the built-in internationalization support so that as you switch languages, the title of the pop-up window (e.g., "At this location") will be translated into the selected language+
  
-Configuration options for OpenLayers display from config.ini file:+The following is an example if you are using CARTO basemap server: 
 +// 
 <code> <code>
-; Geographic Display +img-src[]  "http://basemaps.cartocdn.com" 
-recordMap openlayers +
-mapLabels = driver ; OR file:filename +
-displayCoords = true; OR false +
-graticule = true; OR false+
 </code> </code>
 +==== Notes on Map Tiles ====
  
-Labels can be read from the long_lat_label field if they are stored in Solr, or assigned on the fly with look-up table. If you use a look-up table, put it in your local/config/vufind/ directory, and in the config.ini file, set mapLabels = file:filename. +Map display depends on access to tile set to allow zooming and scrolling around the worldThe geofeatures.ini file includes some example tile URLs, but tile sets from free providers come with significant limitations on usage. If you wish to use this feature in production, you may need to subscribe to commercial map provider or else run your own [[configuration:geographic_features:map_tile_server|local tile server]].
- +
- +
- +
-==== GoogleMaps - VuFind 3.1 only==== +
-:!: //Support for the GoogleMaps display option is only available in VuFind 3.1; it is removed in later versions.// +
- +
-With this option you can only display point features and their labels. You must also supply the GoogleMaps API key in the Geographic Display section of the [[.files:config.ini]] file.  +
- +
-Configuration options for GoogleMaps display from config.ini file: +
-<code> +
-; Geographic Display +
-recordMap = google +
-mapLabels = driver ; OR file:filename +
-displayCoords = false; **Not supported with GoogleMaps** +
-googleMapApiKey = API Key +
-</code> +
- +
-Labels can be read from the long_lat_label field if they are stored in Solr, or assigned on the fly with a look-up table. If you use a look-up table, put it in your local/config/vufind/ directoryand in the config.ini file, set mapLabels = file:filename.  +
- +
-Note that display of coordinates is not supported with the GoogleMaps display option +
  
 +One way to help reduce the amount of map tile server calls is to configure the defaultRecordTab setting in the config.ini file to something other than "Map".
 ===== Geographic Searching ===== ===== Geographic Searching =====
  
Line 150: Line 107:
 You can zoom in to uncluster or zoom out to cluster the points.  You can zoom in to uncluster or zoom out to cluster the points. 
  
-In VuFind 5.0: 
   * Features are clustered based on proximity. You can zoom in to uncluster features. Rectangle feature center points are denoted by marker icons with flat tops and point features are denoted with marker icons with rounded tops.   * Features are clustered based on proximity. You can zoom in to uncluster features. Rectangle feature center points are denoted by marker icons with flat tops and point features are denoted with marker icons with rounded tops.
   * Click on an icon to see the title of the associated record.   * Click on an icon to see the title of the associated record.
- 
-In VuFind 4.x: 
-  * Any clusters with less than five records can be clicked on to show a pop-up with the list of titles in that cluster.  
-  * Additionally, you can click on a title in the pop-up to see the corresponding full record view.   
  
 You can also click on the **Draw Search Box** button, and then click and drag to create the search box query.  You can also click on the **Draw Search Box** button, and then click and drag to create the search box query. 
Line 162: Line 114:
  
 If you need help, just click on the **Need Help?** link next to the **Draw Search Box** button.  If you need help, just click on the **Need Help?** link next to the **Draw Search Box** button. 
-The help text for geographic searching has been integrated into the VuFind help system so that the help is easier to maintain for translation purposes+The help text for geographic searching has been integrated into the VuFind® help system so that the help is easier to maintain for translation purposes.
- +
-Starting in VuFind 4.0, the geographic search queries against the long_lat field and returns the data from the following fields: long_lat, title, id. +
- +
-:!: In VuFind 3.1, the geographic search queries against the location_geo field and returns the data from the following fields: location_geo, title, id.+
  
 +Starting in VuFind® 4.0, the geographic search queries against the long_lat field and returns the data from the following fields: long_lat, title, id.
 ==== Configurable Options ==== ==== Configurable Options ====
 To turn on the geographic search functionality, uncomment the MapSelection line in the Top Recommendations section of the searches.ini file: To turn on the geographic search functionality, uncomment the MapSelection line in the Top Recommendations section of the searches.ini file:
Line 174: Line 123:
 </code> </code>
  
-=== VuFind 5.0: === +You can set the default search box coordinates and the height of the map search interface in the [MapSelection] section of the **geofeatures.ini** file.
-Set the default search box coordinates and the height of the map search interface in the [MapSelection] section of the **geofeatures.ini** file.+
  
 When setting your default search coordinates, try to focus the search on either an area with the most results or an area of high interest. Don’t make the search area too large or too small. You’ll probably have to play with the search interface to find the right setting.  When setting your default search coordinates, try to focus the search on either an area with the most results or an area of high interest. Don’t make the search area too large or too small. You’ll probably have to play with the search interface to find the right setting. 
Line 188: Line 136:
 ; height:    Height in pixels of the map selection interface. ; height:    Height in pixels of the map selection interface.
 default_coordinates = "-95, 30, 72, 15" default_coordinates = "-95, 30, 72, 15"
-height = 320 
-</code> 
- 
-=== VuFind 3.1 and 4.x: ==== 
-Set the default search box coordinates and the height of the map search interface in the Map Selection section of the searches.ini file. 
- 
-When setting your default search coordinates, try to focus the search on either an area with the most results or an area of high interest. Don’t make the search area too large or too small. You’ll probably have to play with the search interface to find the right setting.  
-<code> 
-[MapSelection] 
-; The default coordinates specified below are in decimal degrees, and are  
-; ordered as WENS (west, east, north, south). Ranges of valid values are: 
-; -180 to 180 (longitude) and -85 to 85 (latitude). Note, to search from and to 
-; the international date line, use west = -179 and east = -180.  
-default_coordinates = "-95, 30, 72, 15" 
-; height: Height in pixels of the map selection interface. 
 height = 320 height = 320
 </code> </code>
Line 228: Line 161:
 DismaxHandler: edismax DismaxHandler: edismax
 </code> </code>
- 
-==== Caveats for VuFind 3.1 and 4.x ==== 
-The following functionality was upgraded in VuFind 5.0. In VuFind 5.0, all geographic features that intersect the search box are plotted. Center points for rectangle features are clustered and clusters, when hovered over show the range of center points contained within the cluster. 
- 
-**Clustering of Rectangle Features** \\ 
-Search results clustering requires that all clustered features be points. As such, the code calculates the center point for each rectangle feature.  
-The code goes through several routines to check for rectangle features that intersect the search box, and to check if the center point of those rectangles land within the search box.  
-For those rectangles that intersect the search box and have center points that fall outside of the search box, the code sets the rectangles' center points to the center of the search box.  
- 
-**Records with Multiple Geographic Features** \\ 
-For records that have multiple geographic features, only the first feature that falls within the search box is plotted in the search results.  
- 
  
 ===== Customizing the Geographic Search & Display Code ===== ===== Customizing the Geographic Search & Display Code =====
  
-==== VuFind 5.0 ==== +The geographic search & display features was first implemented in [[https://github.com/vufind-org/vufind/pull/722/files|pull request #722]]. The code was significantly revised in [[https://github.com/vufind-org/vufind/pull/1129/files|pull request #1129]].
-The upgrades and code for the VuFind 5.0 implementation of the Geographic Features code can be found here: [[https://github.com/vufind-org/vufind/pull/1129/files|PR#1129]]+
  
-==== VuFind 3.1 and 4.x ==== +The notes below refer to the code as it has existed since release 5.0; for notes on earlier versions, see the "Old revisions" button below.
-The code for the geographic search & display features can be viewed on github here: [[https://github.com/vufind-org/vufind/pull/722/files|PR#722]]+
  
 If you want to customize the Geographic Display code, you will need to modify these files: If you want to customize the Geographic Display code, you will need to modify these files:
  
   * RecordTab/map.phtml  (also contains GoogleMap javascript code)   * RecordTab/map.phtml  (also contains GoogleMap javascript code)
-  * js/map_tab_ol.js (OpenLayers javascript code)+  * js/map_tab_leaflet.js 
   * RecordTab/Factory.php   * RecordTab/Factory.php
   * RecordTab/Map.php   * RecordTab/Map.php
   * RecordDriver/SolrDefault.php   * RecordDriver/SolrDefault.php
 +  * GeoFeatures/MapTabConfig.php
 +
  
 If you want to customize the Geographic Search code, you will need to modify these files: If you want to customize the Geographic Search code, you will need to modify these files:
Line 261: Line 182:
   * search/searchbox.phtml (if enabled in searches.ini, Geographic Search option appears in search box.)   * search/searchbox.phtml (if enabled in searches.ini, Geographic Search option appears in search box.)
   * root/templates/HelpTranslations/en/geosearch.phtml (help text for geographic search module)   * root/templates/HelpTranslations/en/geosearch.phtml (help text for geographic search module)
-  * js/map_selection.js+  * js/map_selection_leaflet.js
   * Recommend/MapSelection.php   * Recommend/MapSelection.php
 +  * GeoFeatures/MapSelectionConfig.php
 +
   * View/Helper/Root/GeoCoords.php (returns geographic search query parameters).   * View/Helper/Root/GeoCoords.php (returns geographic search query parameters).
  
 The following files support both the Geographic Display and Geographic Search code: The following files support both the Geographic Display and Geographic Search code:
  
-OpenLayers 3.17.1 code: +Leaflet code: 
-  * js/vendor/ol/ol.js , ol-debug.js +  * js/vendor/leaflet/* 
-  * css/vendor/ol/ol.css+  * css/vendor/leaflet/
 + 
 +configuration file: 
 +  * geofeatures.ini 
 + 
 +Helper methods: 
 +   * GeoFeatures/AbstractConfig.php 
 +   * GeoFeatures/BasemapConfig.php 
 +   * GeoFeatures/AbstractConfig.php 
  
 RecordDriver/SolrDefault.php methods: RecordDriver/SolrDefault.php methods:
-  * getLongLat :!: //VuFind 3.1. only// 
   * getGeoLocation   * getGeoLocation
   * getDisplayCoordinates   * getDisplayCoordinates
Line 279: Line 210:
 CSS styling – add geoItem class for pop-ups to these files: CSS styling – add geoItem class for pop-ups to these files:
   * css/compiled.css   * css/compiled.css
 +  * css/geofeatures.css
   * less/components/search.less   * less/components/search.less
  
 +===== Additional Resources =====
 +
 +For an overview of these features as they were originally developed for VuFind® 3.1, you can [[https://vufind.org/docs/summit2016/geo.pptx|download the presentation slides]] from the [[community:conferences:summit_2016|VuFind® 2016 Summit]] for more information. 
  
 ---- struct data ---- ---- struct data ----
 +properties.Page Owner : lmgonzales
 ---- ----
  
configuration/geographic_features.1524536415.txt.gz · Last modified: 2018/04/24 02:20 by lmgonzales