decidim-action_delegator 0.4

data/README.md

@@ -0,0 +1,225 @@
+# Decidim::ActionDelegator
+
+![[CI] Build](https://github.com/coopdevs/decidim-module-action_delegator/workflows/%5BCI%5D%20Build/badge.svg)
+[![Maintainability](https://api.codeclimate.com/v1/badges/6ec3c39e8dc2075808e1/maintainability)](https://codeclimate.com/github/coopdevs/decidim-module-action_delegator/maintainability)
+[![Codecov](https://codecov.io/gh/coopdevs/decidim-module-action_delegator/branch/master/graph/badge.svg)](https://codecov.io/gh/coopdevs/decidim-module-action_delegator)
+
+
+A tool for Decidim that provides extended functionalities for cooperatives.
+
+Combines a CSV-like verification method with impersonation capabilities that allow users to delegate some actions to others.
+
+Admin can set limits to the number of delegation per users an other characteristics.
+
+Initially, only votes can be delegated.
+
+## Dependencies
+
+* [decidim-consultations](https://github.com/decidim/decidim/tree/master/decidim-consultations) >= v0.24.0
+* [decidim-admin](https://github.com/decidim/decidim/tree/master/decidim-admin) >= v0.24.0
+* [decidim-core](https://github.com/decidim/decidim/tree/master/decidim-core) >= v0.24.0
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "decidim-action_delegator"
+```
+
+And then execute:
+
+```bash
+bundle
+bundle exec rails decidim_action_delegator:install:migrations
+bundle exec rails db:migrate
+```
+
+Depending on your Decidim version, choose the corresponding version to ensure compatibility:
+
+| Version | Compatible Decidim versions |
+|---|---|
+| 0.4 | 0.24.x |
+| 0.3 | 0.24.x |
+| 0.2 | 0.23.x |
+| 0.1 | 0.22.0 |
+
+> *Heads up!*  [Consultations module will be deprecated in the near future.](https://github.com/decidim/decidim/issues/7097)
+
+## Usage
+
+ActionDelegator does not provides new Components or Participatory Spaces but enhances some functionalities in them.
+
+### Extended consultation results
+
+This gem modifies the consultation's results page adding two extra columns
+`Membership type` and `Membership weight`. This requires a Decidim verification
+that creates `decidim_authorizations` records which include the following JSON
+structure in the `metadata` column:
+
+```json
+"{ membership_type: '', membership_weight: '' }"
+```
+
+See https://github.com/Platoniq/decidim-verifications-direct_verifications/pull/2
+as an example of such verification.
+
+### SMS gateway setup
+
+In order to use this new sms gateway you need to configure your application. In config/initializers/decidim.rb set:
+
+```ruby
+config.sms_gateway_service = 'Decidim::ActionDelegator::SmsGateway'
+
+```
+#### Som Connexió
+
+You can use Som Connexió as SMS provider which uses [this SOAP API](https://websms.masmovil.com/api_php/smsvirtual.wsdl). Reach out to Som Connexió to sign up first.
+
+Then you'll need to set the following ENV vars:
+
+```bash
+SMS_USER= # Username provided by Som Connexió
+SMS_PASS= # Password provided by Som Connexió
+SMS_SENDER= # (optional) Name or phone number used as sender of the SMS
+```
+
+#### Twilio
+
+Alternatively, you can use Twilio as provider by specifying the folowing ENV vars
+
+```bash
+TWILIO_ACCOUNT_SID # SID from your Twilio account
+TWILIO_AUTH_TOKEN # Token from your Twilio account
+SMS_SENDER # Twilio's phone number. You need to purchase one there with SMS capability.
+```
+
+### Track delegated votes and unvotes
+
+Votes and revocations done on behalf of other members are tracked through the
+`versions` table using `PaperTrail`. This enables fetching a log of actions
+involving a particular delegation or consultation for auditing purposes. This
+keeps out regular votes and unvotes.
+
+When performing votes and unvotes of delegations you'll see things like the
+following in your `versions` table:
+
+```sql
+  id  |          item_type           | item_id |  event  | whodunnit | decidim_action_delegator_delegation_id 
+------+------------------------------+---------+---------+-----------+----------------------------------------
+ 2019 | Decidim::Consultations::Vote |     143 | destroy | 1         |                                     22
+ 2018 | Decidim::Consultations::Vote |     143 | create  | 1         |                                     22
+ 2017 | Decidim::Consultations::Vote |     142 | create  | 1         |                                     23
+ 2016 | Decidim::Consultations::Vote |     138 | destroy | 1         |                                     23
+```
+
+Note that the `item_type` is `Decidim::Consultations::Vote` and `whoddunit`
+refers to a `Decidim::User` record. This enables joining `versions` and
+`decidim_users` tables although this doesn't follow Decidim's convention of
+using gids, such as `gid://decidim/Decidim::User/1`.
+
+You can use `Decidim::ActionDelegato::DelegatedVotesVersions` query object for
+that matter.
+
+## Contributing
+
+See [Decidim](https://github.com/decidim/decidim).
+
+### Developing
+
+To start contributing to this project, first:
+
+- Install the basic dependencies (such as Ruby and PostgreSQL)
+- Clone this repository
+
+Decidim's main repository also provides a Docker configuration file if you
+prefer to use Docker instead of installing the dependencies locally on your
+machine.
+
+You can create the development app by running the following commands after
+cloning this project:
+
+```bash
+bundle
+DATABASE_USERNAME=<username> DATABASE_PASSWORD=<password> bundle exec rake development_app
+```
+
+Note that the database user has to have rights to create and drop a database in
+order to create the dummy test app database.
+
+Then to test how the module works in Decidim, start the development server:
+
+```bash
+cd development_app
+DATABASE_USERNAME=<username> DATABASE_PASSWORD=<password> bundle exec rails s
+```
+
+In case you are using [rbenv](https://github.com/rbenv/rbenv) and have the
+[rbenv-vars](https://github.com/rbenv/rbenv-vars) plugin installed for it, you
+can add the environment variables to the root directory of the project in a file
+named `.rbenv-vars`. If these are defined for the environment, you can omit
+defining these in the commands shown above.
+
+#### Code Styling
+
+Please follow the code styling defined by the different linters that ensure we
+are all talking with the same language collaborating on the same project. This
+project is set to follow the same rules that Decidim itself follows.
+
+[Rubocop](https://rubocop.readthedocs.io/) linter is used for the Ruby language.
+
+You can run the code styling checks by running the following commands from the
+console:
+
+```bash
+bundle exec rubocop
+```
+
+To ease up following the style guide, you should install the plugin to your
+favorite editor, such as:
+
+- Atom - [linter-rubocop](https://atom.io/packages/linter-rubocop)
+- Sublime Text - [Sublime RuboCop](https://github.com/pderichs/sublime_rubocop)
+- Visual Studio Code - [Rubocop for Visual Studio Code](https://github.com/misogi/vscode-ruby-rubocop)
+
+### Testing
+
+To run the tests run the following in the gem development path:
+
+```bash
+bundle
+DATABASE_USERNAME=<username> DATABASE_PASSWORD=<password> bundle exec rake test_app
+DATABASE_USERNAME=<username> DATABASE_PASSWORD=<password> bundle exec rspec
+```
+
+Note that the database user has to have rights to create and drop a database in
+order to create the dummy test app database.
+
+In case you are using [rbenv](https://github.com/rbenv/rbenv) and have the
+[rbenv-vars](https://github.com/rbenv/rbenv-vars) plugin installed for it, you
+can add these environment variables to the root directory of the project in a
+file named `.rbenv-vars`. In this case, you can omit defining these in the
+commands shown above.
+
+### Test code coverage
+
+If you want to generate the code coverage report for the tests, you can use
+the `SIMPLECOV=1` environment variable in the rspec command as follows:
+
+```bash
+SIMPLECOV=1 bundle exec rspec
+```
+
+### Localization
+
+If you would like to see this module in your own language, you can help with its
+translation at Crowdin:
+
+https://crowdin.com/project/decidim-action-delegator-vote
+
+This will generate a folder named `coverage` in the project root which contains
+the code coverage report.
+
+## License
+
+This engine is distributed under the GNU AFFERO GENERAL PUBLIC LICENSE.

data/Rakefile

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "decidim/dev/common_rake"
+
+def install_module(path)
+  Dir.chdir(path) do
+    system("bundle exec rake decidim_consultations:install:migrations")
+    system("bundle exec rake decidim_action_delegator:install:migrations")
+    system("bundle exec rake db:migrate")
+  end
+end
+
+def seed_db(path)
+  Dir.chdir(path) do
+    system("bundle exec rake db:seed")
+  end
+end
+
+desc "Generates a dummy app for testing"
+task test_app: "decidim:generate_external_test_app" do
+  ENV["RAILS_ENV"] = "test"
+  install_module("spec/decidim_dummy_app")
+end
+
+desc "Generates a development app."
+task :development_app do
+  Bundler.with_original_env do
+    generate_decidim_app(
+      "development_app",
+      "--app_name",
+      "#{base_app_name}_development_app",
+      "--path",
+      "..",
+      "--recreate_db",
+      "--demo"
+    )
+  end
+
+  install_module("development_app")
+  seed_db("development_app")
+end

data/app/assets/config/admin/decidim_action_delegator_manifest.js

@@ -0,0 +1 @@
+//= link decidim/action_delegator/admin/action_delegator.js

data/app/assets/config/decidim_action_delegator_manifest.css

@@ -0,0 +1,3 @@
+/*
+ *= link decidim/action_delegator/questions.css
+ */

data/app/assets/config/decidim_action_delegator_manifest.js

@@ -0,0 +1,2 @@
+//= link decidim/action_delegator/admin/action_delegator.js
+//= link decidim/action_delegator/questions.js

data/app/assets/images/decidim/action_delegator/icon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 35 35"><path d="M17.5 35A17.5 17.5 0 1 1 35 17.5 17.52 17.52 0 0 1 17.5 35zm0-33.06A15.56 15.56 0 1 0 33.06 17.5 15.57 15.57 0 0 0 17.5 1.94zm9.5 13.7H8a1 1 0 0 1 0-1.94h19a1 1 0 0 1 0 1.94zm0 3.68H8a1 1 0 0 1 0-1.94h19a1 1 0 0 1 0 1.94zM22.26 23H8a1 1 0 0 1 0-1.94h14.26a1 1 0 0 1 0 1.94z"/></svg>

data/app/assets/javascripts/decidim/action_delegator/admin/action_delegator.js.es6

@@ -0,0 +1,3 @@
+((exports) => {
+  // Nothing here yet
+})(window);

data/app/assets/javascripts/decidim/action_delegator/questions.js.es6

@@ -0,0 +1,26 @@
+$(() => {
+  const voteButton = $("#vote_button"),
+        delegationsButton = $("#delegations-button"),
+        delegationCallouts = $(".delegation-callout"),
+        delegationCalloutsMessage = $(".delegation-callout-message"),
+        delegationDialog = $("#delegations-modal"),
+        delegationVoteButtons = $(".delegation-vote-button"),
+        delegationField = $("#decidim_consultations_delegation_id"),
+        voteDialog = $("#question-vote-modal");
+
+  delegationsButton.click(() => {
+    delegationDialog.foundation("open");
+  });
+
+  delegationVoteButtons.click((e) => {
+    delegationDialog.foundation("close");
+    voteDialog.foundation("open");
+    delegationField.val($(e.currentTarget).data("delegation-id"));
+    delegationCalloutsMessage.text($(e.currentTarget).data("delegation-granter-name"));
+    delegationCallouts.removeClass("is-hidden");
+  });
+
+  voteButton.click(() => {
+    delegationCallouts.addClass("is-hidden");
+  });
+});

data/app/assets/stylesheets/decidim/action_delegator/questions.scss

@@ -0,0 +1,25 @@
+.delegations-notice {
+  a {
+    color: white;
+    background:rgba(0,0,0,0.5);
+    line-height: 1;
+    text-align: center;
+    padding: 0.5em;
+  }
+}
+
+.question-vote-cabin {
+  .delegations-notice {
+    a {
+      color: var(--secondary);
+      font-weight: 600;
+      background:transparent;
+    }
+  }
+}
+
+#delegations-modal {
+  .vote-button-caption {
+    font-weight: bold;
+  }
+}

data/app/commands/decidim/action_delegator/admin/create_delegation.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Decidim
+  module ActionDelegator
+    module Admin
+      class CreateDelegation < Rectify::Command
+        # Public: Initializes the command.
+        #
+        # form         - A form object with the params.
+        # delegated_by - The user performing the operation
+        def initialize(form, performed_by, current_setting)
+          @form = form
+          @performed_by = performed_by
+          @current_setting = current_setting
+        end
+
+        # Executes the command. Broadcasts these events:
+        #
+        # - :ok when everything is valid.
+        # - :invalid if the form wasn't valid and we couldn't proceed.
+        #
+        # Returns nothing.
+        def call
+          return broadcast(:error, generic_error_message) if form.invalid? || current_setting.nil?
+          return broadcast(:error, above_max_grants_error_message) if above_max_grants?
+
+          create_delegation
+
+          return broadcast(:ok) if delegation.persisted?
+
+          broadcast(:error, delegation.errors.full_messages.first)
+        end
+
+        private
+
+        attr_reader :form, :performed_by, :current_setting, :delegation
+
+        def above_max_grants?
+          grants_count >= current_setting.max_grants
+        end
+
+        def above_max_grants_error_message
+          I18n.t("delegations.create.error_max_grants", scope: "decidim.action_delegator.admin")
+        end
+
+        def generic_error_message
+          I18n.t("delegations.create.error", scope: "decidim.action_delegator.admin")
+        end
+
+        def grants_count
+          SettingDelegations.new(current_setting).query
+                            .where(grantee_id: form.grantee_id)
+                            .count
+        end
+
+        def create_delegation
+          @delegation = Delegation.create(form.attributes.merge(setting: current_setting))
+        end
+      end
+    end
+  end
+end

data/app/commands/decidim/action_delegator/consultations/multiple_vote_question_override.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# Recreate validations to take into account custom fields and ignore the length limit in proposals
+module Decidim
+  module ActionDelegator
+    module Consultations
+      module MultipleVoteQuestionOverride
+        extend ActiveSupport::Concern
+        include VoteQuestionOverride
+
+        included do
+          private
+
+          def create_vote!(vote_form)
+            vote = if delegation
+                     form.context.delegation = delegation
+                     Decidim::ActionDelegator::VoteDelegation.new(vote_form.response, form.context).call
+                   else
+                     normal_vote = form.context.current_question.votes.build(
+                       author: @current_user,
+                       response: vote_form.response
+                     )
+                     Decidim::ActionDelegator::UnversionedVote.new(normal_vote)
+                   end
+            vote.save!
+          end
+        end
+      end
+    end
+  end
+end

data/app/commands/decidim/action_delegator/consultations/vote_question_override.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# Recreate validations to take into account custom fields and ignore the length limit in proposals
+module Decidim
+  module ActionDelegator
+    module Consultations
+      module VoteQuestionOverride
+        extend ActiveSupport::Concern
+
+        included do
+          private
+
+          def build_vote
+            if delegation
+              form.context.delegation = delegation
+              Decidim::ActionDelegator::VoteDelegation.new(form.response, form.context).call
+            else
+              vote = form.context.current_question.votes.build(
+                author: form.context.current_user,
+                response: form.response
+              )
+              Decidim::ActionDelegator::UnversionedVote.new(vote)
+            end
+          end
+
+          def delegation
+            @delegation ||= Decidim::ActionDelegator::GranteeDelegations.for(
+              form.context.current_question.consultation,
+              form.context.current_user
+            ).find_by(id: form.decidim_consultations_delegation_id)
+          end
+        end
+      end
+    end
+  end
+end

data/app/commands/decidim/action_delegator/vote_delegation.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Decidim
+  module ActionDelegator
+    class VoteDelegation
+      def initialize(response, context)
+        @response = response
+        @context = context
+      end
+
+      def call
+        PaperTrail.request.controller_info = { decidim_action_delegator_delegation_id: context.delegation.id }
+        WhodunnitVote.new(build_vote, context.current_user)
+      end
+
+      private
+
+      attr_reader :context, :response
+
+      def build_vote
+        context.current_question.votes.build(
+          author: context.delegation.granter,
+          response: response
+        )
+      end
+    end
+  end
+end

data/app/controllers/concerns/decidim/action_delegator/admin/filterable.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Decidim
+  module ActionDelegator
+    module Admin
+      module Filterable
+        extend ActiveSupport::Concern
+
+        included do
+          include Decidim::Admin::Filterable
+
+          private
+
+          def base_query
+            collection
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/decidim/action_delegator/admin/application_controller.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Decidim
+  module ActionDelegator
+    module Admin
+      # This controller is the abstract class from which all other controllers of
+      # this engine inherit.
+      class ApplicationController < Decidim::Admin::ApplicationController
+        register_permissions(ApplicationController,
+                             ActionDelegator::Permissions,
+                             Decidim::Consultations::Permissions,
+                             Decidim::Admin::Permissions)
+        def permission_class_chain
+          Decidim.permissions_registry.chain_for(ApplicationController)
+        end
+      end
+    end
+  end
+end

data/app/controllers/decidim/action_delegator/admin/consultations/exports_controller.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Decidim
+  module ActionDelegator
+    module Admin
+      module Consultations
+        class ExportsController < ActionDelegator::Admin::ApplicationController
+          include NeedsPermission
+          include Decidim::Consultations::NeedsConsultation
+
+          def create
+            enforce_permission_to :export_consultation_results, :consultation, consultation: current_consultation
+
+            ExportConsultationResultsJob.perform_later(current_user, current_consultation, type)
+
+            flash[:notice] = t("decidim.admin.exports.notice")
+            redirect_back(fallback_location: decidim_admin_consultations.results_consultation_path(current_consultation))
+          end
+
+          def type
+            "type_and_weight"
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/decidim/action_delegator/admin/consultations_controller.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Decidim
+  module ActionDelegator
+    module Admin
+      class ConsultationsController < Decidim::Consultations::Admin::ConsultationsController
+        def results
+          enforce_permission_to :read, :consultation, consultation: current_consultation
+
+          @questions = Scrutiny.new(current_consultation).questions
+          @responses = responses.group_by(&:decidim_consultations_questions_id)
+          @total_delegates = DelegatesVotesByConsultation.new(current_consultation).query
+
+          render layout: "decidim/admin/consultation"
+        end
+
+        private
+
+        def permission_class_chain
+          Decidim.permissions_registry.chain_for(ActionDelegator::Admin::ApplicationController)
+        end
+
+        def responses
+          ResponsesByMembership.new(published_questions_responses).query
+        end
+
+        def published_questions_responses
+          VotedWithDirectVerification.new(PublishedResponses.new(current_consultation).query).query
+        end
+      end
+    end
+  end
+end

data/app/controllers/decidim/action_delegator/admin/delegations_controller.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Decidim
+  module ActionDelegator
+    module Admin
+      class DelegationsController < ActionDelegator::Admin::ApplicationController
+        include NeedsPermission
+        include Paginable
+
+        helper DelegationHelper
+        helper_method :current_setting
+
+        layout "decidim/action_delegator/admin/delegations"
+
+        def index
+          enforce_permission_to :index, :delegation
+
+          @delegations = paginate(collection)
+        end
+
+        def new
+          enforce_permission_to :create, :delegation
+
+          @form = form(DelegationForm).instance
+        end
+
+        def create
+          enforce_permission_to :create, :delegation
+
+          @form = DelegationForm.from_params(params)
+
+          CreateDelegation.call(@form, current_user, current_setting) do
+            on(:ok) do
+              notice = I18n.t("delegations.create.success", scope: "decidim.action_delegator.admin")
+              redirect_to setting_delegations_path(current_setting), notice: notice
+            end
+
+            on(:error) do |error|
+              flash.now[:error] = error
+              render :new
+            end
+          end
+        end
+
+        def destroy
+          enforce_permission_to :destroy, :delegation, resource: delegation
+
+          setting_id = delegation.setting.id
+
+          if delegation.destroy
+            notice = I18n.t("delegations.destroy.success", scope: "decidim.action_delegator.admin")
+            redirect_to setting_delegations_path(setting_id), notice: notice
+          else
+            error = I18n.t("delegations.destroy.error", scope: "decidim.action_delegator.admin")
+            redirect_to setting_delegations_path(setting_id), flash: { error: error }
+          end
+        end
+
+        private
+
+        def delegation
+          @delegation ||= collection.find_by(id: params[:id])
+        end
+
+        def collection
+          @collection ||= SettingDelegations.new(current_setting).query
+        end
+
+        def current_setting
+          @current_setting ||= organization_settings.find_by(id: params[:setting_id])
+        end
+
+        def organization_settings
+          ActionDelegator::OrganizationSettings.new(current_organization).query
+        end
+      end
+    end
+  end
+end