decidim 0.23.6 → 0.24.0.rc1

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

@@ -0,0 +1,119 @@
+= Metrics
+
+Metrics calculations must be executed everyday. Some `rake task` have been added to perform it.
+
+* To execute all metrics at once. Related to previous date from _today_
++
+[source,ruby]
+----
+bundle exec rake decidim:metrics:all
+----
+
+* To execute an specific metric. Related to previous date from _today_
++
+[source,ruby]
+----
+bundle exec rake decidim:metrics:one["<metric name>"]
+----
+
+* To execute metrics for a given date (all or an specific one)
++
+[source,ruby]
+----
+bundle exec rake decidim:metrics:all["YYYY-MM-DD"]
+bundle exec rake decidim:metrics:one["<metric name>","YYYY-MM-DD"]
+----
+
+* It is possible to rebuild one or all metrics since some specific day. This is useful in case current metrics are no generated or corrupt. *Depending on the size of the database this can take a long time!*. The command will execute the same calculations as the commands above for *each* day between _today_ and the date specified.
+* To rebuild metrics since a given date (all or an specific one)
++
+[source,ruby]
+----
+bundle exec rake decidim:metrics:rebuild["YYYY-MM-DD"]
+bundle exec rake decidim:metrics:rebuild["<metric name>","YYYY-MM-DD"]
+----
+
+== Available metrics
+
+* Use the command `decidim:metrics:list` to list all available metrics using the console:
+
+[source,ruby]
+----
+bundle exec rake decidim:metrics:list
+----
+
+Currently, available metrics are:
+
+* *users*, created `Users`
+* *proposals*, published, not withdrawn and not _hidden_ `Proposals`
+* *accepted_proposals*, accepted `Proposals`
+* *supports*, supports given to `Proposals`
+* *assemblies*, published `Assemblies`
+* *participatory_processes*, published `ParticipatoryProcesses`
+* *results*, `Results` in `Accountability`
+* *comments*, `Comments` generated by users, related to public elements and not _hidden_
+* *meetings*, public `Meetings`
+
+Only available for `ParticipatorySpaces` (restricted to `ParticipatoryProcesses`)
+
+* *participants*, unique users who make at least one of the following actions:
+ ** Answer a survey
+ ** Create a debate
+ ** Create a proposal
+ ** Endorse a proposal
+ ** Leave a comment
+ ** Support a proposal
+ ** Vote a participatory budgeting project
+* *followers*, unique users who follow any participatory element in a `ParticipatorySpace`
+* *endorsements*, number of `Endorsements` in `Proposals`, within a `ParticipatorySpace`
+* *debates*, number of `Debates` within a `ParticipatorySpace`
+* *survey_answers*, number of answered `Surveys` by users within a `ParticipatorySpace`
+
+== Configuration
+
+* A *crontab* line must be added to your server to maintain them updated daily. You could use https://github.com/javan/whenever[Whenever] to manage it directly from the APP. You probably want to schedule a `bundle exec rake decidim:metrics:all` every night.
+* An *ActiveJob* queue, like https://github.com/mperham/sidekiq[Sidekiq] or https://github.com/collectiveidea/delayed_job/[DelayedJob]
+
+== Persistence
+
+The metrics module percomutes calculations and persists them into
+`decidim_metrics` database table. So this module only uses one single table to
+persist metrics from all times and types.
+
+The `decidim_metrics` table has the following fields:
+
+* `day`: the day for which the metric has been computed.
+* `metric_type`: the type of the metric. One of: users, proposals, accepted_proposals, supports, assemblies.
+* `cumulative`: quantity accumulated to day `"day`".
+* `quantity`:  quantity for the current day, `"day`".
+* `decidim_organization_id`: the FK to the organization to which this Metric belongs to.
+* `participatory_space_type` + `participatory_space_id`: the FK to the participatory space to which this Metric belongs to, if any.
+* `related_object_type` + `related_object_id`: the FK to the object to which this Metric belongs to, if any.
+* `decidim_category_id`: the FK to the category for this Metric, if any.
+
+Relations around `decidim_metrics` table:
+
+[source,ascii]
+----
+                                                    +------------------------+
++--------------+                                    | ParticipatoryProcesses |
+| Organization |                               +----+------------------------+
++------+-------+                               |
+       |            +--------------------+     |    +------------+
+       |            |                    |     +----+ Assemblies |
+       |     +----->+ ParticipatorySpace +<----+    +------------+
+       |     |      |                    |     |    +-------------+
+       |     |      +--------------------+     +----+ Initiatives |
+       |     |                                 |    +-------------+
+       |     |                                 |
+       |     |                                 |    +---------------+
+ +-----+-------+---+                           +----+ Consultations |
+ |                 |                                +---------------+
+ | decidim_metrics |
+ |                 |
+ +--------+--------+       +----------------+
+          |                | related_object |
+          +--------------->+                |
+                           | [polymorphic]  |
+                           +----------------+
+----

