decidim 0.30.1 → 0.31.0.rc1

data/docs/modules/develop/pages/commentable.adoc

@@ -6,7 +6,7 @@
 
 When commenting a resource, the comments counter is increased and a notification to all the followers of the participant, the participatory space and/or the resource is sent.
 
-Participants can comment with their own identity or with the identify of the `user_groups` they belong to.
+Participants can comment with their own identity.
 
 == Data model
 
@@ -16,16 +16,14 @@ For performance, a commentable has a counter cache of comments.
 [source,ascii]
 ----
 +----------------------+
-|  Decidim::Commentable |
-|   ((Proposal,...))   |                                  +-------------+
-+----------------------+  0..N +-------------------+   +--+Decidim::User|
-|-has_many comments    |-------+Decidim::Comment   |   |  +-------------+
-|#counter cache column |       +-------------------+   |
-|-comments_counter     |       |-author: may be a  |<--+
-+----------------------+       |         user or a |   |
-                               |         user_group|   |  +------------------+
-                               +-------------------+   +--+Decidim::UserGroup|
-                                                          +------------------+
+| Decidim::Commentable |
+|   ((Proposal,...))   |
++----------------------+  0..N +-------------------+
+|-has_many comments    |-------+Decidim::Comment   |
+|#counter cache column |       +-------------------+      +-------------+
+|-comments_counter     |       |-author: a user    |<-----+Decidim::User|
++----------------------+       +-------------------+      +-------------+
+
 ----
 
 Thus, each commentable must have the comments counter cache column.

data/docs/modules/develop/pages/components.adoc

@@ -140,7 +140,7 @@ Decidim.register_component(:my_component) do |component|
 
   component.settings(:step) do |settings|
     settings.attribute :a_text_setting, type: :text, default: false, required: true, translated: true, editor: true
-    settings.attribute :a_lambda_enum_setting, type: :enum, default: "all", choices: -> { SomeClass.enum_options }
+    settings.attribute :a_lambda_enum_setting, type: :enum, default: "all", choices: ->(_context) { SomeClass.enum_options }
     settings.attribute :a_readonly_setting, type: :string, readonly: ->(context) { SomeClass.readonly?(context[:component]) }
   end
 
@@ -171,30 +171,30 @@ This sections explains how to add dummy content to a development application.
 
 == Assets
 
-In order to attach the new component assets to Webpacker configuration, you need to follow a few steps. We are considering two scenarios:
+In order to attach the new component assets to Shakapacker configuration, you need to follow a few steps. We are considering two scenarios:
 
-- while the component is being developed, where changes in Webpacker configuration should be done in the development for simplicity
-- once the component has been completed, change the Webpacker templates for the app generators
+- while the component is being developed, where changes in Shakapacker configuration should be done in the development for simplicity
+- once the component has been completed, change the Shakapacker templates for the app generators
 
 In both cases, changes are the same:
 
-1. Add the new component `app/packs` folder to webpacker.yml
+1. Add the new component `app/packs` folder to shakapacker.yml
 2. Add the new entrypoints of the component to `config/webpack/custom.js`
 
 === Updating the development application
 
-While the component is being developed, it will be simpler and faster to update Webpacker configuration inside the development app. The new component `app/packs` folder needs to be added to the list of paths that Webpack will use to look for assets.
+While the component is being developed, it will be simpler and faster to update Shakapacker configuration inside the development app. The new component `app/packs` folder needs to be added to the list of paths that Webpack will use to look for assets.
 
 Also, components might have one or many entrypoints (for CSSs and javascripts) and images. These entrypoints need to be manually added to `config/webpack/custom.js`. **Any change in both files** requires to restart `webpack-dev-server` process.
 
-Take into account that generating a new development application **overwrites** Webpacker configuration so these changes might be overwritten. That is why it is necessary, once the changes are stable enough, to update the generators files.
+Take into account that generating a new development application **overwrites** Shakapacker configuration so these changes might be overwritten. That is why it is necessary, once the changes are stable enough, to update the generators files.
 
-=== Updating Webpacker configuration for the generators
+=== Updating Shakapacker configuration for the generators
 
-Decidim webpacker configuration lives in `decidim-core/lib/decidim/webpacker`. Any change performed in the development app should be replicated in these files.
+Decidim shakapacker configuration lives in `decidim-core/lib/decidim/shakapacker`. Any change performed in the development app should be replicated in these files.
 
 Also, any npm package added to package.json should be replicated in Decidim package.json file.
 
 === Updating the design app
 
-These changes should also be translated to the design app `config/webpacker.yml` and `config/webpack/custom.js` files. And if there are changes in the npm packages, these should be moved to.
+These changes should also be translated to the design app `config/shakapacker.yml` and `config/webpack/custom.js` files. And if there are changes in the npm packages, these should be moved to.

