decidim 0.23.5 → 0.24.2

data/docs/services/analytics.md

@@ -1,23 +0,0 @@
-# Analytics
-
-Decidim, for a matter of privacy, doesn't come bundled (or associated with) any analytics service, leaving that part to the developer.
-
-Adding analytics is quite easy. We've set up a partial in place for that. Just create a view in your app under `app/views/layouts/decidim/_head_extra.html.erb` with your content.
-
-Here's an example for Piwik:
-
-```javascript
-<script type="text/javascript">
-  var _paq = _paq || [];
-  // tracker methods like "setCustomDimension" should be called before "trackPageView"
-  _paq.push(['trackPageView']);
-  _paq.push(['enableLinkTracking']);
-  (function() {
-    var u="?????";
-    _paq.push(['setTrackerUrl', u+'piwik.php']);
-    _paq.push(['setSiteId', '?']);
-    var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
-    g.type='text/javascript'; g.async=true; g.defer=true; g.src=u+'piwik.js'; s.parentNode.insertBefore(g,s);
-  })();
-</script>
-```

data/docs/services/elections_bulletin_board.md

@@ -1,38 +0,0 @@
-# Elections Bulletin Board
-
-:warning: This is a work in progress and is not fully working yet.
-
-In order to celebrate [End-to-end auditable votings](https://en.wikipedia.org/wiki/End-to-end_auditable_voting_systems) using the Elections module, you will need to connect your Decidim instance with an instance of the [Decidim Bulletin Board application](https://github.com/decidim/decidim-bulletin-board/), preferably run by an independent organization.
-
-## Identification pair of keys generation
-
-The first step needed to setup the connection is to generate an a pair of keys to identify the application against the Bulletin Board. This can be done running the following rake task in your application environment:
-
-```sh
-bundle exec rake decidim_elections:generate_identification_keys
-```
-
-This task will output the generated private and public keys. You should copy the public key and send it to the Bulletin Board administrator through a secure channel. When copying the key, include the starting and ending lines with the prefix `-----`.
-
-After that, use one of these methods to make the private key available from your Decidim installation:
-
-a. Copy the private key, paste in a new file and store its path on the environment variable `BULLETIN_BOARD_IDENTIFICATION_PRIVATE_KEY`.
-b. Copy the private key and store that value on the environment variable `BULLETIN_BOARD_IDENTIFICATION_PRIVATE_KEY`.
-
-Regardless of the used method, when copying the private key remember to include the lines prefixed by `-----` and ensure that the private key is not lost between deployments and servers reboots and that only can be accessed by the application.
-
-## Configuration of the Bulletin Board application
-
-The Bulletin Board administrator will store the received public key in their server and will send you back an API key. To complete the setup process you should store this API key and the Bulletin Board URL address on the environment variables `BULLETIN_BOARD_API_KEY` and `BULLETIN_BOARD_SERVER`, respectively.
-
-The following YAML snippet with all the defined environment variables should be used in the `default` block of your application `config/secrets.yml` file. Maybe this is already done, as it was included in the Decidim applications generator during the development of the Elections module.
-
-```yaml
-  bulletin_board:
-    identification_private_key: |
-<%= ENV["BULLETIN_BOARD_IDENTIFICATION_PRIVATE_KEY"]&.indent(6) %>
-    server: <%= ENV["BULLETIN_BOARD_SERVER"] %>
-    api_key: <%= ENV["BULLETIN_BOARD_API_KEY"] %>
-```
-
-After restarting the Decidim instance, administrator users will be able to create elections on the configured Bulletin Board.

data/docs/services/maps.md

@@ -1,362 +0,0 @@
-# Maps and geocoding
-
-Decidim has the ability to geocode proposals and meetings and display them on a
-map. Decidim has built-in support for the following map service providers:
-
-- [HERE Maps][link-here] (Recommended)
-  - Supports map tiles, static map images, geocoding and geocoding
-    autocompletion
-  - Easy to get started with, comes with a rather generous free plan
-  - [Configuring HERE Maps][anchor-configure-here-maps]
-- [Open Street Maps based services][link-osm-commercial]
-  - Please pick a service provider that provides all needed services (map tiles,
-    static map images, geocoding and geocoding autocompletion)
-  - We can't use the OSM's own services by their
-    [tile usage policy][link-osm-tile-usage].
-  - In case your service provider does not offer static map images, Decidim will
-    use the dynamic map tiles to generate a similar map element.
-  - As an alternative, you may also want to use your own self-hosted map servers
-    (see [Hosting your own map services][anchor-hosting-osm] for
-    more information)
-  - [Configuring Open Street Maps based service providers][anchor-configure-osm]
-
-If you want to integrate Decidim to some other map service provider, read how to
-[write your own integration code][link-docs-custom-maps] for that.
-
-## Configuring maps and geocoding
-
-After generating your app, you'll see that your `config/initializers/decidim.rb`
-file includes commented code about map services:
-
-```ruby
-# Map and Geocoder configuration
-# config.maps = {
-#   ...
-# }
-```
-
-The initializer comments provide examples for the services mentioned in this
-documentation. Please refer to the section below for the service you have
-registered for the maps functionality.
-
-If you want to enable geocoding in your app:
-
-1. Select a service provider for the maps functionality and register an account
-   with that provider
-1. Uncomment or add the code under the selected service provider in your
-   `config/initializers/decidim.rb`.
-1. Make sure your `config/secrets.yml` file has the needed section (it should
-   be added by the generator automatically).
-1. Configure the service provider credentials in `config/secrets.yml` and refer
-   to them from your `config/initializers/decidim.rb`.
-1. If you had your Rails server running, restart it so the changes apply.
-
-### Configuring HERE Maps
-
-Use the following configuration for HERE Maps:
-
-`config/initializers/decidim.rb`:
-
-```ruby
-# Map and Geocoder configuration
-# == HERE Maps ==
-config.maps = {
-  provider: :here,
-  api_key: Rails.application.secrets.maps[:api_key],
-  static: { url: "https://image.maps.ls.hereapi.com/mia/1.6/mapview" }
-}
-```
-
-`config/secrets.yml`:
-
-```yaml
-default: &default
-  # ...
-  maps:
-    api_key: <%= ENV["MAPS_API_KEY"] %>
-```
-
-`.env`:
-
-```bash
-MAPS_API_KEY=your_api_key_here
-```
-
-### Configuring Open Street Maps based service providers
-
-Use the following configuration for Open Street Maps based service providers:
-
-`config/initializers/decidim.rb`:
-
-```ruby
-# Map and Geocoder configuration
-# == OpenStreetMap (OSM) services ==
-config.maps = {
-  provider: :osm,
-  api_key: Rails.application.secrets.maps[:api_key],
-  dynamic: {
-    tile_layer: {
-      url: "https://tiles.example.org/{z}/{x}/{y}.png?key={apiKey}",
-      api_key: true,
-      attribution: %(
-        <a href="https://www.openstreetmap.org/copyright" target="_blank">&copy; OpenStreetMap</a> contributors
-      ).strip
-      # Translatable attribution:
-      # attribution: -> { I18n.t("tile_layer_attribution") }
-    }
-  },
-  # static: { url: "https://staticmap.example.org/" }, # optional
-  geocoding: { host: "nominatim.example.org", use_https: true },
-  autocomplete: { url: "https://photon.example.org/api/" }
-}
-```
-
-`config/secrets.yml`:
-
-```yaml
-default: &default
-  # ...
-  maps:
-    api_key: <%= ENV["MAPS_API_KEY"] %>
-```
-
-`.env`:
-
-```bash
-MAPS_API_KEY=your_api_key_here
-```
-
-For further information, see the service provider's documentation or take a look
-at the [Hosting your own map services][anchor-hosting-osm] section.
-
-### Combining multiple service providers
-
-It is also possible to combine multiple service providers for the different
-categories of map services. For instance, if you want to use HERE Maps for
-the map tiles but host the other services yourself, use the following
-configuration:
-
-```ruby
-# Map and Geocoder configuration
-# == Combination (OpenStreetMap default + HERE Maps dynamic map tiles) ==
-config.maps = {
-  provider: :osm,
-  dynamic: {
-    provider: :here,
-    api_key: Rails.application.secrets.maps[:here_api_key]
-  },
-  static: { url: "https://staticmap.example.org/" },
-  geocoding: { host: "nominatim.example.org", use_https: true },
-  autocomplete: { url: "https://photon.example.org/api/" }
-}
-```
-
-`config/secrets.yml`:
-
-```yaml
-default: &default
-  # ...
-  maps:
-    here_api_key: <%= ENV["MAPS_HERE_API_KEY"] %>
-```
-
-`.env`:
-
-```bash
-MAPS_HERE_API_KEY=your_api_key_here
-```
-
-### Disabling some of the map services
-
-When using the maps functionality, you should always aim to provide all the
-services for the user that are available in Decidim. However, not all service
-providers provide all these services, so at times you may need to disable some
-of them.
-
-The configuration syntax allows you to disable the map services one by one. For
-example, if you want to use HERE Maps as your default but disable the static map
-images and geocoding autocompletion functionality, you can use the following
-configuration:
-
-```ruby
-config.maps = {
-  provider: :here,
-  api_key: Rails.application.secrets.maps[:api_key],
-  static: false,
-  autocomplete: false
-}
-```
-
-Decidim works fine when some of the services are disabled individually but
-obviously, the disabled services are not available for Decidim users.
-
-### Global geocoder configurations
-
-In the Dedicim initialiser (`config/initializers/decidim.rb`) you will also see
-a commented section for the global geocoder configurations commented as follows:
-
-```ruby
-# Geocoder configurations ...
-# config.geocoder = {
-#   # geocoding service request timeout, in seconds (default 3):
-#   timeout: 5,
-#   # set default units to kilometers:
-#   units: :km,
-#   # caching (see https://github.com/alexreisner/geocoder#caching for details):
-#   cache: Redis.new,
-#   cache_prefix: "..."
-# }
-```
-
-This will change the global geocoding settings for your application. To learn
-more about these settings, take a look at the
-[Geocoder gem's documentation][link-geocoder].
-
-### Geocoding autocompletion configurations
-
-Each autocompletion geocoder has their own configurations and this may not apply
-for all geocoding services. The geocoder autocompletion integrations shipped
-with Decidim support the configurations shown in this section.
-
-If you want to customize the address format in the geocoding autocompletion
-fields, you can apply the following configuration to your geocoder settings:
-
-```ruby
-config.maps = {
-  # ... other configs ...
-  autocomplete: {
-    # For HERE:
-    address_format: [%w(street houseNumber), "city", "country"]
-    # For OSM/Photon:
-    # address_format: ["name", %w(street housenumber), "city", "country"]
-  }
-}
-```
-
-### Integrating with a new service provider
-
-If you want to integrate the map functionality with a new service provider, take
-a look at the [Custom map providers][link-docs-custom-maps] documentation.
-
-## Enabling maps and geocoding
-
-Once the maps functionality is configured, you'll need to activate it. As of
-April 2017, only proposals and meetings have maps and geocoding.
-
-### Proposals
-
-In order to enable geocoding for proposals you'll need to edit the component
-configuration and turn on "Geocoding enabled" configuration. This works for that
-specific component, so you can have geocoding enabled for proposals in a
-participatory process, and disabled for another proposals component in the same
-participatory process.
-
-### Meetings
-
-Meetings do not have a configuration option for geocoding. Instead, if geocoding
-is configured it will try to geocode the address every time you create or update
-a meeting. As of April 2017 there is no way to enable or disable geocoding per
-meetings component.
-
-## Hosting your own map services
-
-It is recommended to use a commercial service provider for all the map
-functionality to get up and running more easily. Hosting all these services
-yourself and keeping everything up to date is time consuming and rather complex.
-If the related complexity or the required time is not an issue, feel free to
-setup the following services on your own servers.
-
-### Map tiles: Open Street Maps tile server
-
-You will need a [map tiles][link-wiki-map-tiles] server which is used for the
-dynamic maps that the user can move themselves.
-
-Follow these instructions to setup your tiles server:
-
-https://opentileserver.org/
-
-In the example configuration, we assume you have used the following domain for
-the tiles server:
-
-https://tiles.example.org
-
-### Static map images: Openstreetmap static maps server (osm-static-maps)
-
-Some pages in Decidim display static map images which need to be fetched from
-an external server. The tiles server does not provide such static images by
-itself because one static map image may need multiple tiles to be combined into
-one. The static map image is therefore dynamically generated based on the
-parameters passed for the static map request (such as image dimensions and the
-geocoordinates of the map image position).
-
-The Open Street Maps community has made multiple open source
-[static maps image services][link-wiki-static-maps] from which you can pick
-freely but Decidim currently supports only
-[osm-static-maps][link-osm-static-maps] with the Open Street Maps services.
-
-Follow these instructions to setup your static map images server:
-
-https://github.com/jperelli/osm-static-maps#3-standalone-sample-server
-
-In the example configuration, we assume you have used the following domain for
-the static maps image server:
-
-https://staticmap.example.org
-
-Setting up this service is optional. If you do not configure a static map URL
-for the OSM based map services, Decidim will use the dynamic map tiles to
-generate a similar map element.
-
-### Geocoding: Nominatim geocoding server
-
-[Nominatim][link-osm-nominatim] makes it possible to place points on the Decidim
-maps based on addresses. This service provides geocoding capabilities by turning
-human readable addresses to [geographic coordinates][link-wiki-geocoordinates].
-
-Follow these instructions to setup your geocoding server:
-
-http://nominatim.org/release-docs/latest/admin/Installation/
-
-In the example configuration, we assume you have used the following domain for
-the geocoding server:
-
-https://nominatim.example.org
-
-### Geocoding autocompletion: Photon geocoding server
-
-[Photon][link-osm-photon] makes it possible to provide the autocompletion
-service for people writing addresses to the address fields available in Decidim.
-It uses the Open Street Maps data to serve the autocompletion requests. When
-people select one of the suggested addresses, it will also tell Decidim the map
-point for that address.
-
-Follow these instructions to setup your geocoding autocompletion server:
-
-https://github.com/komoot/photon#installation
-
-In the example configuration, we assume you have used the following domain for
-the Photon geocoding server for the autocompletion functionality:
-
-https://photon.example.org
-
-### Configure Decidim
-
-After you have all these services running, change your Decidim configurations
-to use these services. Read the
-[Configuring Open Street Maps based service providers][anchor-configure-osm]
-section for more information.
-
-[anchor-hosting-osm]: #hosting-your-own-map-services
-[anchor-configure-here-maps]: #configuring-here-maps
-[anchor-configure-osm]: #configuring-open-street-maps-based-service-providers
-[link-docs-custom-maps]: /docs/customization/maps.md
-[link-here]: http://here.com
-[link-geocoder]: https://github.com/alexreisner/geocoder
-[link-osm-commercial]: https://wiki.openstreetmap.org/wiki/Commercial_OSM_Software_and_Services
-[link-osm-nominatim]: https://wiki.openstreetmap.org/wiki/Nominatim
-[link-osm-static-maps]: https://github.com/jperelli/osm-static-maps
-[link-osm-photon]: https://github.com/komoot/photon
-[link-osm-tile-usage]: https://operations.osmfoundation.org/policies/tiles/
-[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

data/docs/services/social_providers.md

@@ -1,98 +0,0 @@
-# Social providers integration
-
-If you want to enable sign up through social providers like Facebook you will need to generate app credentials and store them in one of the following places:
-
-- In the Rails secrets file: `config/secrets.yml`. This configuration will be shared by all tenants.
-- In the site configuration (ex. system/organizations/1/edit). This configuration overrides the one in `config/secrets.yml`.
-
-Take into account that for a social provider integration appearing in the organization form, it must also be defined in `config/secrets.yml` (but the values are optional). For example:
-
-```yaml
-twitter:
-  enabled: false # disabled by default, unless activated in the organization
-  api_key:
-  api_secret:
-```
-
-## Facebook
-
-1. Navigate to [Facebook Developers Page](https://developers.facebook.com/)
-1. Follow the "Add a New App" link.
-1. Click the "Website" option.
-1. Fill in your application name and click "Create New Facebook App ID" button.
-1. Fill in the contact email info and category.
-1. Validate the captcha.
-1. Ignore the source code and fill in the URL field with `https://YOUR_DECIDIM_HOST/users/auth/facebook/callback`
-1. Navigate to the application dashboard and copy the APP_ID and APP_SECRET
-1. Paste credentials in `config/secrets.yml` or in the organization configuration. Ensure the `enabled` attribute is `true`.
-
-## Twitter
-
-1. Navigate to [Twitter Developers Page](https://dev.twitter.com/)
-1. Follow the "My apps" link.
-1. Click the "Create New App" button.
-1. Fill in the `Name`, `Description` fields.
-1. Fill in the `Website` and `Callback URL` fields with the same value. If you are working on a development app you need to use `http://127.0.0.1:3000/` instead of `http://localhost:3000/`.
-1. Check the 'Developer Agreement' checkbox and click the 'Create your Twitter application' button.
-1. Navigate to the "Keys and Access Tokens" tab and copy the API_KEY and API_SECRET.
-1. (Optional) Navigate to the "Permissions" tab and check the "Request email addresses from users" checkbox.
-1. Paste credentials in `config/secrets.yml` or in the organization configuration. Ensure the `enabled` attribute is `true`.
-
-## Google
-
-1. Navigate to [Google Developers Page](https://console.developers.google.com)
-1. Follow the 'Create projecte' link.
-1. Fill in the name of your app.
-1. Navigate to the projecte dashboard and click on "Enable API"
-1. Click on `Google+ API` and then "Enable"
-1. Navigate to the project credentials page and click on `OAuth consent screen`.
-1. Fill in the `Product name` field
-1. Click on `Credentials` tab and click on "Create credentials" button. Select `OAuth client ID`.
-1. Select `Web applications`. Fill in the `Authorized Javascript origins` with your url. Then fill in the `Authorized redirect URIs` with your url and append the path `/users/auth/google_oauth2/callback`.
-1. Copy the CLIENT_ID AND CLIENT_SECRET
-1. Paste credentials in `config/secrets.yml` or in the organization configuration. Ensure the `enabled` attribute is `true`.
-
-## Custom providers
-
-- You can define your own provider, to allow users from other external applications to login into Decidim.
-- The provider should implement an [OmniAuth](https://github.com/omniauth/omniauth) strategy.
-- You can use any of the [existing OnmiAuth strategies](https://github.com/omniauth/omniauth/wiki/List-of-Strategies).
-- Or you can create a new strategy, as the [Decidim OmniAuth Strategy](https://github.com/decidim/omniauth-decidim). This strategy allow users from a Decidim instance to login in other Decidim instance. For example, this strategy is used to allow [decidim.barcelona](https://decidim.barcelona) users to log into [meta.decidim.barcelona](https://meta.decidim.barcelona).
-- Once you have defined your strategy, you can configure it in the `config/secrets.yml` or in the organization configuration, as it is done for the built-in providers.
-- By default, Decidim will search in its icons library for an icon named as the provider. You can change this adding an `icon` or `icon_path` attribute to the provider configuration. The `icon` attribute sets the icon name to look for in the Decidim's icons library. The `icon_path` attribute sets the route to the image that should be used.
-- Here is an example of the configuration section for the Decidim strategy, using an icon located on the application's `app/assets/images` folder:
-
-```yaml
-    decidim:
-      enabled: true
-      client_id: <%= ENV["DECIDIM_CLIENT_ID"] %>
-      client_secret: <%= ENV["DECIDIM_CLIENT_SECRET"] %>
-      site_url: <%= ENV["DECIDIM_SITE_URL"] %>
-      icon_path: decidim-logo.svg
-```
-
-- You will need a custom initializer for your provider in order to pass the proper params to the OmniaAuth Builder.
-
-An example of custom initializer could be written as:
-
-```ruby
-#config/initializers/omniauth_myprovider.rb
-if Rails.application.secrets.dig(:omniauth, :myprovider).present?
-  Rails.application.config.middleware.use OmniAuth::Builder do
-    provider(
-      :myprovider,
-      setup: ->(env) {
-          request = Rack::Request.new(env)
-          organization = Decidim::Organization.find_by(host: request.host)
-          provider_config = organization.enabled_omniauth_providers[:myprovider]
-          env["omniauth.strategy"].options[:client_id] = provider_config[:client_id]
-          env["omniauth.strategy"].options[:client_secret] = provider_config[:client_secret]
-          env["omniauth.strategy"].options[:site] = provider_config[:site_url]
-        },
-      scope: :public
-    )
-  end
-end
-```
-
-The custom provider may have different configuration options, instead of `client_id`, `client_secret` and `site`.