decidim-reporting_proposals 0.2.0 → 0.4.2

data/README.md

@@ -9,12 +9,18 @@
 
 This module creates a new component to be used in participatory spaces that allows to create proposals orientated to manage geolocated issues in a city. For instance Damages or new ideas of improving a particular street or public good.
 
-> NOTE: in development, not ready for production.
+[👉 See features & screenshots](#features)
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
+```ruby
+gem 'decidim-reporting_proposals'
+```
+
+Or, if you want to stay up to date with the latest changes use this line instead:
+
 ```ruby
 gem 'decidim-reporting_proposals', git: "https://github.com/openpoke/decidim-module-reporting_proposals"
 ```
@@ -27,17 +33,105 @@ And then execute:
 bundle exec rails decidim_reporting_proposals:install:migrations
 ```
 
+> **IMPORTANT:**
+>
+> This module makes use of the [Deface](https://github.com/spree/deface) gem.
+> In conjunction with other modules (we know [Term Customizer](https://github.com/mainio/decidim-module-term_customizer/) is one of them) it might cause errors when precompiling assets for production sites. But only if during this process the compiling machine does not have access to the database.
+>
+> It is easy to overcome this problem. Just add the following line to your `config/environments/production.rb` file:
+> 
+> ```ruby
+> config.deface.enabled = ENV['DB_ADAPTER'].blank? || ENV['DB_ADAPTER'] == 'postgresql'
+> ```
+>
+> Then precompile with these ENV enabled in your CI:
+>
+> ```bash
+> DB_ADAPTER=nulldb RAILS_ENV=production rake assets:precompile
+> ```
+>
+> Alternatively, use any other ENV var to set up the `config.deface.enabled` to `false` during the precompilation phase.
+
+Depending on your Decidim version, you can choose the corresponding version to ensure compatibility:
+
+| Version | Compatible Decidim versions |
+|---|---|
+| 0.5.x | 0.27.x |
+| 0.4.x | 0.26.x |
+
 ## Usage
 
-TODO...
+This module works very similarly as the Proposals module, in fact, it extends it to provide additional features and some different defaults.
+
+It provides a new component called "Reporting Proposals" that can be added in addition or instead of the Proposals component in any participatory space.
+
+### Features
+
+This module provides the following features:
+
+1. **Reporting Proposals Component**: A new component that can be added to any participatory space. It allows to create proposals in one-step form with some optimization for mobile devices. Users can add photos using the phone's camera directly and also use the device's GPS to establish a precise a geolocated address with one click. Some of the options can be used in the normal proposal's component too (but in this case they 2 steps behavior is maintained).
+  ![Reporting proposal creationg](features/proposal.png)
+
+2. **Comparison by proximity**: By default, reporting proposals are compared by proximity before publishing (as they are geolocated by default). This can be disabled in the component's settings.
+  ![Compare by proximity](features/proximity.png)
+
+3. **Automatic assignation of valuators**: When a proposal is created, admins usually have to assign valuators manually to it. This module allows admins to assign valuators to a category directly. This will automatically assign all valuators in that category to any proposal/reporting proposal created under it (and also existing proposals). This avoids the need of manually assign proposals to valuators. This behavior can be disabled in the component's settings.
+  ![Valuators in categories](features/categories.png)
+
+4. **Valuators empowerment**: A number of features allow valuators to have more control over the proposals they are evaluating. They can assign other valuators (instead of themselves) and they can change or add photos to a proposal. All of it is configurable. Also, valuators can be assigned directly in the proposal's answering page instead of using the bulk assignation feature. Additionally, privates note can be edited and links in it are clickable.
+  ![Valuators empowerment](features/answering1.png)
+
+5. **Overdue proposals**: This module allows to set a number of days after which a proposal is considered overdue. This is configurable and can be disabled. This feature affects the admin list of proposals, adding visual notes, color coded, to facilitate the identification of overdue proposals and preventing admins to leave unanswered proposals for a long time.
+  ![Overdue proposals](features/overdues.png)
+
+6. **Improved notifications**: Some notifications are added, and some existing ones are improved. For instance, valuators and admins can receive notifications after a proposal has been added and it's content includes a direct link to the proposal and its answering page.
+
+7. **Hide proposals without reporting**: Administrators can hide proposals directly, without using the reporting process. Also, authors who's content has been hidden receive a notification.
+
+8. **Proposal answers templates**: Administrators can create templates for the answers to proposals. This is useful to provide a standard answer to proposals that are similar. This feature requires to enable the `decidim-templates` official module.
+  ![Templates for proposals answers](features/templates1.png)
+  ![Applying a template](features/templates2.png)
+
+### Customization
+
+Almost all the features of this module can be customized/disabled through an initializer.
+
+For instance, you can create an initializer an change some of the available options as follows (**This is optional, you don't need to do this, by default all options are enabled**):
 
 ```ruby
 # config/initializers/reporting_proposals.rb
 
 Decidim::ReportingProposals.configure do |config|
+  # Public Setting that defines after how many days a not-answered proposal is overdue
+  # Set it to 0 (zero) if you don't want to use this feature
+  config.unanswered_proposals_overdue = 7
+
+  # Public Setting that defines after how many days an evaluating-state proposal is overdue
+  # Set it to 0 (zero) if you don't want to use this feature
+  config.evaluating_proposals_overdue = 3
+
+  # Public Setting that defines whether the administrator is allowed to hide the proposals.
+  # Set to false if you do not want to use this feature
+  config.allow_admins_to_hide_proposals =true
+
+  # Public Setting that allows to configure which component will have "Use my location" button
+  # in a geocoded address field. Accepts an array of component manifest names
+  config.show_my_location_button = [:proposals, :meetings, :reporting_proposals]
+
+  # Public Setting that adds a button next to the "add image" input[type=file] to open the camera directly
+  config.use_camera_button = [:proposals, :reporting_proposals]
+
+  # Public setting to prevent valuators or admins to modify the photos attached to a proposal
+  # otherwise can be configured at the component level
+  config.allow_proposal_photo_editing = true
+
+  # Public setting to allow to assign other valuators
+  config.valuators_assign_other_valuators = true
 end
 ```
 
+Find all the available options in the [config.rb](lib/decidim/reporting_proposals/config.rb) file.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/openpoke/decidim-module-reporting_proposals.
@@ -57,8 +151,8 @@ 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
+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
@@ -67,10 +161,10 @@ order to create the dummy test app database.
 Then to test how the module works in Decidim, start the development server:
 
 ```bash
-$ DATABASE_USERNAME=<username> DATABASE_PASSWORD=<password> bin/rails s
+DATABASE_USERNAME=<username> DATABASE_PASSWORD=<password> bin/rails s
 ```
 
-Note that `bin/rails` is a convinient wrapper around the command `cd development_app; bundle exec rails`.
+Note that `bin/rails` is a convenient wrapper around the command `cd development_app; bundle exec rails`.
 
 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
@@ -87,7 +181,7 @@ speed up the process.
 
 To do that, start in a separate terminal than the one with `bin/rails s`, and BEFORE it, the following command:
 
-```
+```bash
 bin/webpack-dev-server
 ```
 
@@ -102,14 +196,13 @@ project is set to follow the same rules that Decidim itself follows.
 You can run the code styling checks by running the following commands from the
 console:
 
-```
-$ bundle exec rubocop
+```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)
 
