From: Andrea Buntz Neiman Date: Fri, 9 Apr 2021 14:50:10 +0000 (-0400) Subject: Docs: Sort by Geographic Proximity X-Git-Url: https://old-git.evergreen-ils.org/?a=commitdiff_plain;h=eab504c88c869efbbbf8292940e4e5770f96cb06;p=evergreen%2Fpines.git Docs: Sort by Geographic Proximity Signed-off-by: Andrea Buntz Neiman Signed-off-by: Galen Charlton --- diff --git a/docs/modules/admin_initial_setup/pages/geosort_admin.adoc b/docs/modules/admin_initial_setup/pages/geosort_admin.adoc new file mode 100644 index 0000000000..a06bd90cd4 --- /dev/null +++ b/docs/modules/admin_initial_setup/pages/geosort_admin.adoc @@ -0,0 +1,97 @@ += Sort by Geographic Proximity: Configuration + +indexterm:[Geographic Sort,Search Results,Searching] + +:toc: + +The sort by geographic proximity feature allows library patrons to sort +holdings within a bibliographic record by geographic distance. This +feature requires a 3rd party geographic location service in order to +function. Each Evergreen instance will need to secure its own geographic +location service. + +The feature is controlled by three new Library Settings, a new Global +Flag, two new permissions, and a new interface to configure Geographic +Location Services. Fields to store latitude and longitude have been +added to the *Org Unit Configuration* (/eg2//staff/admin/server/actor/org_unit) page. + +== Library Settings + +* *Enable Holdings Sort by Geographic Proximity* - if this is unset it +will default to FALSE. If set to TRUE, the record details page will +display the address search box to enable proximity sort. The global flag +*opac.use_geolocation* must also be enabled. +* *Geographic Location Service to use for Addresses* - This setting +specifies which geographic location service to use for converting +address input to geographic coordinates. Geolocation Services are +configured via *Server Administration → Geographic Location Services +Configuration* interface. The value used in this is what is entered in +the *Name* field of the Geographic Location Services Configuration. +* *Show Geographic Proximity in Miles* - If set to TRUE, this setting will +force the OPAC to display distance in miles. If this is unset it will +default to FALSE, and the OPAC will display distance in kilometers. + +== Global Flag + +Navigate to *Server Administration → Global Flags* and locate the +opac.use_geolocation flag. Select the *Enabled* checkbox to enable this +flag. This flag must be enabled in order for proximity sort to work. The +*Value* box does not need an entry and in fact any entry in that box +will be ignored. + +== Permissions + +Two new permissions, VIEW_GEOLOCATION_SERVICES and +ADMIN_GEOLOCATION_SERVICES, control viewing and editing values in the +Geolocation Location Services interface. They are added to the System +Administrator and Global Administrator permissions groups by default. + +== Geographic Location Service Configuration + +There is a new administrative interface located at *Server +Administration → Geographic Location Service* +(/eg2//staff/admin/server/config/geolocation_service) which +allows administrators to add and configure new geographic location +services and parameters + +Click the button *New Geographic Location Service* to add a service to +this table. Fields in the modal are: + +* _API Key_ - Provided by your geographic location service provider in +order to authenticate against their service +** Note that HTTP referrers will not work with this feature, but IP address restrictions will. +* _Active_ - Specifies whether this particular location service is active +or not. +* _ID_ - This is automatically generated by the system. +* _Name_ - Enter a name for this service in the Library Setting +*Geographic Location Service to use for Addresses*. Since this value is +translatable, if you give it a translation the Library Setting will +automatically update to the translated value. +* _Owner_ - Indicates which branch owns this service. This gives context +to the two new permissions noted above but does not otherwise affect the +* _Service Code_ - Determines which perl module to use for geocoding. +Valid values are Free, Google, or OSM. +** As of 2021, the perl module 'Google' uses the https://metacpan.org/pod/Geo::Coder::Google[GeoCoder v3 API]. Administrators are strongly advised to review the current Google API documentation. + +You will assign Service Providers to specific Organizational Units using +the Library Setting *Geographic Location Service to use for Addresses*. + +== Other Administration + +The feature makes use of the latitude/longitude of each location’s +physical address, as set in the *Org Unit Configuration* +(/eg2//staff/admin/server/actor/org_unit) page. There is a new +pair of fields to contain Latitude and Longitude as well as a button +which will use the physical address to calculate values for these two +fields. + +Navigate to *Server Administration → Organizational Units*. Select the +relevant Organizational Unit from the tree on the left, select the +*Addresses* tab, and then select the *Physical Address* subtab. You may +manually enter Latitude and Longitude values, or select the *Get +Coordinates* button to generate coordinates from the address entered in +the Physical Address subtab. Click the *Save* button to save your +changes. + +The latitude and longitude values are available in the *Org Address* +reporting source. \ No newline at end of file diff --git a/docs/modules/opac/assets/images/media/geosort_entry_box.PNG b/docs/modules/opac/assets/images/media/geosort_entry_box.PNG new file mode 100644 index 0000000000..1642626b40 Binary files /dev/null and b/docs/modules/opac/assets/images/media/geosort_entry_box.PNG differ diff --git a/docs/modules/opac/assets/images/media/geosort_results_km.PNG b/docs/modules/opac/assets/images/media/geosort_results_km.PNG new file mode 100644 index 0000000000..2af98ba544 Binary files /dev/null and b/docs/modules/opac/assets/images/media/geosort_results_km.PNG differ diff --git a/docs/modules/opac/assets/images/media/geosort_retrieval_error.PNG b/docs/modules/opac/assets/images/media/geosort_retrieval_error.PNG new file mode 100644 index 0000000000..2491cdaace Binary files /dev/null and b/docs/modules/opac/assets/images/media/geosort_retrieval_error.PNG differ