data/docs/modules/develop/pages/elections.adoc

@@ -0,0 +1,101 @@
+= Elections
+
+The Elections component can be embedded in participatory spaces. To enable it, ensure it is included in your Gemfile by adding or uncommenting the following line:
+
+[source,ruby]
+----
+gem "decidim-elections", DECIDIM_VERSION
+----
+
+The Elections component provides a way to organize voting based on a census. Depending on the type of census, users may be required to register before voting. Since the method for verifying a person against a census can vary, censuses are implemented using a manifest.
+Any Decidim application or plugin can implement its own type of census just by defining the corresponding manifest.
+
+== Registering a Census Manifest
+
+Census types use the same manifests-registry pattern used in other places around Decidim. Here is how to register them:
+
+[source,ruby]
+----
+Decidim::Elections.census_registry.register(:my_census_type) do |manifest|
+    # Define your census manifest here
+    # Example:
+    manifest.admin_form = "Decidim::MyCensuses::MyCensusForm"
+    manifest.admin_form_partial = "decidim/my_censuses/my_census_form"
+    # Add additional configuration as needed
+end
+----
+
+Note that census types need to be registered from an initializer. If you are adding a census type from a module, use this in the `engine.rb` file of your module:
+
+[source,ruby]
+----
+module Decidim::MyModule::Engine < ::Rails::Engine
+  # ...
+
+  initializer "decidim_my_module.election_census" do
+    Decidim::Elections.census_registry.register(:my_census_type) do |manifest|
+      # ...
+    end
+  end
+
+  # ...
+end
+----
+
+
+== Options for the census manifest
+
+The manifest is defined in the class `Decidim::Elections::CensusManifest`, possible attributes are:
+
+[cols="1,2,2", options="header"]
+|===
+| Attribute
+| Type
+| Description
+
+| admin_form
+| String
+| Name of the form class used in the admin interface for configuring the census. **Optional**.
+If not defined, the admin interface will not show any additional form for configuring the census.
+Note that, if you need to save different settings as a result of this form, the class needs to implement the method `census_settings` (check the `Decidim::Elections::Admin::Censuses::InternalUsersForm` for an example).
+
+| admin_form_partial
+| String
+| Path to the partial rendered for the form in the admin interface. **Required if admin_form is set**.
+
+| after_update_command
+| String
+| Command called after the census is updated in the admin interface. Receives the form and the election. **Optional**.
+If not defined, there will be no post-processing after saving the census.
+Note that you can use this command to upload a fixed list of voters in the generic model `Decidim::Elections::Voter` which only has one JSON column called `data`.
+Check the command `Decidim::Elections::Admin::Censuses::TokenCsv` for an example on how to fill this table.
+
+| user_presenter
+| String
+| Name of the presenter class for users in the census. Defaults to `"Decidim::Elections::Censuses::UserPresenter"` which should be enough for most cases.
+
+| user_query
+| Proc
+| Block returning an `ActiveRecord::Relation` of users for the census. If set, automatically defines user validation, readiness, counting, and iteration.
+Note that you can ignore this parameter if you define the next methods independently.
+
+| user_validator
+| Proc
+| Block for custom user validation. Receives the election and user data. This is used to check if a user is in a census, must return a "truthy" value if ok.
+Note that, if the `user_query` block is defined and this block is not set, the default behavior is to check the passed data against the query to see if there is any existing record.
+
+| census_ready_validator
+| Proc
+| Block for custom census readiness validation. Receives the election. Must return a "truthy" value if the census is ready (for instance a census might require you to upload a file in order to be ready).
+Note that, if the `user_query` block is defined and this block is not set, the default behavior is to check if there is at least one entry on the query.
+
+| census_counter
+| Proc
+| Block for custom census user counting. Receives the election. Must return an integer of the number of users in the census. This does not mean necessarily that only that amount of users will be able to vote.
+Dynamic censuses can grow/shrink while the election.
+Note that, if the `user_query` block is defined and this block is not set, the default behavior is to count the number of elements in the query.
+
+| user_iterator
+| Proc
+| Block for custom user iteration. Receives the election and offset. This is currently used only to show a preview of the census in the admin (so the offset is always zero, this might change in the future). If not defined and there is a `user_query` the first 5 elements will be listed.
+|===

data/docs/modules/develop/pages/fixing_locales.adoc