@@ -128,9 +221,9 @@ run the following commands:
 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
+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
@@ -144,11 +237,10 @@ 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:
+Running tests automatically generates a code coverage report. To generate the complete report run all the tests using this command:
 
 ```bash
-$ SIMPLECOV=1 bundle exec rspec
+bundle exec rspec
 ```
 
 This will generate a folder named `coverage` in the project root which contains

data/app/cells/concerns/decidim/reporting_proposals/proposals_picker_cell_override.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Decidim
+  module ReportingProposals
+    # Exposes the proposal resource so users can view and create them.
+    module ProposalsPickerCellOverride
+      extend ActiveSupport::Concern
+
+      included do
+        def proposals
+          @proposals ||= begin
+            proposals_query = Decidim.find_resource_manifest(:proposals).try(:resource_scope, component)
+            reporting_proposals_query = Decidim.find_resource_manifest(:reporting_proposals).try(:resource_scope, component)
+            (reporting_proposals_query ? proposals_query.or(reporting_proposals_query) : proposals_query)
+             &.includes(:component)
+             &.published
+             &.not_hidden
+             &.order(id: :asc)
+          end
+        end
+      end
+    end
+  end
+end

data/app/commands/concerns/decidim/admin/hide_resource_override.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Admin
+    module HideResourceOverride
+      extend ActiveSupport::Concern
+
+      included do
+        def call
+          return broadcast(:invalid) unless hideable?
+
+          hide!
+
+          send_hide_notification_to_author
+          send_hide_email_to_author
+
+          broadcast(:ok, @reportable)
+        end
+
+        private
+
+        def send_hide_email_to_author
+          Decidim::Admin::HiddenResourceMailer.notify_mail(
+            @reportable, resource_authors, report_reasons
+          ).deliver_later
+        end
+
+        def resource_authors
+          @reportable.try(:authors) || [@reportable.try(:author)]
+        end
+      end
+    end
+  end
+end