data/docs/{advanced/modules.md → modules/develop/pages/modules.adoc}

@@ -1,15 +1,26 @@
-# Modules
+= Modules
 
 Modules are subapplications that are run as application plugins.
 They're used to define pieces of functionality that are pluggable to Decidim.
 
 Decidim's modules are no more than Ruby on Rails engines that should be required in the application's `Gemfile`.
 
-## Example
+You can see some of our more popular modules at https://decidim.org/modules[Decidim's Modules].
+
+== Types
+
+You can have multiple modules types:
+
+* For Spaces
+* For xref:develop:components.adoc[Components]
+* For Verifications
+
+== Example
 
 A typical engine looks like the following:
 
-```ruby
+[source,ruby]
+----
 module Decidim
   module Verifications
     module MyVerifier
@@ -39,14 +50,13 @@ module Decidim
     end
   end
 end
-```
+----
 
 It is a standard Ruby on Rails engine.
 
-## Decidim gotchas with engines
+== Decidim gotchas with engines
 
 If you have an external module that defines rake tasks and more than one
 engine, you probably want to add `paths["lib/tasks"]= nil` to all engines but
 the main one, otherwise the tasks you define are probably running multiple
 times unintentionally. Check #3892 for more details.
-

data/docs/{advanced/newsletter_templates.md → modules/develop/pages/newsletter_templates.adoc}

@@ -1,14 +1,15 @@
-# Newsletter templates
+= Newsletter templates
 
 The newsletter templates allow the user to select a template amongst a set of of them, and use it as base to send newsletters. This allow for more customization on newsletter, tematic newsletters, etc.
 
