decidim 0.23.6 → 0.24.0.rc1

Sign up to get free protection for your applications and to get access to all the features.

Potentially problematic release.


This version of decidim might be problematic. Click here for more details.

Files changed (114) hide show
  1. checksums.yaml +4 -4
  2. data/Rakefile +1 -0
  3. data/docs/README.adoc +74 -0
  4. data/docs/antora.yml +7 -0
  5. data/docs/modules/configure/pages/environment_variables.adoc +69 -0
  6. data/docs/modules/configure/pages/index.adoc +16 -0
  7. data/docs/modules/configure/pages/initializer.adoc +376 -0
  8. data/docs/modules/customize/assets/images/header-snippet.png +0 -0
  9. data/docs/modules/customize/assets/images/menu.png +0 -0
  10. data/docs/modules/customize/assets/images/organization-colors.png +0 -0
  11. data/docs/modules/customize/pages/authorizations.adoc +22 -0
  12. data/docs/{customization/code.md → modules/customize/pages/code.adoc} +12 -9
  13. data/docs/{customization/gemfile.md → modules/customize/pages/gemfile.adoc} +5 -4
  14. data/docs/modules/customize/pages/images.adoc +7 -0
  15. data/docs/modules/customize/pages/javascript.adoc +59 -0
  16. data/docs/modules/customize/pages/menu.adoc +25 -0
  17. data/docs/modules/customize/pages/oauth.adoc +33 -0
  18. data/docs/modules/customize/pages/styles.adoc +64 -0
  19. data/docs/modules/customize/pages/texts.adoc +30 -0
  20. data/docs/modules/customize/pages/users_registration_mode.adoc +17 -0
  21. data/docs/{customization/views.md → modules/customize/pages/views.adoc} +13 -13
  22. data/docs/modules/develop/assets/images/barcelona.png +0 -0
  23. data/docs/modules/develop/assets/images/helsinki.png +0 -0
  24. data/docs/modules/develop/assets/images/indices.png +0 -0
  25. data/docs/{advanced/api.md → modules/develop/pages/api.adoc} +2 -2
  26. data/docs/{advanced/authorship.md → modules/develop/pages/authorable.adoc} +5 -5
  27. data/docs/modules/develop/pages/c4_component.adoc +91 -0
  28. data/docs/modules/develop/pages/c4_container.adoc +42 -0
  29. data/docs/modules/develop/pages/c4_context.adoc +35 -0
  30. data/docs/{advanced/components.md → modules/develop/pages/components.adoc} +47 -10
  31. data/docs/{advanced/content_blocks.md → modules/develop/pages/content_blocks.adoc} +16 -13
  32. data/docs/{advanced/content_processors.md → modules/develop/pages/content_processors.adoc} +25 -19
  33. data/docs/modules/develop/pages/data-picker.adoc +85 -0
  34. data/docs/modules/develop/pages/deploy.adoc +15 -0
  35. data/docs/modules/develop/pages/docker.adoc +12 -0
  36. data/docs/{advanced/embeddable.md → modules/develop/pages/embeddable.adoc} +6 -6
  37. data/docs/{advanced/endorsable.md → modules/develop/pages/endorsable.adoc} +31 -25
  38. data/docs/{advanced/fixing_locales.md → modules/develop/pages/fixing_locales.adoc} +36 -23
  39. data/docs/{advanced/followers.md → modules/develop/pages/followable.adoc} +9 -8
  40. data/docs/modules/develop/pages/guide.adoc +16 -0
  41. data/docs/modules/develop/pages/guide_architecture.adoc +17 -0
  42. data/docs/modules/develop/pages/guide_changelog.adoc +8 -0
  43. data/docs/modules/develop/pages/guide_commands.adoc +86 -0
  44. data/docs/modules/develop/pages/guide_development_app.adoc +44 -0
  45. data/docs/modules/develop/pages/guide_development_with_custom_seed_data.adoc +31 -0
  46. data/docs/modules/develop/pages/guide_development_with_localhost_ssl.adoc +63 -0
  47. data/docs/modules/develop/pages/guide_example_apps.adoc +59 -0
  48. data/docs/modules/develop/pages/guide_git_conventions.adoc +75 -0
  49. data/docs/modules/develop/pages/guide_github_projects.adoc +42 -0
  50. data/docs/modules/develop/pages/guide_semver.adoc +7 -0
  51. data/docs/{advanced/how_to_fix_metrics.md → modules/develop/pages/how_to_fix_metrics.adoc} +76 -59
  52. data/docs/modules/develop/pages/machine_translations.adoc +42 -0
  53. data/docs/modules/develop/pages/managing_translations_i18n.adoc +24 -0
  54. data/docs/modules/develop/pages/maps.adoc +499 -0
  55. data/docs/modules/develop/pages/metrics.adoc +119 -0
  56. data/docs/{advanced/modules.md → modules/develop/pages/modules.adoc} +16 -6
  57. data/docs/{advanced/newsletter_templates.md → modules/develop/pages/newsletter_templates.adoc} +12 -10
  58. data/docs/{advanced/notifications.md → modules/develop/pages/notifications.adoc} +40 -38
  59. data/docs/{advanced/open-data.md → modules/develop/pages/open-data.adoc} +4 -3
  60. data/docs/modules/develop/pages/permissions.adoc +92 -0
  61. data/docs/{advanced/profiling.md → modules/develop/pages/profiling.adoc} +15 -12
  62. data/docs/modules/develop/pages/releases.adoc +148 -0
  63. data/docs/modules/develop/pages/reportable.adoc +31 -0
  64. data/docs/modules/develop/pages/security.adoc +33 -0
  65. data/docs/{advanced/share_tokens.md → modules/develop/pages/share_tokens.adoc} +18 -14
  66. data/docs/{advanced/templates.md → modules/develop/pages/templates.adoc} +14 -12
  67. data/docs/{advanced/testing.md → modules/develop/pages/testing.adoc} +21 -20
  68. data/docs/{advanced/activity_log.md → modules/develop/pages/traceable.adoc} +31 -26
  69. data/docs/modules/develop/pages/turbolinks.adoc +7 -0
  70. data/docs/{advanced/view_hooks.md → modules/develop/pages/view_hooks.adoc} +29 -23
  71. data/docs/modules/develop/pages/view_models_aka_cells.adoc +105 -0
  72. data/docs/modules/install/pages/checklist.adoc +39 -0
  73. data/docs/modules/install/pages/index.adoc +148 -0
  74. data/docs/{manual-installation.md → modules/install/pages/manual.adoc} +54 -42
  75. data/docs/modules/install/pages/update.adoc +95 -0
  76. data/docs/{services/activejob.md → modules/services/pages/activejob.adoc} +3 -3
  77. data/docs/modules/services/pages/elections_bulletin_board.adoc +52 -0
  78. data/docs/{services/etherpad.md → modules/services/pages/etherpad.adoc} +15 -12
  79. data/docs/modules/services/pages/maps.adoc +311 -0
  80. data/docs/modules/services/pages/smtp.adoc +10 -0
  81. data/docs/modules/services/pages/social_providers.adoc +122 -0
  82. data/lib/decidim/gem_manager.rb +5 -5
  83. data/lib/decidim/version.rb +1 -1
  84. metadata +137 -100
  85. data/README.md +0 -157
  86. data/docs/advanced/add_authorizable_action.md +0 -63
  87. data/docs/advanced/adding_fixtures_aka_dummy_content.md +0 -9
  88. data/docs/advanced/data-picker.md +0 -83
  89. data/docs/advanced/deploy.md +0 -9
  90. data/docs/advanced/how_to_create_a_module.md +0 -9
  91. data/docs/advanced/machine_translation_service.md +0 -12
  92. data/docs/advanced/managing_translations_i18n.md +0 -24
  93. data/docs/advanced/metrics.md +0 -114
  94. data/docs/advanced/permissions.md +0 -23
  95. data/docs/advanced/releases.md +0 -114
  96. data/docs/advanced/tradeoffs.md +0 -14
  97. data/docs/advanced/view_models_aka_cells.md +0 -99
  98. data/docs/checklist.md +0 -55
  99. data/docs/customization/authorizations.md +0 -5
  100. data/docs/customization/images.md +0 -7
  101. data/docs/customization/javascript.md +0 -9
  102. data/docs/customization/machine_translations.md +0 -30
  103. data/docs/customization/maps.md +0 -610
  104. data/docs/customization/oauth.md +0 -50
  105. data/docs/customization/styles.md +0 -11
  106. data/docs/customization/texts.md +0 -27
  107. data/docs/customization/users_registration_mode.md +0 -17
  108. data/docs/development_guide.md +0 -166
  109. data/docs/getting_started.md +0 -191
  110. data/docs/possible_flows_for_proposal.png +0 -0
  111. data/docs/services/analytics.md +0 -23
  112. data/docs/services/elections_bulletin_board.md +0 -38
  113. data/docs/services/maps.md +0 -362
  114. data/docs/services/social_providers.md +0 -98