data/app/commands/concerns/decidim/proposals/admin/answer_proposal_override.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Proposals
+    module Admin
+      module AnswerProposalOverride
+        extend ActiveSupport::Concern
+
+        included do
+          def call
+            return broadcast(:invalid) if form.invalid?
+
+            store_initial_proposal_state
+
+            transaction do
+              answer_proposal
+              notify_proposal_answer
+              send_email_to_author
+            end
+
+            broadcast(:ok)
+          end
+
+          private
+
+          def send_email_to_author
+            return unless Decidim::ReportingProposals.notify_authors_on_answering.include?(proposal.component.manifest_name.to_sym)
+
+            affected_users.each do |user|
+              Decidim::Proposals::Admin::NotificationAnswerProposalMailer.notify_proposal_author(proposal, user).deliver_later
+            end
+          end
+
+          def affected_users
+            proposal.notifiable_identities
+          end
+        end
+      end
+    end
+  end
+end

data/app/commands/concerns/decidim/proposals/admin/assign_proposals_to_valuator_override.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Proposals
+    module Admin
+      module AssignProposalsToValuatorOverride
+        extend ActiveSupport::Concern
+
+        included do
+          def call
+            return broadcast(:invalid) unless form.valid?
+
+            assign_proposals
+            send_email
+
+            broadcast(:ok)
+          rescue ActiveRecord::RecordInvalid
+            broadcast(:invalid)
+          end
+
+          private
+
+          def send_email
+            ProposalsValuatorMailer.notify_proposals_valuator(form.valuator_role.user, form.current_user, form.proposals).deliver_later
+          end
+        end
+      end
+    end
+  end
+end

