Module: Decidim::Map

Defined in:
decidim-core/lib/decidim/map.rb,
decidim-core/lib/decidim/map/utility.rb,
decidim-core/lib/decidim/map/frontend.rb,
decidim-core/lib/decidim/map/provider.rb,
decidim-core/lib/decidim/map/geocoding.rb,
decidim-core/lib/decidim/map/static_map.rb,
decidim-core/lib/decidim/map/dynamic_map.rb,
decidim-core/lib/decidim/map/autocomplete.rb,
decidim-core/lib/decidim/map/provider/osm.rb,
decidim-core/lib/decidim/map/provider/here.rb,
decidim-core/lib/decidim/map/provider/geocoding/osm.rb,
decidim-core/lib/decidim/map/provider/geocoding/here.rb,
decidim-core/lib/decidim/map/provider/static_map/osm.rb,
decidim-core/lib/decidim/map/provider/dynamic_map/osm.rb,
decidim-core/lib/decidim/map/provider/static_map/here.rb,
decidim-core/lib/decidim/map/provider/autocomplete/osm.rb,
decidim-core/lib/decidim/map/provider/dynamic_map/here.rb,
decidim-core/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.

Parameters:

  • *categories (Symbol) —

    The utility category key to check the availability for.

Returns:

  • (Boolean) —

    A boolean indicating if the category of mapping services is available.



31
32
33
 
# File 'decidim-core/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.

Returns:

  • (Hash) —

    The full map functionality configuration hash.



38
39
40
 
# File 'decidim-core/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.

Returns:

  • (Boolean) —

    A boolean indicating whether the mapping functionality has been configured.



20
21
22
 
# File 'decidim-core/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.

Parameters:

  • category (Symbol) —

    The key for the category.

  • mod (Module) —

    The module to be assigned for the category.

Returns:

  • (Module) —

    The module which was assigned for the category.



72
73
74
75
76
77
78
79
80
81
82
83
84
 
# File 'decidim-core/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.

Returns:

  • (nil) 


188
189
190
 
# File 'decidim-core/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.

Parameters:

  • category (Symbol) —

    The key for the category.

Returns:

  • (Module, nil) —

    The module which was previously assigned for the category or nil if no module was previously assigned for it.



92
93
94
95
96
97
98
99
100
101
 
# File 'decidim-core/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.

Parameters:

  • category (Symbol) —

    The utility category key for the utility to be created.

  • options (Hash) —

    The options for the utility constructor method.

Returns:



49
50
51
52
53
54
55
 
# File 'decidim-core/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`.

Parameters:

  • category (Symbol) —

    The category of utilities. E.g. ‘:dynamic`.

Returns:

  • (Class) —

    The configured mapping service provider key.



199
200
201
202
203
204
205
206
207
208
209
210
211
212
 
# File 'decidim-core/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/"
  }
}

Parameters:

  • category (Symbol, nil) (defaults to: nil) —

    The key of the utility category for which to fetch the configuration for. When nil, returns the whole configuration hash.

Returns:

  • (Hash) —

    The configuration hash.



160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
 
# File 'decidim-core/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.

Returns:

  • (Hash<Symbol, Module>) —

    The modules within which the utility classes should be defined in.



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

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