@@ -1,23 +0,0 @@
1
- # Permissions
2
-
3
- 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.
4
-
5
- ## Overview
6
-
7
- When checking for permission to perform an action, we check this chain:
8
-
9
- 1. The component permissions
10
- 1. The participatory space permissions
11
- 1. The core permissions
12
-
13
- This way we're going from more specific to more general.
14
-
15
- ## Explanation
16
-
17
- 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).
18
-
19
- 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.
20
-
21
- 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.
22
-
23
- 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.
@@ -1,114 +0,0 @@
1
- # Releasing new versions
2
-
3
- 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`).
4
-
5
- Remember to follow the Gitflow branching workflow.
6
-
7
- ## Create the stable branch for the release
8
-
9
- 1. Go to develop with `git checkout develop`
10
- 1. Create the release branch `git checkout -b release/x.y.z-stable && git push origin release/x.y.z-stable`.
11
- 1. If required, add the release branch to Crowdin so that any pending translations will generate a PR to this branch.
12
-
13
- Mark `develop` as the reference to the next release:
14
-
15
- 1. Go back to develop with `git checkout develop`
16
- 1. Turn develop into the `dev` branch for the next release:
17
- 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
18
- 1. Run `bin/rake update_versions`, this will update all references to the new version.
19
- 1. Run `bin/rake bundle`, this will update all the `Gemfile.lock` files
20
- 1. Run `bin/rake webpack`, this will update the JavaScript bundle.
21
- 1. Update `SECURITY.md` and change the supported version to the new version.
22
- 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.
23
-
24
- ```markdown
25
- ## [Unreleased](https://github.com/decidim/decidim/tree/HEAD)
26
-
27
- ### Added
28
-
29
- ### Changed
30
-
31
- ### Fixed
32
-
33
- ### Removed
34
-
35
- ## [v0.XX.0](https://github.com/decidim/decidim/releases/tag/v0.XX.0)
36
-
37
- ### Added
38
- ...
39
-
40
- ## Previous versions
41
-
42
- Please check [0.XX-stable](https://github.com/decidim/decidim/blob/release/0.XX-stable/CHANGELOG.md) for previous changes.
43
- ```
44
-
45
- 1. Push the changes `git add . && git commit -m "Bump develop to next release version" && git push origin develop`
46
-
47
- ## Release Candidates
48
-
49
- 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.
50
-
51
- If this is a **Release Candidate version** release, the steps to follow are:
52
-
53
- 1. Checkout the release stable branch `git checkout release/x.y-stable`.
54
- 1. Update `.decidim-version` to the new version `x.y.z.rc1`
55
- 1. Run `bin/rake update_versions`, this will update all references to the new version.
56
- 1. Run `bin/rake bundle`, this will update all the `Gemfile.lock` files
57
- 1. Run `bin/rake webpack`, this will update the JavaScript bundle.
58
- 1. Commit all the changes: `git add . && git commit -m "Bump to rcXX version" && git push origin release/x.y-stable`.
59
- 1. Tag the release candidate with `git tag vX.Y.Z.rcN && git push origin vX.Y.Z.rcN`.
60
- 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.
61
-
62
- ### During the validation period
63
-
64
- 1. During the validation period, bugfixes must be implemented directly to the current `release/x.y.z-stable` branch and ported to `develop`.
65
- 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`.
66
-
67
- ## Major/Minor versions
68
-
69
- 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`:
70
-
71
- 1. Checkout the release stable branch `git checkout release/x.y-stable`.
72
- 1. Update `.decidim-version` by removing the `.rcN` suffix, leaving a clean version number like `x.y.z`
73
- 1. Run `bin/rake update_versions`, this will update all references to the new version.
74
- 1. Run `bin/rake bundle`, this will update all the `Gemfile.lock` files
75
- 1. Run `bin/rake webpack`, this will update the JavaScript bundle.
76
- 1. Commit all the changes: `git add . && git commit -m "Bump to v0.XX.0 final version" && git push origin release/x.y-stable`.
77
- 1. Create the PR for the new version.
78
- 1. `git checkout master && git checkout -b release/x.y.z`
79
- 1. `git merge release/x.y-stable`
80
- 1. `git checkout --theirs *`
81
- 1. `git checkout --theirs .github/* \.*`
82
- 1. Review changes in `CHANGELOG.md`, manually update and create a "changelog" commit if required.
83
- 1. `git push origin release/x.y.z`
84
- 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`.
85
- 1. Still don't merge it.
86
- 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.
87
- 1. Merge (after proper peer review) the PR to `master` and remove `release/x.y.z` branch.
88
- 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.
89
- 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.
90
- 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`.
91
- 1. Update Decidim's Docker repository as explained in the Docker images section below.
92
- 1. Update Crowdin synchronization configuration with Github:
93
- 1. Add the new `release/x.y-stable` branch.
94
- 1. Remove from Crowdin branches that are not officially supported anymore. That way they don't synchronize with Github.
95
- 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.
96
-
97
- ## Releasing patch versions
98
-
99
- Releasing new versions from a ***release/x.y-stable*** branch is quite easy. The process is very similar from releasing a new Decidim version:
100
-
101
- 1. Checkout the branch you want to release: `git checkout -b release/x.y-stable`
102
- 1. Update `.decidim-version` to the new version number.
103
- 1. Run `bin/rake update_versions`, this will update all references to the new version.
104
- 1. Run `bin/rake bundle`, this will update all the `Gemfile.lock` files
105
- 1. Run `bin/rake webpack`, this will update the JavaScript bundle.
106
- 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.
107
- 1. Commit all the changes: `git add . && git commit -m "Prepare VERSION release"`
108
- 1. Run `bin/rake release_all`, this will create all the tags, push the commits and tags and release the gems to RubyGems.
109
- 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.
110
- 1. Update Decidim's Docker repository as explained in the Docker images section.
111
-
112
- ## Docker images for each release
113
-
114
- 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).
@@ -1,14 +0,0 @@
1
- # Technical tradeoffs
2
-
3
- ## Architecture
4
-
5
- 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)".
6
-
7
- ## Turbolinks
8
-
9
- 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.
10
-
11
- 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.
12
-
13
- 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.
14
-
@@ -1,99 +0,0 @@
1
- # View Models (a.k.a. Cells)
2
-
3
- ## General description
4
-
5
- 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.
6
-
7
- Cells are faster than ActionView. While exposing a better performance, you step-wise encapsulate fragments into cell widgets and enforce interfaces.
8
-
9
- ### View Model
10
-
11
- 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.
12
-
13
- ## Decidim Cards
14
-
15
- `card_for @instance` will render the corresponding default card for each component instance.
16
- If a card for the given resource is not registered, a _basic_ (default) card is shown.
17
-
18
- To render a specified size/variation include the `size` option as a `symbol`: `card_for @instance, size: :m`
19
-
20
- ### Card M
21
-
22
- To render a label to identify the type of component renderized add to the `context` the `label` option.
23
-
24
- The `label` option accepts this arguments:
25
-
26
- - `false` or `"false"` will not render the label from the locales `t(model.class.model_name.i18n_key, scope: "activerecord.models", count: 1)`
27
- - `true` or `"true"` will render the translation from
28
- - `"whathever string"` will render it as String
29
-
30
- ## Introducing a Card Cell to a `component`
31
-
32
- - add **dependency** to "decidim-*.gemspec"
33
-
34
- ```rb
35
- s.add_dependency "cells-erb", "~> 0.1.0"
36
- s.add_dependency "cells-rails", "~> 0.0.9"
37
- ```
38
-
39
- - **require** cells in `decidim-<module>/lib/decidim/<module>/engine.rb`
40
-
41
- ```rb
42
- require "cells/rails"
43
- require "cells-erb"
44
-
45
- initializer "decidim_<module>.add_cells_view_paths" do
46
- Cell::ViewModel.view_paths << File.expand_path("#{Decidim::<Module>::Engine.root}/app/cells")
47
- Cell::ViewModel.view_paths << File.expand_path("#{Decidim::<Module>::Engine.root}/app/views") # for partials
48
- end
49
- ```
50
-
51
- - The attribute `card` of the resource is defined in `decidim-core/lib/decidim/resource_manifest.rb`:
52
-
53
- ```rb
54
- # The cell to use to render the card of a resource.
55
- attribute :card, String
56
- ```
57
-
58
- 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:
59
-
60
- ```rb
61
- component.register_resource(:<my_resource>) do |resource|
62
- resource.class = "Decidim::<Component>/<MyResource>" # eg. "Decidim::Proposals::ProposalDraft
63
- resource.card = "decidim/<component>/<my_resource>" # eg. "decidim/proposals/proposal_draft"
64
- resource.component_manifest = component
65
- end
66
- ```
67
-
68
- ```rb
69
- module Decidim
70
- module <Component>
71
- class <MyResource> < Decidim::ApplicationRecord
72
- include Decidim::Resourceable
73
- # ...
74
- end
75
- end
76
- end
77
- ```
78
-
79
- - The **Cell Class**, following the convention, will reside in `decidim-<component>/app/cells/decidim/<component>/<my_resource>_cell.rb`:
80
-
81
- ```rb
82
- module Decidim
83
- module <Component>s
84
- class <MyResource>Cell < Decidim::ViewModel
85
- def show
86
- render # renders decidim-<component>/app/cells/decidim/<component>/<my_resource>
87
- end
88
- end
89
- end
90
- end
91
- ```
92
-
93
- - The **Cell Views** will be in the `decidim-<component>/app/cells/decidim/<component>/<my_resource>` and defaults to `show.erb`
94
-
95
- ## More Info
96
-
97
- - [cells/README.md at master · trailblazer/cells](https://github.com/trailblazer/cells/blob/master/README.md)
98
- - [Trailblazer: Cells](http://trailblazer.to/gems/cells/) / [Trailblazer: Cells API](http://trailblazer.to/gems/cells/api.html)
99
- - [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 DELETED
@@ -1,55 +0,0 @@
1
- # Checklist
2
-
3
- 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:
4
-
5
- ## Technological
6
-
7
- 1. Choose a **domain or subdomain** for your application. Some typical names involve "Participation" or "Decision" conjugations.
8
-
9
- 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).
10
-
11
- 1. Customize the [**look and feel**](customization/styles.md) (colors, pictures, fonts, etc).
12
-
13
- 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.
14
-
15
- 1. Configure your **SMTP** server.
16
-
17
- 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/).
18
-
19
- 1. Setup an **analytics** server. For better compliance with Decidim Social Contract, we recommend using [Matomo](https://matomo.org/).
20
-
21
- 1. Setup **backup** on your server. The most important things to save are the `public/uploads` and the database.
22
-
23
- 1. Decide and implement which kind of **[Authorization](customization/authorizations.md)** you're going to use.
24
-
25
- 1. Comply with our License (Affero GPL 3) and **publish your code** to [GitHub](http://github.com) or wherever you want.
26
-
27
- 1. Review your **decidim initializer** on your application (config/initializers/decidim.rb).
28
-
29
- 1. Configure your [**ActiveJob**](services/activejob.md) background queue.
30
-
31
- 1. If you want, configure your [**social providers**](services/social_providers.md) to enable login using external applications.
32
-
33
- 1. Check that you don't have any **default users, emails and passwords**, neither on the admin or on the system panel.
34
-
35
- 1. Configure recurring jobs for [**metrics**](advanced/metrics.md) and [**open data**](advanced/open-data.md)
36
-
37
- 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.
38
-
39
- 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).
40
-
41
- ## Contents
42
-
43
- 1. Ideally you'll have a **Team** formed with experts on IT, Communication, Participation, Design and Law.
44
-
45
- 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`.
46
-
47
- 1. Comply with your current **legal requirements**, like to registrate your privacy policy with the autorities (eg LOPD on Spain).
48
-
49
- 1. Fill the **Participatory Processes Configuration Form** to prepare your Participatory Process for Decidim.
50
-
51
- 1. Read the **[Administration manual](https://decidim.org/docs/)**.
52
-
53
- 1. Participate on **[MetaDecidim](http://meta.decidim.org)**.
54
-
55
- 1. Read the Decidim **[Social Contract](https://decidim.org/contract/)**.
@@ -1,5 +0,0 @@
1
- # Authorizations
2
-
3
- See [decidim-verifications's README][README].
4
-
5
- [README]: https://github.com/decidim/decidim/blob/master/decidim-verifications/README.md
@@ -1,7 +0,0 @@
1
- # Images
2
-
3
- You can change most of the images (for instance the logo, main banner on homepage, contents of participatory processes, etc) through the Administration panel.
4
-
5
- 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`
6
-
7
- 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).
@@ -1,9 +0,0 @@
1
- # Javascript
2
-
3
- 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:
4
-
5
- ```javascript
6
- $(function(){
7
- alert('foobar');
8
- });
9
- ```
@@ -1,30 +0,0 @@
1
- # Using machine translations
2
-
3
- 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.
4
-
5
- ## Flow description
6
-
7
- 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:
8
-
9
- - 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.
10
- - For each translatable field that is changed, it lists the locales that need to be translated.
11
- - For each combination field/locale a new job is fired.
12
- - This job calls the machine translation service, which will handle how to translate that given text.
13
-
14
- This workflow will only start if the machine translation service is configured in the installation, and the organization has the service enabled.
15
-
16
- ## Enabling the integration, installation-wise
17
-
18
- This is an option in the Decidim initializer:
19
-
20
- ```ruby
21
- config.enable_machine_translations = true
22
- config.machine_translation_service = "MyApp::MyOwnTranslationService"
23
- ```
24
-
25
- The class will need to be implemented, or reuse one from the community. Check the docs on how to implement a machine translation service.
26
-
27
- ## Enabling the integration, organization-wise
28
-
29
- Each organization will be able to enable/disable machine translations if they want to. They can do that from the organization configuration.
30
-
@@ -1,610 +0,0 @@
1
- # Custom map providers
2
-
3
- Decidim can be configured to use multiple different
4
- [map service providers][link-docs-maps] but it can be also extended to use any
5
- possible service provider out there.
6
-
7
- If you want to create your own provider integration, you will need to find a
8
- service provider that provides all the following services:
9
-
10
- - [A geocoding server][link-wiki-geocoding] in order to turn user entered
11
- addresses into [geocoordinates][link-wiki-geocoordinates].
12
- - [A geocoding autocompletion server][link-wiki-autocompletion] in order to
13
- suggest and predict addresses based on the user input and turning these
14
- suggested addresses into [geocoordinates][link-wiki-geocoordinates].
15
- - [A map tile server][link-wiki-tile-server] for the dynamic maps, preferrably
16
- one that is compatible with the default [Leaflet][link-leaflet] map library.
17
- - [A static map image server][link-wiki-static-maps] for the static map images
18
- e.g. on the proposal pages. This service is optional as Decidim will use the
19
- dynamic map tiles to generate a similar map element if the static map image
20
- cannot be provided.
21
-
22
- One option is to host some or all of these services yourself as there are open
23
- source alternatives available for all of these services. More information about
24
- self hosting is available at the
25
- [maps and geocoding configuration][link-docs-maps-multiple-providers]
26
- documentation.
27
-
28
- You may also decide to [disable some of the services][link-docs-maps-disable]
29
- that are not available at your service provider but in order to get the full out
30
- of Decidim, it is recommended to find a service provider with all these
31
- services.
32
-
33
- In case you want to use different service providers for the different categories
34
- of map services, that is also possible. Instructions for this are provided in
35
- the [maps and geocoding configuration][link-docs-maps-multiple-providers]
36
- documentation.
37
-
38
- ## Creating your own map service provider
39
-
40
- First thing you will need is to define a service provider module which also
41
- defines all the services your provider is able to serve. An example service
42
- provider module looks as follows:
43
-
44
- ```ruby
45
- module Decidim
46
- module Map
47
- module Provider
48
- module Geocoding
49
- autoload :YourProvider, "decidim/map/provider/geocoding/your_provider"
50
- end
51
- module Autocomplete
52
- autoload :YourProvider, "decidim/map/provider/autocomplete/your_provider"
53
- end
54
- module DynamicMap
55
- autoload :YourProvider, "decidim/map/provider/dynamic_map/your_provider"
56
- end
57
- module StaticMap
58
- autoload :YourProvider, "decidim/map/provider/static_map/your_provider"
59
- end
60
- end
61
- end
62
- end
63
- ```
64
-
65
- Please note that you will need to place the utility classes for each category of
66
- services under the paths defined for the autoloading functionality.
67
-
68
- ### Defining the geocoding utility
69
-
70
- For the geocoding functionality, Decidim uses the [Geocoder gem][link-geocoder]
71
- which does most of the heavy lifting. It is not necessary to use this gem but
72
- in case your target service is already integrated with that gem, it makes this
73
- step much easier for you. Take a look at the list of
74
- [supported geocoding APIs][link-geocoder-apis] for the Geocoder gem.
75
-
76
- In case your API is supported by the Geocoder gem, the only thing you need to do
77
- to create your geocoding utility is to create the following empty class:
78
-
79
- ```ruby
80
- module Decidim
81
- module Map
82
- module Provider
83
- module Geocoding
84
- class YourProvider < ::Decidim::Map::Geocoding
85
- # ... add your customizations here ...
86
- end
87
- end
88
- end
89
- end
90
- end
91
- ```
92
-
93
- If the target service has some other "lookup handle" defined in the Geocoder gem
94
- than `:your_provider`, you may want to override the `handle` method in the
95
- geocoding utility's class you just defined. This is passed for the Geocoder gem
96
- as your lookup handle. An example of this can be seen in the
97
- [`Decidim::Map::Provider::Geocoding::Osm`][link-code-osm-geocoder] class which
98
- changes the handle to `:nominatim` instead of the default `:osm` which is not an
99
- existing lookup handle in the Geocoder gem.
100
-
101
- In case you want to customize the geocoding utility for your provider, you can
102
- define the following methods in the utility class:
103
-
104
- - `search(query, options = {})` - A common method for searching the geocoding
105
- API and returning an array of results. The results array contains the Geocoder
106
- gem's result objects of type
107
- [`Geocoder::Result::Base`][link-code-geocoder-result] or the result type
108
- specific to your API. If the first parameter is an address string, the method
109
- does a forward geocoding request finding the closest matching coordinate pairs
110
- for that address. If the first parameter is a coordinate pair array, the
111
- method does a reverse geocoding request finding the closest matching addresses
112
- for the search.
113
- - `coordinates(address, options = {})` - A method that searches the best
114
- matching coordinates for the given address string. Only returns one coordinate
115
- pair as an array.
116
- - `address(coordinates, options = {})` - A method that searches the best
117
- matching address for the given coordinate pair array. Only returns one address
118
- as a string.
119
-
120
- Customization may be needed if you are not happy with the default results
121
- returned by the Geocoder gem. For instance, in some occasions you might want to
122
- pass extra query options to the geocoding API or sort the results differently
123
- than what was returned by the API and what is already done in Decidim by
124
- default.
125
-
126
- In order to provide configuration options for the Geocoder gem's lookup, you can
127
- pass them directly through the maps configuration with the following syntax:
128
-
129
- ```ruby
130
- config.maps = {
131
- provider: :your_provider,
132
- api_key: Rails.application.secrets.maps[:api_key],
133
- geocoding: { extra_option: "value", another_option: "value" }
134
- }
135
- ```
136
-
137
- This would equal to configuring the Geocoder gem with the following code:
138
-
139
- ```ruby
140
- Geocoder.configure(
141
- your_provider: {
142
- api_key: Rails.application.secrets.maps[:api_key],
143
- extra_option: "value",
144
- another_option: "value"
145
- }
146
- )
147
- ```
148
-
149
- Each geocoding API may require their own configuration options. Please refer to
150
- the Geocoder gem's [supported geocoding APIs][link-geocoder-apis] documentation
151
- to find out the available options for your API.
152
-
153
- ### Defining the geocoding autocompletion maps utility
154
-
155
- For the geocoding autocompletion map functionality, you should preferrably use
156
- a service provider that is compatible with [Photon][link-photon] which is
157
- already integrated with Decidim.
158
-
159
- If this is not possible, you can also create a custom geocoding autocompletion
160
- maps utility for your own service provider by defining the following empty class
161
- to start with:
162
-
163
- ```ruby
164
- module Decidim
165
- module Map
166
- module Provider
167
- module Autocomplete
168
- class YourProvider < ::Decidim::Map::Autocomplete
169
- # ... add your customizations here ...
170
- end
171
- end
172
- end
173
- end
174
- end
175
- ```
176
-
177
- In case you want to customize the geocoding autocompletion map utility for your
178
- provider, you can define the following methods in the utility class:
179
-
180
- - `builder_class` - Returns a class for the geocoding autocompletion builder
181
- that is used to create the input fields for the autocompleted addresses in the
182
- front-end. By default, this would be
183
- `Decidim::Map::Provider::Autocomplete::YourProvider::Builder` or if that is
184
- not defined, defaults to `Decidim::Map::Autocomplete::Builder`. See below for
185
- further notes about the builder class.
186
- - `builder_options` - A method that prepares the options for the builder
187
- instance that is used to create the maps in the front-end. By default, this
188
- is an empty hash that needs to be configured for each provider.
189
-
190
- To see an example how to customize the static map utility, take a look at the
191
- [HERE Maps geocoding autocomletion utility][link-code-here-autocomplete].
192
-
193
- In order to provide configuration options for the geocoding autocompletion, you
194
- can pass them directly through the maps configuration with the following syntax:
195
-
196
- ```ruby
197
- config.maps = {
198
- provider: :your_provider,
199
- api_key: Rails.application.secrets.maps[:api_key],
200
- autocomplete: {
201
- url: "https://photon.example.org/api/"
202
- }
203
- }
204
- ```
205
-
206
- And then you can use these options in your provider utility as follows e.g. in
207
- the `builder_options` method:
208
-
209
- ```ruby
210
- def builder_options
211
- { url: configuration.fetch(:url, nil) }.compact
212
- end
213
- ```
214
-
215
- You will also need to define a builder class inside your provider utility class
216
- as follows:
217
-
218
- ```ruby
219
- module Decidim
220
- module Map
221
- module Provider
222
- module Autocomplete
223
- class Here < ::Decidim::Map::Autocomplete
224
- # ... other customizations go gere ...
225
-
226
- # This is the actual builder customization where you could define e.g.
227
- # the JavaScript asset which is used to initialize the geocoding
228
- # autocompletion functionality in the front-end:
229
- class Builder < Decidim::Map::Autocomplete::Builder
230
- def javascript_snippets
231
- template.javascript_include_tag("decidim/geocoding/provider/your_provider")
232
- end
233
- end
234
- end
235
- end
236
- end
237
- end
238
- end
239
- ```
240
-
241
- To see an example of the front-end JavaScript code that handles the geocoding
242
- requests, you can take a look at the
243
- [HERE Maps example][link-code-here-autocomplete-js]. You will have to listen to
244
- the `geocoder-suggest.decidim` JavaScript event on all elements that have the
245
- `data-decidim-geocoding` attribute defined which contains all the configurations
246
- returned by the builder's `builder_options` method as mentioned above. For
247
- example, if you passed the following configuration from that method:
248
-
249
- ```js
250
- { url: "https://photon.example.org/api/", other_config: "foo" }
251
- ```
252
-
253
- This would be available in the JavaScript as follows:
254
-
255
- ```js
256
- $(document).on("ready", () => {
257
- $("[data-decidim-geocoding]").each((_i, el) => {
258
- console.log($(el).data("decidim-geocoding"));
259
- // => This would print out:
260
- // {url: "https://photon.example.org/api/", otherConfig: "foo"}
261
- });
262
- });
263
- ```
264
-
265
- When you hook into the `geocoder-suggest.decidim` event on these methods, the
266
- event callback will be provided three arguments:
267
-
268
- - `event` - The event that you hooked into
269
- - `query` - The text to be queried, i.e. what the user entered into the input
270
- - `callback` - A callback method which you will need to call with your geocoding
271
- autocompletion results once the request to the API has finished in the
272
- front-end.
273
-
274
- The `callback` method expects one argument which is the array of result objects.
275
- The result objects need to contain the following keys:
276
-
277
- - `key` - The key which will be matched against the user entered input
278
- - `value` - The value which will be added to the address input if the user
279
- decides to select this value
280
-
281
- Optionally, you can also include a `coordinates` key in the result object which
282
- contains an array of two cordinates (latitude and longitude respectively). You
283
- can also include any other data you might need in the front-end for these
284
- results but it will be not used by Decidim.
285
-
286
- The final code would look something like follows:
287
-
288
- ```js
289
- $(document).on("ready", () => {
290
- $("[data-decidim-geocoding]").each((_i, el) => {
291
- const $input = $(el);
292
- const config = $input.data("decidim-geocoding");
293
-
294
- $input.on("geocoder-suggest.decidim", (event, query, callback) => {
295
- currentSuggestionQuery = setTimeout(() => {
296
- $.ajax({
297
- method: "GET",
298
- url: config.url,
299
- data: { apiKey: config.apiKey },
300
- dataType: "json"
301
- }).done((resp) => {
302
- if (resp.suggestions) {
303
- return callback(resp.suggestions.map((item) => {
304
- return {
305
- key: item.label,
306
- value: item.label,
307
- coordinates: [item.latitude, item.longitude],
308
- yourExtraData: item.yourExtraData
309
- }
310
- }));
311
- }
312
- return null;
313
- });
314
- });
315
- });
316
- });
317
- ```
318
-
319
- If your autocompletion API does not provide the coordinates information along
320
- with the autocompletion requests, you can hook into another event to do extra
321
- queries for the geocoordinates as follows:
322
-
323
- ```js
324
- $(document).on("ready", () => {
325
- $("geocoder-suggest-select.decidim", (ev, selectedItem) => {
326
- console.log(selectedItem);
327
- // => This would print out what you returned for the `callback` as shown
328
- // above.
329
-
330
- // NOTE: YOU DON'T NEED THIS IF YOUR RESPONSE OBJECTS ALREADY CONTAINED THE
331
- // COORDINATES IN THE `coordinates` KEY OF EACH RESULT OBJECT!
332
- // Then, once you know the coordinates, you trigger the following event on
333
- // the same input (obviously, you need to query the API first):
334
- const coordinates = [1.123, 2.234];
335
- $(ev.target).trigger("geocoder-suggest-coordinates.decidim", [coordinates]);
336
- });
337
- });
338
- ```
339
-
340
- Finally, if you want to pass these coordinates to the same form where your
341
- address field is located at, you can use the `Decidim.attachGeocoding()` method
342
- as follows:
343
-
344
- ```js
345
- $(document).ready(function() {
346
- Decidim.attachGeocoding($("#your_address_input"));
347
- });
348
- ```
349
-
350
- Now the latitude and longitude coordinates would be passed to the same form
351
- where the address input is located at. For example, if the address input had the
352
- name `record[address]`, new hidden fields would be now generated for the
353
- geocoding autocomplete suggestion's coordinates with the following names:
354
-
355
- - `record[latitude]` for the latitude coordinate
356
- - `record[longitude]` for the longitude coordinate
357
-
358
- Then, you can read these values along with the form's POST data in order to
359
- store the coordinates for your records in the back-end. This is not 100%
360
- necessary but it improves the accuracy of the geocoding functionality and it
361
- also avoids unnecessary double requests to the geocoding API (front-end +
362
- back-end).
363
-
364
- ### Defining the dynamic maps utility
365
-
366
- For the dynamic map functionality, you should primarily use a service provider
367
- that is compatible with the [Leaflet library][link-leaflet] that ships with
368
- Decidim. You can also integrate to services that are not compatible with Leaflet
369
- but it will cause you more work and is not covered by this guide.
370
-
371
- Please note that you don't necessarily even need to create your own dynamic maps
372
- utility if your service provider is already compatible with the
373
- [`Decidim::Map::Provider::DynamicMap::Osm`][link-code-osm-dynamic] provider. In
374
- order to configure your custom OSM compatible service provider take a look at
375
- the [maps and geocoding configuration][link-docs-maps-osm] documentation.
376
-
377
- If your service provider is not fully compatible with the default OSM provider,
378
- you can start writing your customizations by creating an empty dynamic map
379
- provider utility with the following code:
380
-
381
- ```ruby
382
- module Decidim
383
- module Map
384
- module Provider
385
- module DynamicMap
386
- class YourProvider < ::Decidim::Map::DynamicMap
387
- # ... add your customizations here ...
388
- end
389
- end
390
- end
391
- end
392
- end
393
- ```
394
-
395
- In case you want to customize the dynamic map utility for your provider, you can
396
- define the following methods in the utility class:
397
-
398
- - `builder_class` - Returns a class for the dynamic map builder that is used
399
- to create the maps in the front-end. By default, this would be
400
- `Decidim::Map::Provider::DynamicMap::YourProvider::Builder` or if that is not
401
- defined, defaults to `Decidim::Map::DynamicMap::Builder`. See below for
402
- further notes about the builder class.
403
- - `builder_options` - A method that prepares the options for the builder
404
- instance that is used to create the maps in the front-end. By default, this
405
- prepares the tile layer configurations for the Leaflet map.
406
-
407
- In addition, you may want to customize the Builder class in case you are not
408
- happy with the default dynamic map builder functionality. To see an example how
409
- to customize the builder, take a look at the
410
- [HERE Maps builder class][link-code-here-dynamic]. Please note that the custom
411
- dynamic map builder needs to extend the
412
- [`Decidim::Map::DynamicMap::Builder`][link-code-dynamic-map] class as you can
413
- also see from the HERE Maps example.
414
-
415
- The builder class works directly with the view layer and can refer to the view
416
- in question or any methods available for the view using the `template` object
417
- inside the builder. You may be already familiar with a similar builder concept
418
- if you have ever used the [Rails Form Builder][link-rails-form-builder].
419
-
420
- In order to provide configuration options for the dynamic maps, you can pass
421
- them directly through the maps configuration with the following syntax:
422
-
423
- ```ruby
424
- config.maps = {
425
- provider: :your_provider,
426
- api_key: Rails.application.secrets.maps[:api_key],
427
- dynamic: {
428
- tile_layer: {
429
- url: "https://tiles.example.org/{z}/{x}/{y}.png?key={apiKey}&{foo}&style={style}",
430
- api_key: true,
431
- foo: "bar=baz",
432
- style: "bright-style",
433
- attribution: %{
434
- <a href="https://www.openstreetmap.org/copyright" target="_blank">&copy; OpenStreetMap</a> contributors
435
- }.strip
436
- }
437
- }
438
- }
439
- ```
440
-
441
- This will cause the following options to be available for the builder instance
442
- by default:
443
-
444
- ```ruby
445
- {
446
- tile_layer: {
447
- url: "https://tiles.example.org/{z}/{x}/{y}.png?key={apiKey}&{foo}&style={style}",
448
- configuration: {
449
- api_key: Rails.application.secrets.maps[:api_key],
450
- foo: "bar=baz",
451
- style: "bright",
452
- attribution: %{
453
- <a href="https://www.openstreetmap.org/copyright" target="_blank">&copy; OpenStreetMap</a> contributors
454
- }.strip
455
- }
456
- }
457
- }
458
- ```
459
-
460
- And by default, this will cause the Leaflet tile layer to be configured as
461
- follows:
462
-
463
- ```js
464
- L.tileLayer(
465
- "https://tiles.example.org/{z}/{x}/{y}.png?key={apiKey}&{foo}&style={style}",
466
- {
467
- apiKey: "your_secret_key",
468
- foo: "bar=baz",
469
- style: "bright",
470
- attribution: '<a href="https://www.openstreetmap.org/copyright" target="_blank">&copy; OpenStreetMap</a> contributors'
471
- }
472
- ).addTo(map);
473
- ```
474
-
475
- ### Defining the static maps utility
476
-
477
- For the static map functionality, you should preferrably use a service provider
478
- that is compatible with [osm-static-maps][link-osm-static-maps] which is already
479
- integrated with Decidim.
480
-
481
- If this is not possible, you can also create a custom static maps utility for
482
- your own service provider by defining the following empty class to start with:
483
-
484
- ```ruby
485
- module Decidim
486
- module Map
487
- module Provider
488
- module StaticMap
489
- class YourProvider < ::Decidim::Map::StaticMap
490
- # ... add your customizations here ...
491
- end
492
- end
493
- end
494
- end
495
- end
496
- ```
497
-
498
- If you want to use dynamic map elements for the static maps as well, you can
499
- leave the static map utility empty as shown above. Decidim will create a dynamic
500
- map replacement for the static map image in case the static map utility will not
501
- return a proper map URL.
502
-
503
- In case you want to customize the static map utility for your provider, you can
504
- define the following methods in the utility class:
505
-
506
- - `link(latitude:, longitude:, options: {})` - Returns a link for the given
507
- geographic location where the static map image is linked to. By default, this
508
- will return a link to www.openstreetmap.org.
509
- - `url(latitude:, longitude:, options: {})` - Returns a URL for loading the
510
- static map image from the service provider. By default, this will return a
511
- link to the configured static map URL with the following URL query parameters:
512
- - `latitude` - The value for the `latitude` option provided for the method.
513
- - `longitude` - The value for the `longitude` option provided for the method.
514
- - `zoom` - The value for key `:zoom` in the options hash (default: 15).
515
- - `width` - The value for key `:width` in the options hash (default: 120).
516
- - `height` - The value for key `:height` in the options hash (default: 120).
517
- - `url_params(latitude:, longitude:, options: {})` - Returns a hash of prepared
518
- URL parameters for the `url` method. For the default parameters, see the
519
- explanations above for the `url` method.
520
- - `image_data(latitude:, longitude:, options: {})` - Does a request to the URL
521
- defined by the `url` method and returns the raw binary data in the response
522
- body of that request. This data will be cached by Decidim once fetched from
523
- the API to speed up further displays of the same static map.
524
-
525
- To see an example how to customize the static map utility, take a look at the
526
- [HERE Maps static map utility][link-code-here-static].
527
-
528
- In order to provide configuration options for the static maps, you can pass them
529
- directly through the maps configuration with the following syntax:
530
-
531
- ```ruby
532
- config.maps = {
533
- provider: :your_provider,
534
- api_key: Rails.application.secrets.maps[:api_key],
535
- static: {
536
- url: "https://staticmap.example.org/",
537
- foo: "bar",
538
- style: "bright"
539
- }
540
- }
541
- ```
542
-
543
- And then you can use these options in your provider utility as follows e.g. in
544
- the `url_params` method:
545
-
546
- ```ruby
547
- def url_params(latitude:, longitude:, options: {})
548
- super.merge(
549
- style: configuration.fetch(:style, "dark"),
550
- foo: configuration.fetch(:foo, "baz")
551
- )
552
- end
553
- ```
554
-
555
- When calling the `url` method with the latitude of `1.123` and longitude of
556
- `2.456`, the utility would now generate the following URL with these
557
- configurations and customizations:
558
-
559
- ```bash
560
- https://staticmap.example.org/?latitude=1.123&longitude=2.456&zoom=15&width=120&height=120&style=bright&foo=bar
561
- ```
562
-
563
- If you want to use the dynamic map replacements for the static map images, do
564
- not configure `static` section for your maps:
565
-
566
- ```ruby
567
- config.maps = {
568
- provider: :your_provider,
569
- api_key: Rails.application.secrets.maps[:api_key]
570
- # static: { ... } # LEAVE THIS OUT
571
- }
572
- ```
573
-
574
- Even if you decide to use the dynamic map replacements, you will still need to
575
- define the static map utility because it is used to generate the link where
576
- users will be pointed at when they click the map image. In this case, the static
577
- map utility can be empty as you won't need any customization for it to work.
578
-
579
- ## Configuring your own map service provider
580
-
581
- After you have finished all the steps shown above, you will need to configure
582
- your service provider for Decidim. The configuration key for the example service
583
- provider referred to in this documentation would be `:your_provider`. For
584
- configuration, refer to the [maps and geocoding configuration][link-docs-maps]
585
- documentation.
586
-
587
- [link-code-dynamic-map]: /decidim-core/lib/decidim/map/dynamic_map.rb
588
- [link-code-geocoder-result]: https://github.com/alexreisner/geocoder/blob/master/lib/geocoder/results/base.rb
589
- [link-code-here-autocomplete]: /decidim-core/lib/decidim/map/provider/autocomplete/here.rb
590
- [link-code-here-autocomplete-js]: /decidim-core/app/assets/javascripts/decidim/geocoding/provider/here.js.es6
591
- [link-code-here-dynamic]: /decidim-core/lib/decidim/map/provider/dynamic_map/here.rb
592
- [link-code-here-static]: /decidim-core/lib/decidim/map/provider/static_map/here.rb
593
- [link-code-osm-dynamic]: /decidim-core/lib/decidim/map/provider/dynamic_map/osm.rb
594
- [link-code-osm-geocoder]: /decidim-core/lib/decidim/map/provider/geocoding/osm.rb
595
- [link-docs-maps]: /docs/services/maps.md
596
- [link-docs-maps-disable]: /docs/services/maps.md#disabling
597
- [link-docs-maps-osm]: /docs/services/maps.md#configuring-open-street-maps-based-service-providers
598
- [link-docs-maps-multiple-providers]: /docs/services/maps.md#combining-multiple-service-providers
599
- [link-geocoder]: https://github.com/alexreisner/geocoder
600
- [link-geocoder-apis]: https://github.com/alexreisner/geocoder/blob/master/README_API_GUIDE.md
601
- [link-leaflet]: https://leafletjs.com/
602
- [link-osm-static-maps]: https://github.com/jperelli/osm-static-maps
603
- [link-photon]: https://github.com/komoot/photon
604
- [link-rails-form-builder]: https://guides.rubyonrails.org/form_helpers.html#customizing-form-builders
605
- [link-wiki-autocompletion]: https://en.wikipedia.org/wiki/Autocomplete
606
- [link-wiki-geocoding]: https://en.wikipedia.org/wiki/Geocoding
607
- [link-wiki-geocoordinates]: https://en.wikipedia.org/wiki/Geographic_coordinate_system
608
- [link-wiki-map-tiles]: https://wiki.openstreetmap.org/wiki/Tiles
609
- [link-wiki-static-maps]: https://wiki.openstreetmap.org/wiki/Static_map_images
610
- [link-wiki-tile-server]: https://en.wikipedia.org/wiki/Tile_Map_Service