decidim 0.23.5 → 0.24.2

data/docs/advanced/permissions.md

@@ -1,23 +0,0 @@
-# Permissions
-
-Since Decidim has multiple roles, we needed a permissions system to discover what actions can a user perform, given their roles. The basis of the current permissions system were added on [\#3029](https://github.com/decidim/decidim/pull/3029), so be sure to check that PR (and the related ones) to read the discussion and the motivations behind the change.
-
-## Overview
-
-When checking for permission to perform an action, we check this chain:
-
-1. The component permissions
-1. The participatory space permissions
-1. The core permissions
-
-This way we're going from more specific to more general.
-
-## Explanation
-
-We wrap the permission and its context in a `PermissionsAction` object. It also holds the state of the permission (whether it's been allowed or not).
-
-Each component and space must define a `Permissions` class, inheriting from `Decidim::DefaultPermissions`. The `Permissions` class must define a `permissions` instance method. this class will receive the permission action, and the `permissions` method must return the permission action. The `Permissions` class can set the action as allowed or disallowed.
-
-There's a small limitation in the permission action state machine: once it's been disallowed it can't be reallowed. This is to avoid mischievous modules modifying permissions.
-
-Permission actions have a scope. It's usually either `:public` or `:admin`, and the `Permissions` class usually handles the `:public` scope, while it delegates the `:admin` one to another specialized class.

data/docs/advanced/releases.md

@@ -1,114 +0,0 @@
-# Releasing new versions
-
-In order to release new version you need to be owner of all the gems at RubyGems, ask one of the owners to add you before releasing. (Try `gem owner decidim`).
-
-Remember to follow the Gitflow branching workflow.
-
-## Create the stable branch for the release
-
-1. Go to develop with `git checkout develop`
-1. Create the release branch `git checkout -b release/x.y.z-stable && git push origin release/x.y.z-stable`.
-1. If required, add the release branch to Crowdin so that any pending translations will generate a PR to this branch.
-
-Mark `develop` as the reference to the next release:
-
-1. Go back to develop with `git checkout develop`
-1. Turn develop into the `dev` branch for the next release:
-    1. Update `.decidim-version` to the new `dev` development version: `x.y.z.dev`, where `x.y.z` is the new semver number for the next version
-    1. Run `bin/rake update_versions`, this will update all references to the new version.
-    1. Run `bin/rake bundle`, this will update all the `Gemfile.lock` files
-    1. Run `bin/rake webpack`, this will update the JavaScript bundle.
-1. Update `SECURITY.md` and change the supported version to the new version.
-1. Update the `CHANGELOG.MD`. At the top you should have an `Unreleased` header with the `Added`, `Changed`, `Fixed` and `Removed` empty sections. After that, the header with the current version and link with the same beforementioned sections and a `Previous versions` header at the bottom that links to the previous minor release stable branch.
-
-  ```markdown
-  ## [Unreleased](https://github.com/decidim/decidim/tree/HEAD)
-
-  ### Added
-
-  ### Changed
-
-  ### Fixed
-
-  ### Removed
-
-  ## [v0.XX.0](https://github.com/decidim/decidim/releases/tag/v0.XX.0)
-
-  ### Added
-  ...
-
-  ## Previous versions
-
-  Please check [0.XX-stable](https://github.com/decidim/decidim/blob/release/0.XX-stable/CHANGELOG.md) for previous changes.
-  ```
-
-1. Push the changes `git add . && git commit -m "Bump develop to next release version" && git push origin develop`
-
-## Release Candidates
-
-Release Candidates are the same as beta versions. They should be ready to go to production, but publicly released just before in order to be widely tested.
-
-If this is a **Release Candidate version** release, the steps to follow are:
-
-1. Checkout the release stable branch `git checkout release/x.y-stable`.
-1. Update `.decidim-version` to the new version `x.y.z.rc1`
-1. Run `bin/rake update_versions`, this will update all references to the new version.
-1. Run `bin/rake bundle`, this will update all the `Gemfile.lock` files
-1. Run `bin/rake webpack`, this will update the JavaScript bundle.
-1. Commit all the changes: `git add . && git commit -m "Bump to rcXX version" && git push origin release/x.y-stable`.
-1. Tag the release candidate with `git tag vX.Y.Z.rcN && git push origin vX.Y.Z.rcN`.
-1. Usually, at this point, the release branch is deployed to meta-decidim during, at least, one week to validate the stability of the version.
-
-### During the validation period
-
-1. During the validation period, bugfixes must be implemented directly to the current `release/x.y.z-stable` branch and ported to `develop`.
-1. During the validation period, translations to the officially supported languages must be added to Crowdin and, when completed, merged into `release/x.y.z-stable`.
-
-## Major/Minor versions
-
-Release Candidates will be tested in a production server (usually meta-decidim) during some period of time (a week at least), when they are considered ready, it is time for them to be merged into `master`:
-
-1. Checkout the release stable branch `git checkout release/x.y-stable`.
-1. Update `.decidim-version` by removing the `.rcN` suffix, leaving a clean version number like `x.y.z`
-1. Run `bin/rake update_versions`, this will update all references to the new version.
-1. Run `bin/rake bundle`, this will update all the `Gemfile.lock` files
-1. Run `bin/rake webpack`, this will update the JavaScript bundle.
-1. Commit all the changes: `git add . && git commit -m "Bump to v0.XX.0 final version" && git push origin release/x.y-stable`.
-1. Create the PR for the new version.
-    1. `git checkout master && git checkout -b release/x.y.z`
-    1. `git merge release/x.y-stable`
-    1. `git checkout --theirs *`
-    1. `git checkout --theirs .github/* \.*`
-    1. Review changes in `CHANGELOG.md`, manually update and create a "changelog" commit if required.
-    1. `git push origin release/x.y.z`
-    1. Create the PR. The base for this PR should be `master`, but GitHub may crash if there are a lot of changes. As a workaround create the branch against `develop` and, when created, change the base to `master`.
-    1. Still don't merge it.
-1. Before merging the PR to upgrade `master`, check that the stable branch for the previous version exists. For instance, if we are going to release v0.22.0, there should be a `release/0.21-stable` branch in the repository. If such branch does not exists, it has to be created now, before merging the new release. So, if this is the release of v0.22.0, branch off `release/0.21-stable` from `master`. These stable branches will be able to receive bugfixes, backports and will be the origin of patch releases for older releases.
-1. Merge (after proper peer review) the PR to `master` and remove `release/x.y.z` branch.
-1. Run `git checkout master && bin/rake release_all`, this will create all the tags, push the commits and tags and release the gems to RubyGems.
-1. Once all the gems are published you should create a new release at this repository, just go to the [releases page](https://github.com/decidim/decidim/releases) and create a new one.
-1. Create the stable branch for the current version. From `master`: `git checkout -b release/x.y-stable && git push origin release/x.y-stable`.
-1. Update Decidim's Docker repository as explained in the Docker images section below.
-1. Update Crowdin synchronization configuration with Github:
-    1. Add the new `release/x.y-stable` branch.
-    1. Remove from Crowdin branches that are not officially supported anymore. That way they don't synchronize with Github.
-1. Update the `CHANGELOG.MD` in `release/x.y-stable`. At the top you should have an `Unreleased` header with the `Added`, `Changed`, `Fixed` and `Removed` empty sections. After that, the header with the current version. Add the `Unreleased` section or create the new current version section.
-
-## Releasing patch versions
-
-Releasing new versions from a ***release/x.y-stable*** branch is quite easy. The process is very similar from releasing a new Decidim version:
-
-1. Checkout the branch you want to release: `git checkout -b release/x.y-stable`
-1. Update `.decidim-version` to the new version number.
-1. Run `bin/rake update_versions`, this will update all references to the new version.
-1. Run `bin/rake bundle`, this will update all the `Gemfile.lock` files
-1. Run `bin/rake webpack`, this will update the JavaScript bundle.
-1. Update `CHANGELOG.MD`. At the top you should have an `Unreleased` header with the `Added`, `Changed`, `Fixed` and `Removed` empty sections. After that, the header with the current version and link like `## [0.20.0](https://github.com/decidim/decidim/tree/v0.20.0)` and again the headers for the `Added`, `Changed`, `Fixed` and `Removed` sections.
-1. Commit all the changes: `git add . && git commit -m "Prepare VERSION release"`
-1. Run `bin/rake release_all`, this will create all the tags, push the commits and tags and release the gems to RubyGems.
-1. Once all the gems are published you should create a new release at this repository, just go to the [releases page](https://github.com/decidim/decidim/releases) and create a new one.
-1. Update Decidim's Docker repository as explained in the Docker images section.
-
-## Docker images for each release
-
-1. After each release, you should update our [Docker repository](https://github.com/decidim/docker) so new images are build for the new release. To do it, just update `DECIDIM_VERSION` at [circle.yml](https://github.com/decidim/docker/blob/master/circle.yml).

data/docs/advanced/tradeoffs.md

@@ -1,14 +0,0 @@
-# Technical tradeoffs
-
-## Architecture
-
-This is not your typical Ruby on Rails Vanilla App. We've tried using [Consul](http://decide.es) but we found some problems on reutilization, adaptation, modularization and configuration. You can read more about that on "[Propuesta de Cambios de Arquitectura de Consul](https://www.gitbook.com/book/alabs/propuesta-de-cambios-en-la-arquitectura-de-consul/details)".
-
-## Turbolinks
-
-Decidim doesn't support `turbolinks` so it isn't included on our generated apps and it's removed for existing Rails applications which install the Decidim engine.
-
-The main reason is we are injecting some scripts into the body for some individual pages and Turbolinks loads the scripts in parallel. For some libraries like [leaflet](http://leafletjs.com/) it's very inconvenient because its plugins extend an existing global object.
-
-The support of Turbolinks was dropped in [d8c7d9f](https://github.com/decidim/decidim/commit/d8c7d9f63e4d75307e8f7a0360bef977fab209b6). If you're interested in bringing turbolinks back, further discussion is welcome.
-

data/docs/advanced/view_models_aka_cells.md

@@ -1,99 +0,0 @@
-# View Models (a.k.a. Cells)
-
-## General description
-
-A cell is an object that represent a fragment of your UI. The scope of that fragment can embrace an entire page, a single comment container in a thread or just an avatar image link.
-
-Cells are faster than ActionView. While exposing a better performance, you step-wise encapsulate fragments into cell widgets and enforce interfaces.
-
-### View Model
-
-Think of cells, or view models, as small Rails controllers, but without any HTTP coupling. Cells embrace all presentation and rendering logic to present a fragment of the UI.
-
-## Decidim Cards
-
-`card_for @instance` will render the corresponding default card for each component instance.
-If a card for the given resource is not registered, a _basic_ (default) card is shown.
-
-To render a specified size/variation include the `size` option as a `symbol`: `card_for @instance, size: :m`
-
-### Card M
-
-To render a label to identify the type of component renderized add to the `context` the `label` option.
-
-The `label` option accepts this arguments:
-
-- `false` or `"false"` will not render the label from the locales `t(model.class.model_name.i18n_key, scope: "activerecord.models", count: 1)`
-- `true` or `"true"` will render the translation from
-- `"whathever string"` will render it as String
-
-## Introducing a Card Cell to a `component`
-
-- add **dependency** to "decidim-*.gemspec"
-
-  ```rb
-  s.add_dependency "cells-erb", "~> 0.1.0"
-  s.add_dependency "cells-rails", "~> 0.0.9"
-  ```
-
-- **require** cells in `decidim-<module>/lib/decidim/<module>/engine.rb`
-
-  ```rb
-  require "cells/rails"
-  require "cells-erb"
-
-  initializer "decidim_<module>.add_cells_view_paths" do
-    Cell::ViewModel.view_paths << File.expand_path("#{Decidim::<Module>::Engine.root}/app/cells")
-    Cell::ViewModel.view_paths << File.expand_path("#{Decidim::<Module>::Engine.root}/app/views") # for partials
-  end
-  ```
-
-- The attribute `card` of the resource is defined in `decidim-core/lib/decidim/resource_manifest.rb`:
-
-  ```rb
-  # The cell to use to render the card of a resource.
-  attribute :card, String
-  ```
-
-  In your `decidim-<component>/lib/decidim/<component>/component.rb` register the resource and set the card value. Note that the model class for your resource must include the `Decidim::Resourceable` concern for this to work:
-
-  ```rb
-  component.register_resource(:<my_resource>) do |resource|
-    resource.class = "Decidim::<Component>/<MyResource>" # eg. "Decidim::Proposals::ProposalDraft
-    resource.card = "decidim/<component>/<my_resource>" # eg. "decidim/proposals/proposal_draft"
-    resource.component_manifest = component
-  end
-  ```
-
-  ```rb
-  module Decidim
-    module <Component>
-      class <MyResource> < Decidim::ApplicationRecord
-        include Decidim::Resourceable
-        # ...
-      end
-    end
-  end
-  ```
-
-- The **Cell Class**, following the convention, will reside in `decidim-<component>/app/cells/decidim/<component>/<my_resource>_cell.rb`:
-
-  ```rb
-  module Decidim
-    module <Component>s
-      class <MyResource>Cell < Decidim::ViewModel
-        def show
-          render # renders decidim-<component>/app/cells/decidim/<component>/<my_resource>
-        end
-      end
-    end
-  end
-  ```
-
-- The **Cell Views** will be in the `decidim-<component>/app/cells/decidim/<component>/<my_resource>` and defaults to `show.erb`
-
-## More Info
-
-- [cells/README.md at master · trailblazer/cells](https://github.com/trailblazer/cells/blob/master/README.md)
-- [Trailblazer: Cells](http://trailblazer.to/gems/cells/) / [Trailblazer: Cells API](http://trailblazer.to/gems/cells/api.html)
-- [Introduction to Cells: A Better View Layer for Rails — SitePoint](https://www.sitepoint.com/introduction-to-cells-a-better-view-layer-for-rails/)

data/docs/checklist.md

@@ -1,55 +0,0 @@
-# Checklist
-
-As a technopolitical project, Decidim needs several things to work. This is a non comprehensive list that serves as a general recommendation of what things you need to have it working with the best practices:
-
-## Technological
-
-1. Choose a **domain or subdomain** for your application. Some typical names involve "Participation" or "Decision" conjugations.
-
-1. Choose which **languages** do you want for your application. In case that your language isn't supported you should translate it on [Crowdin](https://crowdin.com/project/decidim).
-
-1. Customize the [**look and feel**](customization/styles.md) (colors, pictures, fonts, etc).
-
-1. Configure **SSL**. We recommend using at least [Let's Encrypt](https://letsencrypt.org/) for a minimum security. You should also check that there's an enforced redirection from HTTP to HTTPS on your web server.
-
-1. Configure your **SMTP** server.
-
-1. Setup the **geolocation** service. We recommend using [Here Maps](https://developer.here.com/), but you can use other kind of tiling server compatible with [Open Street Maps](https://www.openstreetmap.org/).
-
-1. Setup an **analytics** server. For better compliance with Decidim Social Contract, we recommend using [Matomo](https://matomo.org/).
-
-1. Setup **backup** on your server. The most important things to save are the `public/uploads` and the database.
-
-1. Decide and implement which kind of **[Authorization](customization/authorizations.md)** you're going to use.
-
-1. Comply with our License (Affero GPL 3) and **publish your code** to [GitHub](http://github.com) or wherever you want.
-
-1. Review your **decidim initializer** on your application (config/initializers/decidim.rb).
-
-1. Configure your [**ActiveJob**](services/activejob.md) background queue.
-
-1. If you want, configure your [**social providers**](services/social_providers.md) to enable login using external applications.
-
-1. Check that you don't have any **default users, emails and passwords**, neither on the admin or on the system panel.
-
-1. Configure recurring jobs for [**metrics**](advanced/metrics.md) and [**open data**](advanced/open-data.md)
-
-1. You should have a **staging** / preproduction environment where to test changes before deploying to production. If this environment has a copy of production database, you should disable the SMTP server and for privacy issues you should change the usernames / names / emails.
-
-1. You should have a **exception tracking** service or gem, like [Errbit](https://errbit.com/), [Exception Notification](https://github.com/smartinez87/exception_notification), [Airbrake](https://airbrake.io/) or [Sentry](https://sentry.io).
-
-## Contents
-
-1. Ideally you'll have a **Team** formed with experts on IT, Communication, Participation, Design and Law.
-
-1. Texts for at least, **terms of use, privacy policy and frequently asked questions**. To show the "Terms and conditions" body text in the "Sign Up Form", it is a requirement that the slug of this page to be equal `terms-and-conditions`.
-
-1. Comply with your current **legal requirements**, like to registrate your privacy policy with the autorities (eg LOPD on Spain).
-
-1. Fill the **Participatory Processes Configuration Form** to prepare your Participatory Process for Decidim.
-
-1. Read the **[Administration manual](https://decidim.org/docs/)**.
-
-1. Participate on **[MetaDecidim](http://meta.decidim.org)**.
-
-1. Read the Decidim **[Social Contract](https://decidim.org/contract/)**.

data/docs/customization/authorizations.md

@@ -1,5 +0,0 @@
-# Authorizations
-
-See [decidim-verifications's README][README].
-
-[README]: https://github.com/decidim/decidim/blob/master/decidim-verifications/README.md

data/docs/customization/images.md

@@ -1,7 +0,0 @@
-# Images
-
-You can change most of the images (for instance the logo, main banner on homepage, contents of participatory processes, etc) through the Administration panel.
-
-If you want to override the standard images given by Decidim (for instance the initial image for user’s avatars) you can do it by naming it the same way as the original image, in this case it should be `app/assets/images/decidim/default-avatar.svg`
-
-If you want to add a new image you can do it as any Rails application, leaving it on your image’s asset folder and using image_tag helper. You can see more documentation on [Rails guide](http://guides.rubyonrails.org/asset_pipeline.html).

data/docs/customization/javascript.md

@@ -1,9 +0,0 @@
-# Javascript
-
-If you want to add some custom Javascript code, just add it to app/assets/javascripts/application.js. For example to create a new alert just add:
-
-```javascript
-$(function(){
-  alert('foobar');
-});
-```

data/docs/customization/machine_translations.md

@@ -1,30 +0,0 @@
-# Using machine translations
-
-For multilingual organizations, Decidim includes a way to integrate with amachine translation service. The aim of this integration is to provide machine translations for any user-generated content.
-
-## Flow description
-
-Every time a user creates or updates a translatable resource (that is, an instance of a resource that implements the `Decidim::TranslatableResource` concern), this workflow is triggered:
-
-- A background job starts for the resource. This background job lists the fields that have been changed, and checks if any of the fields is considered translatable.
-- For each translatable field that is changed, it lists the locales that need to be translated.
-- For each combination field/locale a new job is fired.
-- This job calls the machine translation service, which will handle how to translate that given text.
-
-This workflow will only start if the machine translation service is configured in the installation, and the organization has the service enabled.
-
-## Enabling the integration, installation-wise
-
-This is an option in the Decidim initializer:
-
-```ruby
-config.enable_machine_translations = true
-config.machine_translation_service = "MyApp::MyOwnTranslationService"
-```
-
-The class will need to be implemented, or reuse one from the community. Check the docs on how to implement a machine translation service.
-
-## Enabling the integration, organization-wise
-
-Each organization will be able to enable/disable machine translations if they want to. They can do that from the organization configuration.
-

data/docs/customization/maps.md

@@ -1,610 +0,0 @@
-# Custom map providers
-
-Decidim can be configured to use multiple different
-[map service providers][link-docs-maps] but it can be also extended to use any
-possible service provider out there.
-
-If you want to create your own provider integration, you will need to find a
-service provider that provides all the following services:
-
-- [A geocoding server][link-wiki-geocoding] in order to turn user entered
-  addresses into [geocoordinates][link-wiki-geocoordinates].
-- [A geocoding autocompletion server][link-wiki-autocompletion] in order to
-  suggest and predict addresses based on the user input and turning these
-  suggested addresses into [geocoordinates][link-wiki-geocoordinates].
-- [A map tile server][link-wiki-tile-server] for the dynamic maps, preferrably
-  one that is compatible with the default [Leaflet][link-leaflet] map library.
-- [A static map image server][link-wiki-static-maps] for the static map images
-  e.g. on the proposal pages. This service is optional as Decidim will use the
-  dynamic map tiles to generate a similar map element if the static map image
-  cannot be provided.
-
-One option is to host some or all of these services yourself as there are open
-source alternatives available for all of these services. More information about
-self hosting is available at the
-[maps and geocoding configuration][link-docs-maps-multiple-providers]
-documentation.
-
-You may also decide to [disable some of the services][link-docs-maps-disable]
-that are not available at your service provider but in order to get the full out
-of Decidim, it is recommended to find a service provider with all these
-services.
-
-In case you want to use different service providers for the different categories
-of map services, that is also possible. Instructions for this are provided in
-the [maps and geocoding configuration][link-docs-maps-multiple-providers]
-documentation.
-
-## Creating your own map service provider
-
-First thing you will need is to define a service provider module which also
-defines all the services your provider is able to serve. An example service
-provider module looks as follows:
-
-```ruby
-module Decidim
-  module Map
-    module Provider
-      module Geocoding
-        autoload :YourProvider, "decidim/map/provider/geocoding/your_provider"
-      end
-      module Autocomplete
-        autoload :YourProvider, "decidim/map/provider/autocomplete/your_provider"
-      end
-      module DynamicMap
-        autoload :YourProvider, "decidim/map/provider/dynamic_map/your_provider"
-      end
-      module StaticMap
-        autoload :YourProvider, "decidim/map/provider/static_map/your_provider"
-      end
-    end
-  end
-end
-```
-
-Please note that you will need to place the utility classes for each category of
-services under the paths defined for the autoloading functionality.
-
-### Defining the geocoding utility
-
-For the geocoding functionality, Decidim uses the [Geocoder gem][link-geocoder]
-which does most of the heavy lifting. It is not necessary to use this gem but
-in case your target service is already integrated with that gem, it makes this
-step much easier for you. Take a look at the list of
-[supported geocoding APIs][link-geocoder-apis] for the Geocoder gem.
-
-In case your API is supported by the Geocoder gem, the only thing you need to do
-to create your geocoding utility is to create the following empty class:
-
-```ruby
-module Decidim
-  module Map
-    module Provider
-      module Geocoding
-        class YourProvider < ::Decidim::Map::Geocoding
-          # ... add your customizations here ...
-        end
-      end
-    end
-  end
-end
-```
-
-If the target service has some other "lookup handle" defined in the Geocoder gem
-than `:your_provider`, you may want to override the `handle` method in the
-geocoding utility's class you just defined. This is passed for the Geocoder gem
-as your lookup handle. An example of this can be seen in the
-[`Decidim::Map::Provider::Geocoding::Osm`][link-code-osm-geocoder] class which
-changes the handle to `:nominatim` instead of the default `:osm` which is not an
-existing lookup handle in the Geocoder gem.
-
-In case you want to customize the geocoding utility for your provider, you can
-define the following methods in the utility class:
-
-- `search(query, options = {})` - A common method for searching the geocoding
-  API and returning an array of results. The results array contains the Geocoder
-  gem's result objects of type
-  [`Geocoder::Result::Base`][link-code-geocoder-result] or the result type
-  specific to your API. If the first parameter is an address string, the method
-  does a forward geocoding request finding the closest matching coordinate pairs
-  for that address. If the first parameter is a coordinate pair array, the
-  method does a reverse geocoding request finding the closest matching addresses
-  for the search.
-- `coordinates(address, options = {})` - A method that searches the best
-  matching coordinates for the given address string. Only returns one coordinate
-  pair as an array.
-- `address(coordinates, options = {})` - A method that searches the best
-  matching address for the given coordinate pair array. Only returns one address
-  as a string.
-
-Customization may be needed if you are not happy with the default results
-returned by the Geocoder gem. For instance, in some occasions you might want to
-pass extra query options to the geocoding API or sort the results differently
-than what was returned by the API and what is already done in Decidim by
-default.
-
-In order to provide configuration options for the Geocoder gem's lookup, you can
-pass them directly through the maps configuration with the following syntax:
-
-```ruby
-config.maps = {
-  provider: :your_provider,
-  api_key: Rails.application.secrets.maps[:api_key],
-  geocoding: { extra_option: "value", another_option: "value" }
-}
-```
-
-This would equal to configuring the Geocoder gem with the following code:
-
-```ruby
-Geocoder.configure(
-  your_provider: {
-    api_key: Rails.application.secrets.maps[:api_key],
-    extra_option: "value",
-    another_option: "value"
-  }
-)
-```
-
-Each geocoding API may require their own configuration options. Please refer to
-the Geocoder gem's [supported geocoding APIs][link-geocoder-apis] documentation
-to find out the available options for your API.
-
-### Defining the geocoding autocompletion maps utility
-
-For the geocoding autocompletion map functionality, you should preferrably use
-a service provider that is compatible with [Photon][link-photon] which is
-already integrated with Decidim.
-
-If this is not possible, you can also create a custom geocoding autocompletion
-maps utility for your own service provider by defining the following empty class
-to start with:
-
-```ruby
-module Decidim
-  module Map
-    module Provider
-      module Autocomplete
-        class YourProvider < ::Decidim::Map::Autocomplete
-          # ... add your customizations here ...
-        end
-      end
-    end
-  end
-end
-```
-
-In case you want to customize the geocoding autocompletion map utility for your
-provider, you can define the following methods in the utility class:
-
-- `builder_class` - Returns a class for the geocoding autocompletion builder
-  that is used to create the input fields for the autocompleted addresses in the
-  front-end. By default, this would be
-  `Decidim::Map::Provider::Autocomplete::YourProvider::Builder` or if that is
-  not defined, defaults to `Decidim::Map::Autocomplete::Builder`. See below for
-  further notes about the builder class.
-- `builder_options` - A method that prepares the options for the builder
-  instance that is used to create the maps in the front-end. By default, this
-  is an empty hash that needs to be configured for each provider.
-
-To see an example how to customize the static map utility, take a look at the
-[HERE Maps geocoding autocomletion utility][link-code-here-autocomplete].
-
-In order to provide configuration options for the geocoding autocompletion, you
-can pass them directly through the maps configuration with the following syntax:
-
-```ruby
-config.maps = {
-  provider: :your_provider,
-  api_key: Rails.application.secrets.maps[:api_key],
-  autocomplete: {
-    url: "https://photon.example.org/api/"
-  }
-}
-```
-
-And then you can use these options in your provider utility as follows e.g. in
-the `builder_options` method:
-
-```ruby
-def builder_options
-  { url: configuration.fetch(:url, nil) }.compact
-end
-```
-
-You will also need to define a builder class inside your provider utility class
-as follows:
-
-```ruby
-module Decidim
-  module Map
-    module Provider
-      module Autocomplete
-        class Here < ::Decidim::Map::Autocomplete
-          # ... other customizations go gere ...
-
-          # This is the actual builder customization where you could define e.g.
-          # the JavaScript asset which is used to initialize the geocoding
-          # autocompletion functionality in the front-end:
-          class Builder < Decidim::Map::Autocomplete::Builder
-            def javascript_snippets
-              template.javascript_include_tag("decidim/geocoding/provider/your_provider")
-            end
-          end
-        end
-      end
-    end
-  end
-end
-```
-
-To see an example of the front-end JavaScript code that handles the geocoding
-requests, you can take a look at the
-[HERE Maps example][link-code-here-autocomplete-js]. You will have to listen to
-the `geocoder-suggest.decidim` JavaScript event on all elements that have the
-`data-decidim-geocoding` attribute defined which contains all the configurations
-returned by the builder's `builder_options` method as mentioned above. For
-example, if you passed the following configuration from that method:
-
-```js
-{ url: "https://photon.example.org/api/", other_config: "foo" }
-```
-
-This would be available in the JavaScript as follows:
-
-```js
-$(document).on("ready", () => {
-  $("[data-decidim-geocoding]").each((_i, el) => {
-    console.log($(el).data("decidim-geocoding"));
-    // => This would print out:
-    // {url: "https://photon.example.org/api/", otherConfig: "foo"}
-  });
-});
-```
-
-When you hook into the `geocoder-suggest.decidim` event on these methods, the
-event callback will be provided three arguments:
-
-- `event` - The event that you hooked into
-- `query` - The text to be queried, i.e. what the user entered into the input
-- `callback` - A callback method which you will need to call with your geocoding
-  autocompletion results once the request to the API has finished in the
-  front-end.
-
-The `callback` method expects one argument which is the array of result objects.
-The result objects need to contain the following keys:
-
-- `key` - The key which will be matched against the user entered input
-- `value` - The value which will be added to the address input if the user
-  decides to select this value
-
-Optionally, you can also include a `coordinates` key in the result object which
-contains an array of two cordinates (latitude and longitude respectively). You
-can also include any other data you might need in the front-end for these
-results but it will be not used by Decidim.
-
-The final code would look something like follows:
-
-```js
-$(document).on("ready", () => {
-  $("[data-decidim-geocoding]").each((_i, el) => {
-    const $input = $(el);
-    const config = $input.data("decidim-geocoding");
-
-    $input.on("geocoder-suggest.decidim", (event, query, callback) => {
-        currentSuggestionQuery = setTimeout(() => {
-          $.ajax({
-            method: "GET",
-            url: config.url,
-            data: { apiKey: config.apiKey },
-            dataType: "json"
-          }).done((resp) => {
-            if (resp.suggestions) {
-              return callback(resp.suggestions.map((item) => {
-                return {
-                  key: item.label,
-                  value: item.label,
-                  coordinates: [item.latitude, item.longitude],
-                  yourExtraData: item.yourExtraData
-                }
-              }));
-            }
-            return null;
-          });
-    });
-  });
-});
-```
-
-If your autocompletion API does not provide the coordinates information along
-with the autocompletion requests, you can hook into another event to do extra
-queries for the geocoordinates as follows:
-
-```js
-$(document).on("ready", () => {
-  $("geocoder-suggest-select.decidim", (ev, selectedItem) => {
-    console.log(selectedItem);
-    // => This would print out what you returned for the `callback` as shown
-    // above.
-
-    // NOTE: YOU DON'T NEED THIS IF YOUR RESPONSE OBJECTS ALREADY CONTAINED THE
-    //       COORDINATES IN THE `coordinates` KEY OF EACH RESULT OBJECT!
-    // Then, once you know the coordinates, you trigger the following event on
-    // the same input (obviously, you need to query the API first):
-    const coordinates = [1.123, 2.234];
-    $(ev.target).trigger("geocoder-suggest-coordinates.decidim", [coordinates]);
-  });
-});
-```
-
-Finally, if you want to pass these coordinates to the same form where your
-address field is located at, you can use the `Decidim.attachGeocoding()` method
-as follows:
-
-```js
-$(document).ready(function() {
-  Decidim.attachGeocoding($("#your_address_input"));
-});
-```
-
-Now the latitude and longitude coordinates would be passed to the same form
-where the address input is located at. For example, if the address input had the
-name `record[address]`, new hidden fields would be now generated for the
-geocoding autocomplete suggestion's coordinates with the following names:
-
-- `record[latitude]` for the latitude coordinate
-- `record[longitude]` for the longitude coordinate
-
-Then, you can read these values along with the form's POST data in order to
-store the coordinates for your records in the back-end. This is not 100%
-necessary but it improves the accuracy of the geocoding functionality and it
-also avoids unnecessary double requests to the geocoding API (front-end +
-back-end).
-
-### Defining the dynamic maps utility
-
-For the dynamic map functionality, you should primarily use a service provider
-that is compatible with the [Leaflet library][link-leaflet] that ships with
-Decidim. You can also integrate to services that are not compatible with Leaflet
-but it will cause you more work and is not covered by this guide.
-
-Please note that you don't necessarily even need to create your own dynamic maps
-utility if your service provider is already compatible with the
-[`Decidim::Map::Provider::DynamicMap::Osm`][link-code-osm-dynamic] provider. In
-order to configure your custom OSM compatible service provider take a look at
-the [maps and geocoding configuration][link-docs-maps-osm] documentation.
-
-If your service provider is not fully compatible with the default OSM provider,
-you can start writing your customizations by creating an empty dynamic map
-provider utility with the following code:
-
-```ruby
-module Decidim
-  module Map
-    module Provider
-      module DynamicMap
-        class YourProvider < ::Decidim::Map::DynamicMap
-          # ... add your customizations here ...
-        end
-      end
-    end
-  end
-end
-```
-
-In case you want to customize the dynamic map utility for your provider, you can
-define the following methods in the utility class:
-
-- `builder_class` - Returns a class for the dynamic map builder that is used
-  to create the maps in the front-end. By default, this would be
-  `Decidim::Map::Provider::DynamicMap::YourProvider::Builder` or if that is not
-  defined, defaults to `Decidim::Map::DynamicMap::Builder`. See below for
-  further notes about the builder class.
-- `builder_options` - A method that prepares the options for the builder
-  instance that is used to create the maps in the front-end. By default, this
-  prepares the tile layer configurations for the Leaflet map.
-
-In addition, you may want to customize the Builder class in case you are not
-happy with the default dynamic map builder functionality. To see an example how
-to customize the builder, take a look at the
-[HERE Maps builder class][link-code-here-dynamic]. Please note that the custom
-dynamic map builder needs to extend the
-[`Decidim::Map::DynamicMap::Builder`][link-code-dynamic-map] class as you can
-also see from the HERE Maps example.
-
-The builder class works directly with the view layer and can refer to the view
-in question or any methods available for the view using the `template` object
-inside the builder. You may be already familiar with a similar builder concept
-if you have ever used the [Rails Form Builder][link-rails-form-builder].
-
-In order to provide configuration options for the dynamic maps, you can pass
-them directly through the maps configuration with the following syntax:
-
-```ruby
-config.maps = {
-  provider: :your_provider,
-  api_key: Rails.application.secrets.maps[:api_key],
-  dynamic: {
-    tile_layer: {
-      url: "https://tiles.example.org/{z}/{x}/{y}.png?key={apiKey}&{foo}&style={style}",
-      api_key: true,
-      foo: "bar=baz",
-      style: "bright-style",
-      attribution: %{
-        <a href="https://www.openstreetmap.org/copyright" target="_blank">&copy; OpenStreetMap</a> contributors
-      }.strip
-    }
-  }
-}
-```
-
-This will cause the following options to be available for the builder instance
-by default:
-
-```ruby
-{
-  tile_layer: {
-    url: "https://tiles.example.org/{z}/{x}/{y}.png?key={apiKey}&{foo}&style={style}",
-    configuration: {
-      api_key: Rails.application.secrets.maps[:api_key],
-      foo: "bar=baz",
-      style: "bright",
-      attribution: %{
-        <a href="https://www.openstreetmap.org/copyright" target="_blank">&copy; OpenStreetMap</a> contributors
-      }.strip
-    }
-  }
-}
-```
-
-And by default, this will cause the Leaflet tile layer to be configured as
-follows:
-
-```js
-L.tileLayer(
-  "https://tiles.example.org/{z}/{x}/{y}.png?key={apiKey}&{foo}&style={style}",
-  {
-    apiKey: "your_secret_key",
-    foo: "bar=baz",
-    style: "bright",
-    attribution: '<a href="https://www.openstreetmap.org/copyright" target="_blank">&copy; OpenStreetMap</a> contributors'
-  }
-).addTo(map);
-```
-
-### Defining the static maps utility
-
-For the static map functionality, you should preferrably use a service provider
-that is compatible with [osm-static-maps][link-osm-static-maps] which is already
-integrated with Decidim.
-
-If this is not possible, you can also create a custom static maps utility for
-your own service provider by defining the following empty class to start with:
-
-```ruby
-module Decidim
-  module Map
-    module Provider
-      module StaticMap
-        class YourProvider < ::Decidim::Map::StaticMap
-          # ... add your customizations here ...
-        end
-      end
-    end
-  end
-end
-```
-
-If you want to use dynamic map elements for the static maps as well, you can
-leave the static map utility empty as shown above. Decidim will create a dynamic
-map replacement for the static map image in case the static map utility will not
-return a proper map URL.
-
-In case you want to customize the static map utility for your provider, you can
-define the following methods in the utility class:
-
-- `link(latitude:, longitude:, options: {})` - Returns a link for the given
-  geographic location where the static map image is linked to. By default, this
-  will return a link to www.openstreetmap.org.
-- `url(latitude:, longitude:, options: {})` - Returns a URL for loading the
-  static map image from the service provider. By default, this will return a
-  link to the configured static map URL with the following URL query parameters:
-  - `latitude` - The value for the `latitude` option provided for the method.
-  - `longitude` - The value for the `longitude` option provided for the method.
-  - `zoom` - The value for key `:zoom` in the options hash (default: 15).
-  - `width` - The value for key `:width` in the options hash (default: 120).
-  - `height` - The value for key `:height` in the options hash (default: 120).
-- `url_params(latitude:, longitude:, options: {})` - Returns a hash of prepared
-  URL parameters for the `url` method. For the default parameters, see the
-  explanations above for the `url` method.
-- `image_data(latitude:, longitude:, options: {})` - Does a request to the URL
-  defined by the `url` method and returns the raw binary data in the response
-  body of that request. This data will be cached by Decidim once fetched from
-  the API to speed up further displays of the same static map.
-
-To see an example how to customize the static map utility, take a look at the
-[HERE Maps static map utility][link-code-here-static].
-
-In order to provide configuration options for the static maps, you can pass them
-directly through the maps configuration with the following syntax:
-
-```ruby
-config.maps = {
-  provider: :your_provider,
-  api_key: Rails.application.secrets.maps[:api_key],
-  static: {
-    url: "https://staticmap.example.org/",
-    foo: "bar",
-    style: "bright"
-  }
-}
-```
-
-And then you can use these options in your provider utility as follows e.g. in
-the `url_params` method:
-
-```ruby
-def url_params(latitude:, longitude:, options: {})
-  super.merge(
-    style: configuration.fetch(:style, "dark"),
-    foo: configuration.fetch(:foo, "baz")
-  )
-end
-```
-
-When calling the `url` method with the latitude of `1.123` and longitude of
-`2.456`, the utility would now generate the following URL with these
-configurations and customizations:
-
-```bash
-https://staticmap.example.org/?latitude=1.123&longitude=2.456&zoom=15&width=120&height=120&style=bright&foo=bar
-```
-
-If you want to use the dynamic map replacements for the static map images, do
-not configure `static` section for your maps:
-
-```ruby
-config.maps = {
-  provider: :your_provider,
-  api_key: Rails.application.secrets.maps[:api_key]
-  # static: { ... } # LEAVE THIS OUT
-}
-```
-
-Even if you decide to use the dynamic map replacements, you will still need to
-define the static map utility because it is used to generate the link where
-users will be pointed at when they click the map image. In this case, the static
-map utility can be empty as you won't need any customization for it to work.
-
-## Configuring your own map service provider
-
-After you have finished all the steps shown above, you will need to configure
-your service provider for Decidim. The configuration key for the example service
-provider referred to in this documentation would be `:your_provider`. For
-configuration, refer to the [maps and geocoding configuration][link-docs-maps]
-documentation.
-
-[link-code-dynamic-map]: /decidim-core/lib/decidim/map/dynamic_map.rb
-[link-code-geocoder-result]: https://github.com/alexreisner/geocoder/blob/master/lib/geocoder/results/base.rb
-[link-code-here-autocomplete]: /decidim-core/lib/decidim/map/provider/autocomplete/here.rb
-[link-code-here-autocomplete-js]: /decidim-core/app/assets/javascripts/decidim/geocoding/provider/here.js.es6
-[link-code-here-dynamic]: /decidim-core/lib/decidim/map/provider/dynamic_map/here.rb
-[link-code-here-static]: /decidim-core/lib/decidim/map/provider/static_map/here.rb
-[link-code-osm-dynamic]: /decidim-core/lib/decidim/map/provider/dynamic_map/osm.rb
-[link-code-osm-geocoder]: /decidim-core/lib/decidim/map/provider/geocoding/osm.rb
-[link-docs-maps]: /docs/services/maps.md
-[link-docs-maps-disable]: /docs/services/maps.md#disabling
-[link-docs-maps-osm]: /docs/services/maps.md#configuring-open-street-maps-based-service-providers
-[link-docs-maps-multiple-providers]: /docs/services/maps.md#combining-multiple-service-providers
-[link-geocoder]: https://github.com/alexreisner/geocoder
-[link-geocoder-apis]: https://github.com/alexreisner/geocoder/blob/master/README_API_GUIDE.md
-[link-leaflet]: https://leafletjs.com/
-[link-osm-static-maps]: https://github.com/jperelli/osm-static-maps
-[link-photon]: https://github.com/komoot/photon
-[link-rails-form-builder]: https://guides.rubyonrails.org/form_helpers.html#customizing-form-builders
-[link-wiki-autocompletion]: https://en.wikipedia.org/wiki/Autocomplete
-[link-wiki-geocoding]: https://en.wikipedia.org/wiki/Geocoding
-[link-wiki-geocoordinates]: https://en.wikipedia.org/wiki/Geographic_coordinate_system
-[link-wiki-map-tiles]: https://wiki.openstreetmap.org/wiki/Tiles
-[link-wiki-static-maps]: https://wiki.openstreetmap.org/wiki/Static_map_images
-[link-wiki-tile-server]: https://en.wikipedia.org/wiki/Tile_Map_Service