Module: Decidim::Map

Defined in:
lib/decidim/map.rb,
lib/decidim/map/utility.rb,
lib/decidim/map/frontend.rb,
lib/decidim/map/provider.rb,
lib/decidim/map/geocoding.rb,
lib/decidim/map/static_map.rb,
lib/decidim/map/dynamic_map.rb,
lib/decidim/map/autocomplete.rb,
lib/decidim/map/provider/osm.rb,
lib/decidim/map/provider/here.rb,
lib/decidim/map/provider/geocoding/osm.rb,
lib/decidim/map/provider/geocoding/here.rb,
lib/decidim/map/provider/static_map/osm.rb,
lib/decidim/map/provider/dynamic_map/osm.rb,
lib/decidim/map/provider/static_map/here.rb,
lib/decidim/map/provider/autocomplete/osm.rb,
lib/decidim/map/provider/dynamic_map/here.rb,
lib/decidim/map/provider/autocomplete/here.rb

Overview

A module containing the map functionality for Decidim.

Defined Under Namespace

Modules: Provider Classes: Autocomplete, DynamicMap, Frontend, Geocoding, StaticMap, Utility

Class Method Summary collapse

Class Method Details

.available?(*categories) ⇒ Boolean

Public: Returns a boolean indicating if the category of mapping services is available for this instance that the provided key represents.



31
32
33
 
# File 'lib/decidim/map.rb', line 31

def self.available?(*categories)
  categories.all? { |category| utility_class(category).present? }
end

.configuration ⇒ Hash

Public: Returns the full maps configuration hash.



38
39
40
 
# File 'lib/decidim/map.rb', line 38

def self.configuration
  Decidim.maps
end

.configured? ⇒ Boolean

Public: Returns a boolean indicating whether the mapping functionality has been configured.



20
21
22
 
# File 'lib/decidim/map.rb', line 20

def self.configured?
  configuration.present?
end

.register_category(category, mod) ⇒ Module

Public: Registers a new category of map modules.



72
73
74
75
76
77
78
79
80
81
82
83
84
 
# File 'lib/decidim/map.rb', line 72

def self.register_category(category, mod)
  @utility_modules ||= {}
  @utility_modules[category] = mod

  # Dynamically define the category method.
  module_eval %{
    def self.#{category}(options)    # def self.dynamic(options)
      utility(:#{category}, options) #  utility(:dynamic, options)
    end                              # end
  }, __FILE__, __LINE__ - 4

  mod
end

.reset_utility_configuration! ⇒ nil

Public: Resets the utility configuration to its initial state so that it is reloaded when utility_configuration is called the next time. It should not be necessary to call this ever but it is useful for the tests as the configurations can change.



188
189
190
 
# File 'lib/decidim/map.rb', line 188

def self.reset_utility_configuration!
  @utility_configuration = nil
end

.unregister_category(category) ⇒ Module?

Public: Unregisters the given category of map modules. Mostly used for testing but there can be also actual use cases for this.



92
93
94
95
96
97
98
99
100
101
 
# File 'lib/decidim/map.rb', line 92

def self.unregister_category(category)
  return unless @utility_modules

  mod = @utility_modules.delete(category)
  @utility_configuration.delete(category) if @utility_configuration
  singleton_class.instance_eval do
    undef_method(category) if method_defined?(category)
  end
  mod
end

.utility(category, options) ⇒ Decidim::Map::Utility

Public: Creates a new instance of the correct mapping utility class for the category specified by the key argument.



49
50
51
52
53
54
55
 
# File 'lib/decidim/map.rb', line 49

def self.utility(category, options)
  return unless (klass = utility_class(category))

  config = utility_configuration(category)
  options[:config] = config.except(:provider)
  klass.new(**options)
end

.utility_class(category) ⇒ Class

Public: Returns the full utility class name in the correct module namespace for the given utility category. For example, if the provider :osm is configured for the :dynamic utilities, the utility class returned by this method is ‘Decidim::Map::Provider::DynamicMap::Osm`.



199
200
201
202
203
204
205
206
207
208
209
210
211
212
 
# File 'lib/decidim/map.rb', line 199

def self.utility_class(category)
  return unless (ns = utility_modules[category])

  config = utility_configuration(category)
  return if config.blank?
  return unless (key = config[:provider])

  # Define the last part of the class name from the category provider's key,
  # e.g. by turning `:osm` to "Osm" or `:some_service` to "SomeService".
  subclass_name = key.to_s.camelize
  return unless ns.const_defined?(subclass_name)

  ns.const_get(subclass_name)
end

.utility_configuration(category = nil) ⇒ Hash

Public: Sets and returns the utility specific configuration hash which contains the prepared configuration objects for each category of utilities.

For example, given the following configuration:

Decidim.configure do |config|
  config.maps = {
    provider: :osm,
    api_key: "apikey",
    global_conf: "value",
    dynamic: {
      tile_layer: {
        url: "https://tiles.example.org/{z}/{x}/{y}.png?{foo}",
        foo: "bar"
      }
    },
    static: {
      url: "https://staticmap.example.org/"
    },
    geocoding: {
      provider: :alternative,
      api_key: "gc_apikey",
      host: "https://nominatim.example.org/"
    }
  }
end

This would result in the following kind of configuration hash returned by this method:

{
  dynamic: {
    provider: :osm,
    api_key: "apikey",
    global_conf: "value",
    tile_layer: {
      url: "https://tiles.example.org/{z}/{x}/{y}.png?{foo}",
      foo: "bar"
    }
  }
  static: {
    provider: :osm,
    api_key: "apikey",
    global_conf: "value",
    url: "https://staticmap.example.org/"
  }
  geocoding: {
    provider: :alternative,
    api_key: "gc_apikey",
    global_conf: "value",
    host: "https://nominatim.example.org/"
  }
}



160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
 
# File 'lib/decidim/map.rb', line 160

def self.utility_configuration(category = nil)
  @utility_configuration ||= {}.tap do |config|
    break {} unless configuration

    global_config = configuration.except(*utility_modules.keys)
    utility_modules.keys.each do |key|
      utility_config = configuration.fetch(key, {})
      next if utility_config == false

      unless utility_config.is_a?(Hash)
        config[key] = global_config
        next
      end

      config[key] = global_config.merge(utility_config)
    end
  end
  return @utility_configuration[category] if category

  @utility_configuration
end

.utility_modules ⇒ Hash<Symbol, Module>

Public: Returns the utility class module namespace for each category of map utilities. The configured utility class (through Decidim.maps) is should be under these namespaces.



63
64
65
 
# File 'lib/decidim/map.rb', line 63

def self.utility_modules
  @utility_modules ||= {}
end