data/app/commands/concerns/decidim/proposals/publish_proposal_override.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Proposals
+    module PublishProposalOverride
+      extend ActiveSupport::Concern
+
+      included do
+        def call
+          return broadcast(:invalid) unless @proposal.authored_by?(@current_user)
+
+          transaction do
+            publish_proposal
+            increment_scores
+            send_notification
+            send_email_to_author
+            send_notification_to_participatory_space
+          end
+
+          broadcast(:ok, @proposal)
+        end
+
+        private
+
+        def send_notification_to_participatory_space
+          Decidim::EventsManager.publish(
+            event: "decidim.events.proposals.proposal_published",
+            event_class: Decidim::Proposals::PublishProposalEvent,
+            resource: @proposal,
+            followers: @proposal.participatory_space.followers - coauthors_followers - admins_followers,
+            extra: {
+              participatory_space: true
+            }
+          )
+          # put here to avoid override the call method
+          send_notification_to_admins
+        end
+
+        def send_notification_to_admins
+          return if admins_followers.empty?
+
+          Decidim::EventsManager.publish(
+            event: "decidim.events.proposals.proposal_published",
+            event_class: Decidim::Proposals::PublishProposalEvent,
+            resource: @proposal,
+            followers: admins_followers,
+            extra: {
+              type: "admin",
+              participatory_space: true
+            }
+          )
+        end
+
+        def admins_followers
+          @proposal.followers.where(admin: true).uniq
+        end
+
+        def send_email_to_author
+          return unless Decidim::ReportingProposals.notify_authors_on_publish.include?(@proposal.component.manifest_name.to_sym)
+
+          affected_users.each do |user|
+            Decidim::Proposals::NotificationPublishProposalMailer.notify_proposal_author(@proposal, user).deliver_later
+          end
+        end
+
+        def affected_users
+          @proposal.notifiable_identities
+        end
+      end
+    end
+  end
+end

data/app/commands/concerns/decidim/reporting_proposals/admin/create_answer_override.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Decidim
+  module ReportingProposals
+    module Admin
+      module CreateAnswerOverride
+        extend ActiveSupport::Concern
+
+        included do
+          def proposals
+            @proposals ||= answer.sibling_scope(:proposals).where(id: @form.proposal_ids) + answer.sibling_scope(:reporting_proposals).where(id: @form.proposal_ids)
+          end
+        end
+      end
+    end
+  end
+end

data/app/commands/concerns/decidim/reporting_proposals/admin/create_result_override.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Decidim
+  module ReportingProposals
+    module Admin
+      module CreateResultOverride
+        extend ActiveSupport::Concern
+
+        included do
+          def proposals
+            @proposals ||= result.sibling_scope(:proposals).where(id: @form.proposal_ids) + result.sibling_scope(:reporting_proposals).where(id: @form.proposal_ids)
+          end
+        end
+      end
+    end
+  end
+end

