decidim-core 0.22.0 → 0.23.0

data/lib/decidim/map/frontend.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Map
+    # A base class for front-end mapping functionality, common to all front-end
+    # map services, such as dynamic_map.rb and autocomplete.rb. Provides builder
+    # classes for the front-end.
+    class Frontend < Map::Utility
+      # Creates a builder class for the front-end that is used to build the HTML
+      # markup related to this utility.
+      #
+      # @param (see Decidim::Map::BuilderUtility::Builder#initialize)
+      #
+      # @return [Decidim::Map::BuilderUtility::Builder] The builder object that
+      #   can be used to build the map's markup.
+      def create_builder(template, options = {})
+        builder_class.new(template, builder_options.merge(options))
+      end
+
+      # Returns the builder class for the map. Allows fetching the class name
+      # dynamically also in the utility classes that extend this class.
+      #
+      # @return [Class] The class for the builder object.
+      def builder_class
+        self.class.const_get(:Builder)
+      end
+
+      # Returns the default options for the builder object.
+      #
+      # @return [Hash] The default options for the map builder.
+      def builder_options
+        configuration
+      end
+
+      # A general builder for any functionality needed for the views. Provides
+      # all the necessary functionality to display and initialize the front-end
+      # elements related to the given map utility.
+      class Builder
+        # Initializes the map builder instance.
+        #
+        # @param template [ActionView::Template] The template within which the
+        #   map is displayed.
+        # @param options [Hash] Extra options for the builder object.
+        def initialize(template, options)
+          @template = template
+          @options = options
+        end
+
+        # Displays the necessary front-end stylesheet assets for the map
+        # element.
+        #
+        # @return [String, nil] The map element's stylesheet assets markup for
+        #   the view or nil if there are no stylesheet assets.
+        def stylesheet_snippets; end
+
+        # Displays the necessary front-end JavaScript assets for the map
+        # element.
+        #
+        # @return [String, nil ] The map element's JavaScript assets markup for
+        #   the view or nil if there are no JavaScript assets.
+        def javascript_snippets; end
+
+        protected
+
+        attr_reader :template, :options
+
+        # Returns the options hash that will be passed to the map element as a
+        # JSON encoded data attribute. These configurations can be used to pass
+        # information to the front-end map functionality, e.g. about the tile
+        # layer configurations and markers data.
+        #
+        # @return [Hash] The configurations passed to the map element's data
+        #   attribute.
+        def view_options
+          hash_to_js(options)
+        end
+
+        # Converts a hash with Ruby-style key names (snake_case) to JS-style key
+        # names (camelCase).
+        #
+        # @param [Hash] The original hash with Ruby-style hash keys in
+        #   snake_case format.
+        #
+        # @return [Hash] The resulting hash with JS-style hash keys in camelCase
+        #   format.
+        def hash_to_js(hash)
+          hash.map do |key, value|
+            value = hash_to_js(value) if value.is_a?(Hash)
+            value = value.call(self) if value.respond_to?(:call)
+
+            [key.to_s.camelize(:lower), value]
+          end.to_h
+        end
+      end
+    end
+  end
+end

