decidim 0.20.1 → 0.23.1

data/docs/advanced/permissions.md

@@ -0,0 +1,23 @@
+# 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/profiling.md

@@ -0,0 +1,43 @@
+# How to profile a Decidim app
+
+The developmen_app includes a bunch of gems that profile the application. Run the following command in the decidim root's folder:
+
+```bash
+bundle exec rake development_app
+```
+
+and then move into it and boot the server
+
+```bash
+cd developmen_app
+bundle exec rails s
+```
+
+## Bullet
+
+Bullet detects N+1 queries and suggests how to fix them, although it doesn't catch them all. It's currently configured in `config/initializers/bullet.rb` to log in the regular rails log and also in its own `log/bullet.log`. You'll now see entries like the following:
+
+```bash
+user: xxx
+GET /
+USE eager loading detected
+  Decidim::Comments::Comment => [:author]
+  Add to your query: .includes([:author])
+Call stack
+```
+
+It also warns you when there's an unnecessary eager load.
+
+More details: https://github.com/flyerhzm/bullet
+
+## Rack-mini-profiler
+
+This gem can analyze memory, database, and call stack with flamegraphs. It will show up in development on the top left corner and it gives you all sorts of profiling insights about that page. It'll tell you where the response time was spend on in the call stack.
+
+This gem is further enhanced with the `flamegraph`, `stackprof` and `memory_profiler` gems which provide more detailed analysis. Try out by appending `?pp=flamegraph`, `?pp=profile-gc` or `?pp=analyze-memory` to the URL. You can read more about these options at https://github.com/MiniProfiler/rack-mini-profiler#flamegraphs.
+
+More details: https://github.com/MiniProfiler/rack-mini-profiler
+
+## Profiling best practices
+
+You need to take the insights of these gems with a grain of salt though, if you run this in development. Rails' development settings have nothing to do with a production set up where classes are not reloaded and assets are precompiled and served from a web server. Therefore, you should mimic these settings as much as possible if you want your findings to be realistic.

data/docs/advanced/releases.md

@@ -0,0 +1,114 @@
+# 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/share_tokens.md

@@ -0,0 +1,53 @@
+# Share tokens
+
+Share tokens can be assigned to any model to provide a system to share unpublished resources with expirable and manageable tokens.
+
+A share token is created by a user with an expiration time, and can be added as a query param to access otherwise restricted locations.
+
+## Add share tokens to a model
+
+The model must `include Decidim::ShareableWithToken` and implement `shareable_url(share_token)`, which should return the public url for the resource you want to share, including the token as a query parameter.
+
+```ruby
+# Public: Public URL for your_resource with given share token as query parameter
+def shareable_url(share_token)
+  your_resource_public_path(self, share_token: share_token.token)
+end
+```
+
+## Set permissions
+
+You should change permissions logic for the resource to check if there's a `share_token` query parameter in the request url, and call `Decidim::ShareToken.use!` to both check if the token is valid, and if it is, to *use it* (which increments `times_used` variable and sets `last_used_at` to current time).
+
+It should do something similar to this:
+
+```ruby
+token = context[:share_token]
+
+return unless token.present?
+
+allow! if Decidim::ShareToken.use!(token_for: your_resource, token: token)
+```
+
+## Manage tokens
+
+Render the partial `decidim-admin/app/views/decidim/admin/share_tokens/_share_tokens.html.erb` inside a view, with:
+
+```ruby
+locals: { share_tokens: your_share_tokens_variable }
+```
+
+to let admins see and manage tokens for that resource.
+
+## Link to url with token
+
+Implement a `share` action (see below) in the resource controller (admin scope), redirecting to a url with a newly generated token, so you can call `share_my_resource_url`.
+
+```ruby
+def share
+  @your_resource = YourResource.find(params[:id]) # or whatever
+  share_token = @your_resource.share_tokens.create!(user: current_user, organization: current_organization)
+
+  redirect_to share_token.url
+end
+```

data/docs/advanced/templates.md

@@ -0,0 +1,56 @@
+# Templates
+
+Templates can be defined from their own section in the admin panel to store and use objects with given values and use them to create new ones using these values as default.
+
+## Model
+
+The only requisite to create a template for a model is that the model class includes the `Decidim::Templates::Templatable` concern.
+
+## Controller
+
+A controller must be created in `decidim-templates/app/controllers/decidim/templates/admin` for the template management actions: `index`, `new`, `create`, `edit`, `update`, `delete` and the additional `copy`, `apply`, `skip` and `preview` actions.
+
+## Commands
+
+You should create at least the custom `create`, `copy` and `apply` commands for the model templates in `decidim-templates/app/commands/decidim/templates/admin`, and can use the general `destroy` and `update` commands in the controller, which need to be called only with the `Template` itself.
+
+## Routes
+
+The following routes should be defined in `decidim-templates/lib/decidim/templates/admin_engine.rb`.
+
+```ruby
+resources :$MODEL_templates do
+  member do
+    post :copy
+
+    resource :$MODEL, module: :$MODEL_templates # To manage the templatable resource
+  end
+
+  collection do
+    post :apply # To use when creating an object from a template
+    post :skip # To use when creating an object without a template
+    get :preview # To provide a preview for the template in the object creation view
+  end
+end
+```
+
+## Views
+
+All views related to a model's template management must be created inside `decidim-templates/app/views/decidim/templates/admin/$MODEL_templates`.
+
+## Testing
+
+The factory for a specific model's template should be defined in `decidim-templates/lib/decidim/templates/test/factories.rb`, inside the general `:template` factory.
+
+## Other
+
+Add the route to the model templates index inside `decidim-templates/app/controllers/decidim/templates/admin/application_controller.rb`, providing the title and the index root.
+
+```ruby
+def template_types
+  @template_types ||= {
+    I18n.t("template_types.questionnaires", scope: "decidim.templates") => decidim_admin_templates.questionnaire_templates_path,
+    I18n.t("template_types.$MODEL_PLURAL", scope: "decidim.templates") => decidim_admin_templates.$MODEL_templates_path,
+  }
+end
+```

data/docs/advanced/testing.md

@@ -11,11 +11,14 @@ bundle exec rake test_app
 ## Running a specific test file or just a single spec
 
 If you are writing new specs, you can run the tests contained in a single file by opening a console window in the corresponding module and calling `rspec`on the file. For example:
+
 ```bash
 cd decidim-participatory_processes
 bundle exec rspec spec/forms/participatory_process_form_spec.rb
 ```
+
 You can also run a single test by appending its start line number to the command:
+
 ```bash
 bundle exec rspec spec/forms/participatory_process_form_spec.rb:134
 ```

data/docs/customization/machine_translations.md

@@ -0,0 +1,30 @@
+# 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

@@ -0,0 +1,610 @@
+# 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