data/app/commands/concerns/decidim/reporting_proposals/admin/update_result_override.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Decidim
+  module ReportingProposals
+    module Admin
+      module UpdateResultOverride
+        extend ActiveSupport::Concern
+
+        included do
+          def proposals
+            @proposals ||= result.sibling_scope(:proposals).where(id: form.proposal_ids) + result.sibling_scope(:reporting_proposals).where(id: form.proposal_ids)
+          end
+
+          def send_notifications
+            all = result.linked_resources(:proposals, "included_proposals") + result.linked_resources(:reporting_proposals, "included_proposals")
+            all.each do |proposal|
+              Decidim::EventsManager.publish(
+                event: "decidim.events.accountability.result_progress_updated",
+                event_class: Decidim::Accountability::ResultProgressUpdatedEvent,
+                resource: result,
+                affected_users: proposal.notifiable_identities,
+                followers: proposal.followers - proposal.notifiable_identities,
+                extra: {
+                  progress: result.progress,
+                  proposal_id: proposal.id
+                }
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/commands/concerns/decidim/reporting_proposals/close_meeting_override.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Decidim
+  module ReportingProposals
+    module CloseMeetingOverride
+      extend ActiveSupport::Concern
+
+      included do
+        def proposals
+          @proposals ||= meeting.sibling_scope(:proposals).where(id: @form.proposal_ids) + meeting.sibling_scope(:reporting_proposals).where(id: form.proposal_ids)
+        end
+      end
+    end
+  end
+end

data/app/commands/concerns/decidim/reporting_proposals/create_project_override.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Decidim
+  module ReportingProposals
+    module CreateProjectOverride
+      extend ActiveSupport::Concern
+
+      included do
+        def proposals
+          @proposals ||= project.sibling_scope(:proposals).where(id: @form.proposal_ids) + project.sibling_scope(:reporting_proposals).where(id: form.proposal_ids)
+        end
+      end
+    end
+  end
+end

data/app/commands/concerns/decidim/templates/admin/copy_questionnaire_template_override.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Templates
+    # A command with all the business logic when duplicating a questionnaire template
+    module Admin
+      module CopyQuestionnaireTemplateOverride
+        extend ActiveSupport::Concern
+
+        included do
+          private
+
+          def copy_template
+            @copied_template = Template.create!(
+              organization: @template.organization,
+              name: @template.name,
+              description: @template.description,
+              target: :questionnaire
+            )
+            @resource = Decidim::Forms::Questionnaire.create!(
+              @template.templatable.dup.attributes.merge(
+                questionnaire_for: @copied_template
+              )
+            )
+
+            @copied_template.update!(templatable: @resource)
+          end
+        end
+      end
+    end
+  end
+end

data/app/commands/concerns/decidim/templates/admin/create_questionnaire_template_override.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Templates
+    # A command with all the business logic when duplicating a questionnaire template
+    module Admin
+      module CreateQuestionnaireTemplateOverride
+        extend ActiveSupport::Concern
+
+        included do
+          def call
+            return broadcast(:invalid) unless @form.valid?
+
+            @template = Decidim.traceability.create!(
+              Template,
+              @form.current_user,
+              name: @form.name,
+              description: @form.description,
+              organization: @form.current_organization,
+              target: :questionnaire
+            )
+
+            @questionnaire = Decidim::Forms::Questionnaire.create!(questionnaire_for: @template)
+            @template.update!(templatable: @questionnaire)
+
+            broadcast(:ok, @template)
+          end
+        end
+      end
+    end
+  end
+end

data/app/commands/decidim/templates/admin/copy_proposal_answer_template.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Templates
+    # A command with all the business logic when duplicating a proposal's answer template
+    module Admin
+      class CopyProposalAnswerTemplate < Rectify::Command
+        def initialize(template)
+          @template = template
+        end
+
+        def call
+          return broadcast(:invalid) unless @template.valid?
+
+          Template.transaction do
+            copy_template
+          end
+
+          broadcast(:ok, @copied_template)
+        end
+
+        def copy_template
+          @copied_template = Template.create!(
+            organization: @template.organization,
+            name: @template.name,
+            description: @template.description,
+            target: :proposal_answer,
+            field_values: @template.field_values,
+            templatable: @template.templatable
+          )
+        end
+      end
+    end
+  end
+end

data/app/commands/decidim/templates/admin/create_proposal_answer_template.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Templates
+    module Admin
+      class CreateProposalAnswerTemplate < Rectify::Command
+        # Initializes the command.
+        #
+        # form - The source for this ProposalAnswerTemplate.
+        def initialize(form)
+          @form = form
+        end
+
+        def call
+          return broadcast(:invalid) unless @form.valid?
+
+          @template = Decidim.traceability.create!(
+            Template,
+            @form.current_user,
+            name: @form.name,
+            description: @form.description,
+            organization: @form.current_organization,
+            field_values: { internal_state: @form.internal_state },
+            target: :proposal_answer
+          )
+
+          resource = identify_templateable_resource
+          @template.update!(templatable: resource)
+
+          broadcast(:ok, @template)
+        end
+
+        private
+
+        def identify_templateable_resource
+          resource = @form.scope_for_availability.split("-")
+          case resource.first
+          when "organizations"
+            @form.current_organization
+          when "components"
+            component = Decidim::Component.find_by(id: resource.last)
+            component&.participatory_space&.decidim_organization_id == @form.current_organization.id ? component : nil
+          end
+        end
+      end
+    end
+  end
+end