data/lib/decidim/map/geocoding.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Map
+    # A base class for geocoding functionality, common to all geocoding
+    # services.
+    class Geocoding < Map::Utility
+      # @see Decidim::Map::Utility#initialize
+      def initialize(organization:, config:, locale: I18n.locale.to_s)
+        super
+        prepare!
+      end
+
+      # The "lookup" handle to be passed to the geocoder gem. For the full list,
+      # see https://github.com/alexreisner/geocoder/blob/master/README_API_GUIDE.md.
+      #
+      # @return [Symbol] The handle of the geocoder gem's lookup
+      def handle
+        @handle ||= self.class.name.to_s.split("::")[-1].underscore.to_sym
+      end
+
+      # A common search method to lookup information about an address or
+      # coordinates from the geocoder.
+      #
+      # @param query [String, Array(<Float, String>, <Float, String>)] The
+      #   search query to be passed to the geocoder
+      # @param options [Hash] Extra options to be provided for the geocoder
+      #   search
+      #
+      # @return [Array(Float, Float), String, nil] The corresponding result for
+      #   the search query, either a string or an array containing the result
+      #   coordinates or nil when no corresponding result was found.
+      def search(query, options = {})
+        Geocoder.search(query, geocoder_options(options))
+      end
+
+      # Does a geocoding request with the given address and returns the
+      # corresponding geocoordinates as an array where the first element
+      # corresponds the latitude and the second element corresponds to the
+      # longitude.
+      #
+      # @param address [String] The address to search the geocoordinates for
+      # @param options [Hash] Extra options to be provided for the geocoder
+      #   search
+      #
+      # @return [Array(Float, Float), nil] The corresponding coordinates found
+      #  by the geocoder where the first element corresponds to the latitude
+      #  coordinate and the second element corresponds to the longitude
+      #  coordinate or nil when no result was found
+      def coordinates(address, options = {})
+        Geocoder.coordinates(address, geocoder_options(options))
+      end
+
+      # Does a reverse geocoding request with the given geocoordinates
+      # (latitude/longitude) coordinates and returns a clear text address for
+      # the closest result.
+      #
+      # @param coordinates [Array(<Float, String>, <Float, String>)] An array of
+      #   the coordinates where the first element is the latitude and the second
+      #   element is the longitude
+      # @param options [Hash] Extra options to be provided for the geocoder
+      #   search
+      #
+      # @return [String, nil] The corresponding address found by the geocoder
+      #   or nil when no result was found
+      def address(coordinates, options = {})
+        results = search(coordinates, options)
+        return if results.empty?
+
+        results.sort! do |result1, result2|
+          dist1 = Geocoder::Calculations.distance_between(
+            result1.coordinates,
+            coordinates
+          )
+          dist2 = Geocoder::Calculations.distance_between(
+            result2.coordinates,
+            coordinates
+          )
+          dist1 <=> dist2
+        end
+
+        results.first.address
+      end
+
+      protected
+
+      # @see Decidim::Map::Utility#configure
+      def configure!(config)
+        @configuration = config.merge(
+          http_headers: { "Referer" => organization.host }
+        )
+      end
+
+      # Prepares the options to be passed to the Geocoder gem.
+      #
+      # @param options [Hash] The options hash to be passed to Geocoder.
+      #
+      # @return [Hash]
+      def geocoder_options(options)
+        { lookup: handle, language: locale }.merge(options)
+      end
+
+      private
+
+      # Prepares the geocoder for the lookups with the configured geocoding
+      # service. This is called when an instance of the geocoding utility is
+      # created.
+      #
+      # @return [void]
+      def prepare!
+        Geocoder.configure(handle => configuration)
+      end
+    end
+  end
+end

data/lib/decidim/map/provider.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "decidim/map/provider/here"
+require "decidim/map/provider/osm"
+
+module Decidim
+  module Map
+    # Base module for the map providers.
+    module Provider
+    end
+  end
+end

data/lib/decidim/map/provider/autocomplete/here.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Map
+    module Provider
+      module Autocomplete
+        # The geocoding autocomplete map utility class for the HERE map
+        # services.
+        class Here < ::Decidim::Map::Autocomplete
+          class Builder < Decidim::Map::Autocomplete::Builder
+            # @see Decidim::Map::FrontendUtility::Builder#javascript_snippets
+            def javascript_snippets
+              template.javascript_include_tag("decidim/geocoding/provider/here")
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/decidim/map/provider/autocomplete/osm.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Map
+    module Provider
+      module Autocomplete
+        # The geocoding autocomplete utility class for Photon based geocoding
+        # autocompletion services which use the OpenStreetMap's (OSM) data.
+        class Osm < ::Decidim::Map::Autocomplete
+          class Builder < Decidim::Map::Autocomplete::Builder
+            # @see Decidim::Map::FrontendUtility::Builder#javascript_snippets
+            def javascript_snippets
+              template.javascript_include_tag("decidim/geocoding/provider/photon")
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/decidim/map/provider/dynamic_map/here.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Map
+    module Provider
+      module DynamicMap
+        # The dynamic map utility class for the HERE maps service
+        class Here < ::Decidim::Map::DynamicMap
+          protected
+
+          # @see Decidim::Map::DynamicMap#tile_layer_configuration
+          def tile_layer_configuration
+            base_config = configuration.fetch(:tile_layer, {})
+
+            api_key = configuration[:api_key]
+            if api_key.is_a?(Array)
+              # Support for legacy style configurations
+              ActiveSupport::Deprecation.warn(
+                <<~DEPRECATION.strip
+                  Please use a single api_key configuration for HERE maps.
+
+                  For further information, see:
+                  https://developer.here.com/documentation/maps/3.1.16.1/dev_guide/topics/migration.html
+
+                  Also make sure your Decidim.maps configurations are using the
+                  up to date format.
+                DEPRECATION
+              )
+
+              return base_config.merge(
+                app_id: api_key[0],
+                app_code: api_key[1]
+              )
+            end
+
+            base_config.merge(api_key: api_key)
+          end
+
+          # A builder for the HERE maps which needs to be configured differently
+          # than "normal" OSM based tile service providers.
+          class Builder < Decidim::Map::DynamicMap::Builder
+            # @see Decidim::Map::DynamicMap::Builder#javascript_snippets
+            def javascript_snippets
+              template.javascript_include_tag("decidim/map/provider/here")
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/decidim/map/provider/dynamic_map/osm.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Map
+    module Provider
+      module DynamicMap
+        # The dynamic map utility class for the OpenStreetMap based map services
+        class Osm < ::Decidim::Map::DynamicMap
+        end
+      end
+    end
+  end
+end