@@ -10,17 +10,12 @@ When you create an organization, you choose the available languages for it (thro
 However, when trying to edit it, the language selector is not available anymore.
 Here is a way to update that locales manually:
 
-First, make sure that your initializer file has all the locales you want:
+First, make sure you have set your environment variables to use all the locales that you want
 
-Edit the file `config/initializers/decidim.rb` and be sure to include all the necessary locales:
-
-[source,ruby]
+[source,bash]
 ----
-...
-# Change these lines to set your preferred locales
-  config.default_locale = :en
-  config.available_locales = [:en, :ca, :es, :fr, :pt]
-..
+export DECIDIM_DEFAULT_LOCALE="en"
+export DECIDIM_AVAILABLE_LOCALES="en,ca,es,fr,pt"
 ----
 
 Then you need to access the rails console and update the organization locales manually.
@@ -76,12 +71,12 @@ In order to solve that you can make use of these rake tasks:
 bundle exec rake decidim:locales:sync_all
 ----
 
-Run this task if you have changed `available_locales` or `default_locale` in `config/initializers/decidim.rb` and you think that some organization have values not supported by the Decidim installation.
+Run this task if you have changed `DECIDIM_AVAILABLE_LOCALES` or `DECIDIM_DEFAULT_LOCALE` environment variables, and you think that some organization has values not supported by the Decidim installation.
 
 Examples:
 
-* `Decidim.available_locales` is set to `[:en, :ca, :fr]` and your organization has `available_locales` to `[:es, :ca]`, running this script will change it to `[:ca]` as `:es` is not supported.
-* `organization.default_locale` is set to `:fr` and your `available_locales` to `[:en, :es]`, running this script will change `organization.default_locale` to `:en`.
+* `DECIDIM_AVAILABLE_LOCALES` is set to `"en,ca,fr"` and your organization has `available_locales` set to `"es,ca"`, running this script will change it to `ca` as `es` is not supported.
+* `organization.default_locale` is set to `:fr` and your `DECIDIM_AVAILABLE_LOCALES` is set to `"en,es"`, running this script will change `organization.default_locale` to `:en`.
 
 It is safe to run this task as it respects organizations with less languages than the supported.
 

data/docs/modules/develop/pages/grafana.adoc

@@ -0,0 +1,100 @@
+# Grafana
+
+For improving the data visualization capabilities of Decidim, we have a working dashboard that can be imported to Grafana, an open-source observability and monitoring platform that allows users to visualize metrics, logs, and traces in real time from various data sources.
+
+## Initial set-up
+
+The steps for having this dashboard are the following. For this tutorial we will use link:https://grafana.com[Grafana Cloud]
+
+. Go to http://grafana.com
+
++
+image::grafana/homepage.png[Grafana.com homepage]
+
+. Click in button "Create account"
+. Fill the account creation form with your information
+
++
+image::grafana/create_account_form.png[Create an account form]
+
+. Confirm your email address
+
++
+image::grafana/create_account_confirm.png[Create an account form - confirm step]
+
+. Finish the setup account process
+
++
+image::grafana/create_account_setup.png[Create an account form - setup step]
+
+## Methods
+
+Then, you have two options for connecting to any Decidim instance.
+
+a. CSV (Comma-Separated Values): A simple file format used to store tabular data, such as spreadsheets or databases. Each line in a CSV file represents a row, with values separated by commas or other separators (semi colons in the case of Decidim).
+
+b. GraphQL: A query language for APIs and a runtime for executing those queries. It allows clients to request only the data they need, reducing over-fetching and improving performance.
+
+For demonstration purposes, we will use the link:https://meta.decidim.org[Metadecidim installation].
+
+[cols="1,1", options="header"]
+|===
+|CSV
+|GraphQL
+
+|Using the Open Data features from https://meta.decidim.org/open-data
+|Using the GraphQL API features from https://meta.decidim.org/api
+
+|Only has access to the last 24 hours data
+|Has real-time access
+
+|Has access to all the public data
+|Has a limit on the number of resources. See link:https://github.com/grafana/grafana-infinity-datasource/discussions/601[Pagination of API responses]
+|===
+
+So, taking into account the last limitation from the Grafana Infinity GraphQL connector, **we recommend using the CSV method** if you need to access more than the last 10 or 20 resources.
+
+## Examples
+
+As a starting point to check-out the possibilities of this integration, we have provided some examples with the two methods.
+
+### CSV example
+
+++++
+<a href="_attachments/grafana/metadecidim-csv.json" download>Download the example for CSV integration</a>
+++++
+
+### GraphQL example
+
+++++
+<a href="_attachments/grafana/metadecidim-graphql.json" download>Download the example for GraphQL integration</a>
+++++
+
+## Import
+
+For importing any of these methods, follow these instructions:
+
+. Go to the "Dashboards" page and in the "New" button click in the "Import" option
+
++
+image::grafana/dashboards.png[Dashboards page]
+
+. In the text area, paste the contents of any of the examples provided (see below).
+
++
+image::grafana/dashboard_import.png[Import a dashboard page]
+
+. Click in the "Import" button
+
++
+image::grafana/dashboard_import_csv.png[Dashboards page]
+
+. Then you will see the imported Dashboard. Even though the examples are based on Metadecidim, are a good starting point to understand how to connect any Decidim API with Grafana.
+
++
+image::grafana/dashboard_example_csv.png[Dashboard CSV example page]
+
++
+image::grafana/dashboard_example_graphql.png[Dashboard GraphQL API example page]
+
+😊⌨️✨Happy hacking!

data/docs/modules/develop/pages/likeable.adoc

@@ -0,0 +1,106 @@
+= Likeable
+
+== Things can be likeable
+
+`Likeable` is a feature to allow participants to promote (reivindicate, etc.) resources in the platform to their followers.
+
+When liking an element the likes counter for this element is increased and a notification to all the followers of the participant is sent.
+
+Participants can like with their own identity. Each liking identity on its own will increment the likes counter by one.
+
+== Data model
+
+A `decidim_likes` table registers each like that each identity gives to each element. This is, one likeable has many likes, and each like belongs to one likeable.
+For performance, a likeable has a counter cache of likes.
+
+[source,ascii]
+----
++----------------------+
+|  Decidim::Likeable |
+|   ((Proposal,...))   |
++----------------------+  0..N +--------------------+
+|-has_many likes|-------+Decidim::Like|
+|#counter cache column |       +--------------------+   +-------------+
+|-likes_counter |       |-author: a user     |<--+Decidim::User|
++----------------------+       +--------------------+   +-------------+
+----
+
+Thus, each likeable must have the likes counter cache column.
+This is an example migration to add the likes counter cache column to a resource:
+
+[source,ruby]
+----
+class AddLikesCounterCacheToProposals < ActiveRecord::Migration[5.2]
+  def change
+    add_column :decidim_proposals_proposals, :likes_count, :integer, null: false, default: 0
+  end
+end
+----
+
+== Administration Panel
+
+It is a good practice to give the opportunity to the admin to switch Likes on and off.
+
+There are two switches that are normally defined in the manifest of the element in the following way (usually this would be at component.rb in a Decidim engine):
+
+[source,ruby]
+----
+    settings.attribute :likes_enabled, type: :boolean, default: true
+    settings.attribute :likes_blocked, type: :boolean
+----
+
+* `likes_enabled`: when enabled like functionality appears in the public views, when disabled, this functionality is hidden.
+* `likes_blocked`: when blocked, the counter of likes is visible but no more likes can be added or withdrawn, the button is hidden.
+
+== Permissions
+
+In some cases, it may be interesting to require the user to be verified in order to be able to like. To do so, add the like action to the component manifest:
+
+[source,ruby]
+----
+  component.actions = %w(like vote create withdraw amend)
+----
+
+Given that some settings have been defined in the Administration Panel, for the user to have permissions to like likes should be enabled and not blocked.
+
+== Public view
+
+=== The "Like" buttons cell
+
+It normally appears in the resource detail view (show), at the bottom of the resource content, but above the comments when comments are enabled.
+It allows users to like with any of their personal identity.
+It also shows the current number of likes for this resource.
+
+To render this button, `decidim-core` offers the `decidim/like_buttons` cell. It is strongly recommended to use this cell to make new resources likeable.
+
+[source,ruby]
+----
+cell("decidim/like_buttons", resource)
+----
+
+This cell will render the like buttons depending on whether user liked the resource or not. The likes are labeled as *Likes*.
+
+[source,ruby]
+----
+# By default the `show` method is invoked as usual
+# Renders `render_likes_count` and `render_likes_button` in a block.
+#
+# It takes into account:
+# - if likes are enabled
+# - if users are logged in
+# - if users require verification
+ #
+cell("decidim/like_buttons", resource)
+----
+
+=== The list of likes
+
+The `Decidim::LikersListCell` renders the list of likes of a resource. It is usually rendered in the show page of the resource, just upside the comments. Additionally, this cell also renders the pop-up required to view the likes of a certain resource.
+
+[source,ruby]
+----
+# to render the list of likes, the cell requires the likeable resource, and the current user
+cell "decidim/likers_list", resource
+# or using the helper
+likers_list_cell(resource)
+----

data/docs/modules/develop/pages/machine_translations.adoc

@@ -16,8 +16,12 @@ This workflow will only start if the machine translation service is configured i
 == Create your own machine translation service
 
 You can use the `Decidim::Dev::DummyTranslator` service as a base. Any new translator service will need to implement the same API as this class.
-In order to test the `Decidim::Dev::DummyTranslator` you will need to add at the top of `config/initializers/decidim.rb` the following line:
-`require "decidim/dev/dummy_translator"`
+In order to test the `Decidim::Dev::DummyTranslator` you will need to set the `DECIDIM_MACHINE_TRANSLATION_SERVICE` environment variable.
+
+[source,bash]
+----
+export DECIDIM_MACHINE_TRANSLATION_SERVICE="Decidim::Dev::DummyTranslator"
+----
 
 == Integrating with async services