-Code-wise, they use the content blocks system internally, so [check the docs](https://github.com/decidim/decidim/blob/master/docs/advanced/content_blocks.md) for that section first.
+Code-wise, they use the content blocks system internally, so https://github.com/decidim/decidim/blob/develop/docs/advanced/content_blocks.md[check the docs] for that section first.
 
-## Adding a new template
+== Adding a new template
 
 You'll first need to register the template as a content block, but specifying `:newsletter_template` as its scope:
 
-```ruby
+[source,ruby]
+----
 Decidim.content_blocks.register(:newsletter_template, :my_template) do |content_block|
   content_block.cell "decidim/newsletter_templates/my_template"
   content_block.settings_form_cell = "decidim/newsletter_templates/my_template_settings_form"
@@ -31,7 +32,7 @@ Decidim.content_blocks.register(:newsletter_template, :my_template) do |content_
     )
   end
 end
-```
+----
 
 You'll need to add this into an initializer. Note that if you're adding this from a module, then you need to add it from the `engine.rb` file (check the docs for content blocks for more info).
 
@@ -43,15 +44,16 @@ Then we define the cell that will be used to render the form in the admin sectio
 
 In the third line inside the block we define the I18n path to the public name of the template. This name will serve as identifier for the users who write the newsletters, so be sure to make it descriptive.
 
-After that we define the images this newsletter supports. We give it a unique name, the class name of the uploader we'll use (the example one is the default one, but you might want to customize this value) and a way to preview this image. This preview image will only be used in the "Preview" page of the template, it's not a fallback. If you want a fallback, please implement it through a custom uploader (see `carrierwave`'s docs for that). There's no limit of the amount of images you add.
+After that we define the images this newsletter supports. We give it a unique name, the class name of the uploader we'll use (the example one is the default one, but you might want to customize this value) and a way to preview this image. This preview image will only be used in the "Preview" page of the template, it's not a fallback. If you want a fallback, please implement it through a custom uploader (see ``carrierwave``'s docs for that). There's no limit of the amount of images you add.
 
 Finally, we define the attributes for the newsletter. In this case we define a body attribute, which is a translatable text. Whether this text require an editor or not will be defined by the settings cell. We also have a way to preview that attribute. There's no limit on the number of attributes you define.
 
-## Interpolating the recipient name
+== Interpolating the recipient name
 
-Decidim accepts `%{name}` as a placeholder for the recipient name. If you want your template to use it, you'll need to call `parse_interpolations` in your public cell:
+Decidim accepts `+%{name}+` as a placeholder for the recipient name. If you want your template to use it, you'll need to call `parse_interpolations` in your public cell:
 
-```ruby
+[source,ruby]
+----
 class Decidim::NewsletterTemplates::MyTemplate < Decidim::ViewModel
   include Decidim::NewslettersHelper
 
@@ -59,6 +61,6 @@ class Decidim::NewsletterTemplates::MyTemplate < Decidim::ViewModel
     parse_interpolations(uninterpolated_body, recipient_user, newsletter.id)
   end
 end
-```
+----
 
 The newsletter subject is automatically interpolated.

data/docs/{advanced/notifications.md → modules/develop/pages/notifications.adoc}

@@ -1,19 +1,20 @@
-# Notifications
+= Notifications
 
 In Decidim, notifications may mean two things:
 
-- he concept of notifying an event to a user. This is the wider use of "notification".
-- the notification's participant space, which lists the `Decidim::Notification`s she has received.
+* he concept of notifying an event to a user. This is the wider use of "notification".
+* the notification's participant space, which lists the ``Decidim::Notification``s she has received.
 
 So, in the wider sense, notifications are messages that are sent to the users, admins or participants, when something interesting occurs in the platform.
 
 Each notification is sent via two communication channels: email and internal notifications.
 
-## A Decidim Event
+== A Decidim Event
 
 Technically, a Decidim event is nothing but an `ActiveSupport::Notification` with a payload of the form
 
-```ruby
+[source,ruby]
+----
 ActiveSupport::Notifications.publish(
   event,
   event_class: event_class.name,
@@ -22,11 +23,12 @@ ActiveSupport::Notifications.publish(
   followers: followers.uniq.compact,
   extra: extra
 )
-```
+----
 
 To publish an event to send a notification, Decidim's `EventManager` should be used:
 
-```ruby
+[source,ruby]
+----
 # Note the convention between the `event` key, and the `event_class` that will be used later to wrap the payload and be used as the email or notification model.
 data = {
   event: "decidim.events.comments.comment_created",
@@ -40,75 +42,75 @@ data = {
 }
 
 Decidim::EventsManager.publish(data)
-```
+----
 
 Both, `EmailNotificationGenerator` and `NotificationGenerator` are use the same arguments:
 
-- **event**: A String with the name of the event.
-- **event_class**: A class that wraps the event.
-- **resource**: an instance of a class implementing the `Decidim::Resource` concern.
-- **followers**: a collection of Users that receive the notification because they're following it.
-- **affected_users**: a collection of Users that receive the notification because they're affected by it.
-- **force_send**: boolean indicating if EventPublisherJob should skip the `notifiable?` check it performs before notifying.
-- **extra**: a Hash with extra information to be included in the notification.
+* *event*: A String with the name of the event.
+* *event_class*: A class that wraps the event.
+* *resource*: an instance of a class implementing the `Decidim::Resource` concern.
+* *followers*: a collection of Users that receive the notification because they're following it.
+* *affected_users*: a collection of Users that receive the notification because they're affected by it.
+* *force_send*: boolean indicating if EventPublisherJob should skip the `notifiable?` check it performs before notifying.
+* *extra*: a Hash with extra information to be included in the notification.
 
 Again, both generators will check for each user
 
-- in the *followers* array, if she has the `notification_types` set to "all" or "followed-only".
-- in the *affected_users* array, if she has the `notification_types` set to "all" or "own-only".
+* in the _followers_ array, if she has the `notification_types` set to "all" or "followed-only".
+* in the _affected_users_ array, if she has the `notification_types` set to "all" or "own-only".
 
 Event names must start with "decidim.events." (the `event` data key). This way `Decidim::EventPublisherJob` will automatically process them. Otherwise no artifact in Decidim will process them, and will be the developer's responsibility to subscribe to them and process.
 
 Sometimes, when something that must be notified to users happen, a service is defined to manage the logic involved to decide which events should be published. See for example `Decidim::Comments::NewCommentNotificationCreator`.
 
-Please refer to [Ruby on Rails Notifications documentation](https://api.rubyonrails.org/classes/ActiveSupport/Notifications.html) if you need to hack the Decidim's events system.
+Please refer to https://api.rubyonrails.org/classes/ActiveSupport/Notifications.html[Ruby on Rails Notifications documentation] if you need to hack the Decidim's events system.
 
-## How Decidim's `EventPublisherJob` processes the events?
+== How Decidim's `EventPublisherJob` processes the events?
 
-The `EventPublisherJob` in Decidim's core engine subscribes to all notifications matching the regular expression `/^decidim\.events\./`. This is, starting with "decidim.events.". It will then be invoked when an imaginary event named "decidim.events.harmonica_blues" is published.
+The `EventPublisherJob` in Decidim's core engine subscribes to all notifications matching the regular expression `+/^decidim\.events\./+`. This is, starting with "decidim.events.". It will then be invoked when an imaginary event named "decidim.events.harmonica_blues" is published.
 
 When invoked it simply performs some validations and enqueue an `EmailNotificationGeneratorJob` and a `NotificationGeneratorJob`.
 
 The validations it performs check if the resource, the component, or the participatory space are published (when the concept applies to the artifact).
 
-## The \*Event class
+== The *Event class
 
 Generates the email and notification messages from the information related with the notification.
 
 Event classes are subclasses of `Decidim::Events::SimpleEvent`.
 A subset of the payload of the notification is passed to the event class's constructor:
 
-- The `resource`
-- The `event` name
-- The notified user, either from the `followers` or from the `affected_users` arrays
-- The `extra` hash, with content specific for the given SimpleEvent subclass
-- The user_role, either :follower or :affected_user
+* The `resource`
+* The `event` name
+* The notified user, either from the `followers` or from the `affected_users` arrays
+* The `extra` hash, with content specific for the given SimpleEvent subclass
+* The user_role, either :follower or :affected_user
 
 With the previous information the event class is able to generate the following contents.
 
 Developers will be able to customize those messages by adding translations to the `config/locales/en.yml` file of the corresponding module.
 The keys to be used will have the translation scope corresponding to the event name ("decidim.events.comments.comment_by_followed_user" for example) and the key will be the content to override (email_subject, email_intro, etc.)
 
-### Email contents
+=== Email contents
 
 The following are the parts of the notification email:
 
-- *email_subject*, to be customized
-- email_greeting, with a good default, usually there's no need to cusomize it
-- *email_intro*, to be customized
-- *resource_text* (optional), rendered `html_safe` if present
-- *resource_url*, a link to the involved resource if resource_url and resource_title are present
-- *email_outro*
+* _email_subject_, to be customized
+* email_greeting, with a good default, usually there's no need to cusomize it
+* _email_intro_, to be customized
+* _resource_text_ (optional), rendered `html_safe` if present
+* _resource_url_, a link to the involved resource if resource_url and resource_title are present
+* _email_outro_
 
 All contents except the `email_greeting` use to require customization on each notification.
 
-### Notification contents
+=== Notification contents
 
 Only the `notification_title` is generated in the event class. The rest of the contents are produced by the templates from the `resource` and the `notification` objects.
 
-## Testing notifications
+== Testing notifications
 
-- Test that the event has been published (usually a command test)
-- Test the event returns the expected contents for the email and the notification.
+* Test that the event has been published (usually a command test)
+* Test the event returns the expected contents for the email and the notification.
 
-Developers should we aware when adding URLs in the email's content, be sure to use absolute URLs and not relative paths.
+Developers should we aware when adding URLs in the email's content, be sure to use absolute URLs and not relative paths.

data/docs/{advanced/open-data.md → modules/develop/pages/open-data.adoc}

@@ -1,9 +1,10 @@
-# Open Data
+= Open Data
 
 In order for users to be able to download Open Data files they have to be generated previously, since generating them on the fly would take too much time and resources.
 
 You should schedule this command to be run everyday, using `cron` or `whenever` or your favorite tool:
 
-```ruby
+[source,ruby]
+----
   bundle exec rake decidim:open_data:export
-```
+----

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

@@ -0,0 +1,92 @@
+= Permissions
+
+Since Decidim has multiple roles, we needed a permissions system to discover what actions can a user perform, given their roles. The basis of the current permissions system were added on https://github.com/decidim/decidim/pull/3029[#3029], so be sure to check that PR (and the related ones) to read the discussion and the motivations behind the change.
+
+== Overview
+
+When checking for permission to perform an action, we check this chain:
+
+. The component permissions
+. The participatory space permissions
+. The core permissions
+
+This way we're going from more specific to more general.
+
+== Explanation
+
+We wrap the permission and its context in a `PermissionsAction` object. It also holds the state of the permission (whether it's been allowed or not).
+
+Each component and space must define a `Permissions` class, inheriting from `Decidim::DefaultPermissions`. The `Permissions` class must define a `permissions` instance method. this class will receive the permission action, and the `permissions` method must return the permission action. The `Permissions` class can set the action as allowed or disallowed.
+
+There's a small limitation in the permission action state machine: once it's been disallowed it can't be reallowed. This is to avoid mischievous modules modifying permissions.
+
+Permission actions have a scope. It's usually either `:public` or `:admin`, and the `Permissions` class usually handles the `:public` scope, while it delegates the `:admin` one to another specialized class.
+
+== Add a new Action
+
+=== Proposals example
+
+We're going to reproduce the steps to add an action (endorse) for a proposal step by step.
+
+==== Configuring a new 'endorse' action
+
+. Edit decidim-proposals/lib/decidim/proposals/component.rb
+. Add the new 'endorse' action into the `component.actions` array and save the file:
+
+[source,ruby]
+----
+component.actions = %w(endorse vote create)
+----
+
+. Translate the action for the corresponding key: `en.decidim.components.proposals.actions.endorse = Endorse`
+. Edit `app/permissions/decidim/proposals/permissions.rb` and add the corresponding permission, using `authorized?` method to run the `authorization handler` logic.
+. In the endorse proposals controller, enforce that the user has permissions to perform the `endorse` action before actually doing it, using the `enforce_permission_to` method:
+
+[source,ruby]
+----
+enforce_permission_to :endorse, :proposal, proposal: proposal
+----
+
+. In the proposals templates, change regular links and buttons to endorse a proposal with calls to `action_authorized_link_to` and `action_authorized_button_to` helpers.
+. Restart the server to pick up the changes.
+
+==== Using the new 'endorse' action
+
+. Now an admin user should be able to go to a participatory space with a `proposals` component panel and click on its `Permissions` link (the icon with a key). There, an `authorization handler` can be set for the `endorse` action.
+. Go to a Proposal detail in the front-end
+. Try to endorse the current proposal
+ ** If the user has not granted the selected permission, the 'endorse' button should block the action and allow the user to grant the permission with the selected `authorization handler` logic.
+ ** If the logger user has already granted the selected permission, the user should be able to perform the endorsement.
+
+==== Allow to configure the related permissions at resource level
+
+Permissions settings could also be set for an specific resources appart from the full component. Actions should also be related to the resource.
+
+. Edit decidim-proposals/lib/decidim/proposals/component.rb
+. Add the 'endorse' action into the `resource.actions` array for the `proposal` resource definition and save the file:
+
+[source,ruby]
+----
+resource.actions = %w(endorse vote)
+----
+
+. Only if this is the first resource action added, edit the proposals admin templates and use the `resource_permissions_link` helper to link the resource permissions page from each resource in the listing.
+
+[source,erb]
+----
+<%= resource_permissions_link(proposal) %>
+----
+
+. In the proposals permission class, pass an extra `resource` named parameter to the calls to the `authorized?` method.
+
+[source,ruby]
+----
+authorized?(:endorse, resource: proposal)
+----
+
+. In the proposals templates, also add the extra `resource` parameter to the `action_authorized_link_to` and `action_authorized_button_to` helpers.
+. Restart the server to pick up the changes.
+
+==== Using permissions at resource level
+
+. Now an admin user should be able to go to a participatory space with a `proposals` component panel and click on its `Permissions` link (the icon with a key). There, an `authorization handler` can be set for the `endorse` action.