data/lib/decidim/map/provider/geocoding/here.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Map
+    module Provider
+      module Geocoding
+        # The geocoding utility class for the HERE geocoding service
+        class Here < ::Decidim::Map::Geocoding
+          # @see Decidim::Map::Geocoding#address
+          def address(coordinates, options = {})
+            # Pass in a radius of 50 meters as an extra attribute for the HERE
+            # API. Also sort the results by distance and pass a maxresults
+            # attribute of 5.
+            results = search(coordinates + [50], {
+              params: {
+                sortby: :distance,
+                maxresults: 5
+              }
+            }.merge(options))
+            return if results.empty?
+
+            # Always prioritize house number results, even if they are not as
+            # close as street level matches.
+            hn_result = results.find do |r|
+              r.data["MatchLevel"] == "houseNumber"
+            end
+            return hn_result.address if hn_result
+
+            # Some of the matches that have "MatchLevel" == "street" do not even
+            # contain the street name unless they also have the "Street" key in
+            # the "MatchQuality" attribute defined.
+            street_result = results.find do |r|
+              r.data["MatchQuality"].has_key?("Street")
+            end
+            return street_result.address if street_result
+
+            # Otherwise, sort the results based on their exact distances from
+            # the given coordinates (default functionality).
+            results.sort! do |result1, result2|
+              dist1 = Geocoder::Calculations.distance_between(
+                result1.coordinates,
+                coordinates
+              )
+              dist2 = Geocoder::Calculations.distance_between(
+                result2.coordinates,
+                coordinates
+              )
+
+              dist1 <=> dist2
+            end
+
+            results.first.address
+          end
+        end
+      end
+    end
+  end
+end

data/lib/decidim/map/provider/geocoding/osm.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Map
+    module Provider
+      module Geocoding
+        # The geocoding utility class for OpenStreetMap's (OSM) Nominatim based
+        # geocoding services
+        class Osm < ::Decidim::Map::Geocoding
+          # @see Decidim::Map::Geocoding#handle
+          def handle
+            @handle ||= :nominatim
+          end
+
+          protected
+
+          # @see Decidim::Map::Utility#configure!
+          def configure!(config)
+            @configuration = config.merge(
+              http_headers: {
+                "User-Agent" => "Decidim/#{Decidim.version} (#{Decidim.application_name})",
+                "Referer" => organization.host
+              }
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/decidim/map/provider/here.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Map
+    # A module to contain map functionality specific to the HERE map provider.
+    module Provider
+      module Autocomplete
+        autoload :Here, "decidim/map/provider/autocomplete/here"
+      end
+      module Geocoding
+        autoload :Here, "decidim/map/provider/geocoding/here"
+      end
+      module DynamicMap
+        autoload :Here, "decidim/map/provider/dynamic_map/here"
+      end
+      module StaticMap
+        autoload :Here, "decidim/map/provider/static_map/here"
+      end
+    end
+  end
+end