Add documentation to "Download my data" page (#13711)

Co-authored-by: Tom Greenwood <101816158+greenwoodt@users.noreply.github.com> Co-authored-by: Alexandru Emil Lupu <contact@alecslupu.ro> Co-authored-by: Alejandro Rueda López <alejandro.rueda@nazaries.com> Co-authored-by: MariaDascaluPublicis <166501615+MariaDascaluPublicis@users.noreply.github.com>
decidim · Dec 17, 2024 · b759937 · b759937
1 parent e45e59b
commit b759937
Show file tree

Hide file tree

Showing 27 changed files with 587 additions and 124 deletions.
diff --git a/decidim-budgets/config/locales/en.yml b/decidim-budgets/config/locales/en.yml
@@ -367,6 +367,15 @@ en:
               enabled: Voting enabled
               finished: Voting finished
     download_your_data:
+      help:
+        orders:
+          budget: The budget that the order is related to
+          checked_out_at: The date and time when the order was checked out
+          component: The component that the order is related to
+          created_at: The date and time when the order was created
+          id: The unique identifier of the order
+          projects: The projects that the order has voted on
+          updated_at: The date and time when the order was updated
       show:
         projects: Projects export
     events:

diff --git a/decidim-budgets/spec/services/decidim/download_your_data_exporter_spec.rb b/decidim-budgets/spec/services/decidim/download_your_data_exporter_spec.rb
@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "decidim/core/test/shared_examples/download_your_data_shared_examples"
+
+module Decidim
+  describe DownloadYourDataExporter do
+    subject { DownloadYourDataExporter.new(user, "download-your-data", "CSV") }
+
+    let(:organization) { create(:organization) }
+    let(:user) { create(:user, organization:) }
+    let(:component) { create(:budgets_component, organization:) }
+    let(:budget) { create(:budget, component:) }
+
+    describe "#readme" do
+      context "when the user has a budgets' order" do
+        let!(:order) { create(:order, budget:, user:) }
+        let(:help_definition_string) { "The projects that the order has voted on" }
+
+        it_behaves_like "a download your data entity"
+      end
+    end
+  end
+end
diff --git a/decidim-comments/config/locales/en.yml b/decidim-comments/config/locales/en.yml
@@ -130,6 +130,26 @@ en:
         title: Edit your comment
       up_vote_button:
         text: I agree with this comment
+    download_your_data:
+      help:
+        comment_votes:
+          comment: The id of the comment that was voted
+          created_at: The date when this vote was created
+          id: The id of the vote
+          updated_at: The date when this vote was last updated
+          weight: The weight of the vote (1 for upvote, -1 for downvote)
+        comments:
+          alignment: If this comment was a favour, against or neutral
+          author: The name of the participant that made this comment
+          body: The comment itself
+          commentable_id: The unique id of the commentable
+          commentable_type: The type of the commentable (if it was a result, a proposal, etc.)
+          created_at: The date when this comment was created
+          depth: The place where this comment is in the three of comments (if it is an answer or an answer of an answer)
+          id: The id for this comment
+          locale: The locale (language) that the participant had when leaving this comment
+          root_commentable_url: The URL of the resource that ties to this comment
+          user_group: The name of the user group that made this comment (if any)
     events:
       comments:
         comment_by_followed_user:

diff --git a/decidim-comments/spec/services/decidim/download_your_data_exporter_spec.rb b/decidim-comments/spec/services/decidim/download_your_data_exporter_spec.rb
@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "decidim/core/test/shared_examples/download_your_data_shared_examples"
+
+module Decidim
+  describe DownloadYourDataExporter do
+    subject { DownloadYourDataExporter.new(user, "download-your-data", "CSV") }
+
+    let(:user) { create(:user, organization:) }
+    let(:organization) { create(:organization) }
+    let(:expected_files) do
+      # this are the prefixes for the files that could have user generated content
+      %w(
+        decidim-comments-comments-
+        decidim-comments-commentvotes-
+      )
+    end
+
+    describe "#data_and_attachments_for_user" do
+      context "when the user has a comment" do
+        let(:participatory_space) { create(:participatory_process, organization:) }
+        let(:component) { create(:component, participatory_space:) }
+        let(:commentable) { create(:dummy_resource, component:) }
+
+        let!(:comment) { create(:comment, commentable:, author: user) }
+
+        it "returns the comment data" do
+          user_data, = subject.send(:data_and_attachments_for_user)
+
+          user_data.find { |entity, _| entity == "decidim-comments-comments" }.tap do |_, exporter_data|
+            csv_comments = exporter_data.read.split("\n")
+            expect(csv_comments.count).to eq 2
+            expect(csv_comments.first).to start_with "id;created_at;body;locale;author/id;author/name;alignment;depth;"
+            expect(csv_comments.second).to start_with "#{comment.id};"
+          end
+        end
+      end
+    end
+
+    describe "#readme" do
+      context "when the user has a comment" do
+        let(:participatory_space) { create(:participatory_process, organization:) }
+        let(:component) { create(:component, participatory_space:) }
+        let(:commentable) { create(:dummy_resource, component:) }
+        let!(:comment) { create(:comment, commentable:, author: user) }
+        let(:help_definition_string) { "If this comment was a favour, against or neutral" }
+
+        it_behaves_like "a download your data entity"
+      end
+
+      context "when the user has a comment vote" do
+        let(:participatory_space) { create(:participatory_process, organization:) }
+        let(:component) { create(:component, participatory_space:) }
+        let(:commentable) { create(:dummy_resource, component:) }
+        let!(:comment) { create(:comment, commentable:) }
+        let!(:comment_vote) { create(:comment_vote, comment:, author: user) }
+        let(:help_definition_string) { "The weight of the vote (1 for upvote, -1 for downvote)" }
+
+        it_behaves_like "a download your data entity"
+      end
+    end
+  end
+end
diff --git a/decidim-conferences/config/locales/en.yml b/decidim-conferences/config/locales/en.yml
@@ -538,6 +538,21 @@ en:
         objectives: Objectives
         related_assemblies: Related assemblies
         related_participatory_processes: Related participatory processes
+    download_your_data:
+      help:
+        conference_invites:
+          accepted_at: The date when the conference invitation was accepted
+          conference: The conference where this invitation was sent
+          id: The unique identifier of the conference invitation
+          registration_type: The type of the registration for this conference that was sent
+          rejected_at: The date when the conference invitation was rejected
+          sent_at: The date when this conference invitation was sent
+          user: The unique identifier of the user that the invitation was sent
+        conference_registrations:
+          conference: The conference that this belongs to
+          id: The unique identifier of the conference regisrations
+          registration_type: The type of registration that this belongs to
+          user: The unique identifier of the user for this registration
     events:
       conferences:
         conference_registration_confirmed:

diff --git a/decidim-conferences/spec/services/decidim/download_your_data_exporter_spec.rb b/decidim-conferences/spec/services/decidim/download_your_data_exporter_spec.rb
@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "decidim/core/test/shared_examples/download_your_data_shared_examples"
+
+module Decidim
+  describe DownloadYourDataExporter do
+    subject { DownloadYourDataExporter.new(user, "download-your-data", "CSV") }
+
+    let(:user) { create(:user, organization:) }
+    let(:organization) { create(:organization) }
+
+    describe "#readme" do
+      context "when the user has a conference invite" do
+        let!(:conference_invite) { create(:conference_invite, user:) }
+        let(:help_definition_string) { "The date when this conference invitation was sent" }
+
+        it_behaves_like "a download your data entity"
+      end
+
+      context "when the user has a conference registration" do
+        let!(:conference_registration) { create(:conference_registration, user:) }
+        let(:help_definition_string) { "The type of registration that this belongs to" }
+
+        it_behaves_like "a download your data entity"
+      end
+    end
+  end
+end
diff --git a/decidim-core/app/controllers/decidim/download_your_data_controller.rb b/decidim-core/app/controllers/decidim/download_your_data_controller.rb
@@ -8,6 +8,8 @@ class DownloadYourDataController < Decidim::ApplicationController
     include Decidim::UserProfile
     include Decidim::Paginable
 
+    helper_method :help_definitions
+
     # i18n-tasks-use t('decidim.download_your_data.show.answers')
     # i18n-tasks-use t('decidim.download_your_data.show.assemblies')
     # i18n-tasks-use t('decidim.download_your_data.show.debate_comments')
@@ -57,5 +59,9 @@ def download_file
     def private_export
       @private_export ||= current_user.private_exports.find(params[:uuid])
     end
+
+    def help_definitions
+      @help_definitions ||= Decidim::DownloadYourDataSerializers.help_definitions_for(current_user)
+    end
   end
 end
diff --git a/decidim-core/app/packs/stylesheets/decidim/_accordion.scss b/decidim-core/app/packs/stylesheets/decidim/_accordion.scss
@@ -11,3 +11,33 @@
   [id*="comment"][class="comment-reply"][aria-hidden="false"] {
   display: block;
 }
+
+.card-accordion {
+  @apply border-b border-gray-3 mt-6;
+
+  &-title {
+    @apply text-primary font-semibold text-xl inline-block;
+  }
+
+  &-divider-button {
+    @apply flex items-center justify-between items-end w-full;
+
+    svg {
+      @apply inline-block w-6 h-6 fill-primary;
+    }
+
+    &[aria-expanded="true"] {
+      svg {
+        @apply rotate-180 transition-transform;
+      }
+    }
+  }
+
+  &-section {
+    @apply pb-8;
+
+    ul {
+      @apply mb-0;
+    }
+  }
+}
diff --git a/decidim-core/app/packs/stylesheets/decidim/_open_data.scss b/decidim-core/app/packs/stylesheets/decidim/_open_data.scss
diff --git a/decidim-core/app/packs/stylesheets/decidim/application.scss b/decidim-core/app/packs/stylesheets/decidim/application.scss
@@ -75,7 +75,6 @@
 @import "stylesheets/decidim/_home.scss";
 @import "stylesheets/decidim/_search.scss";
 @import "stylesheets/decidim/_cookies.scss";
-@import "stylesheets/decidim/_open_data.scss";
 // participatory spaces are quite similar between processes and assemblies (different modules), so their stylesheets are placed in the core
 @import "stylesheets/decidim/_participatory_spaces.scss";
 @import "stylesheets/decidim/_omnipresent_banner.scss";

diff --git a/decidim-core/app/services/decidim/download_your_data_exporter.rb b/decidim-core/app/services/decidim/download_your_data_exporter.rb
@@ -8,6 +8,8 @@ class DownloadYourDataExporter
     DEFAULT_EXPORT_FORMAT = "CSV"
     ZIP_FILE_NAME = "download-your-data.zip"
 
+    include Decidim::TranslatableAttributes
+
     # Public: Initializes the class.
     #
     # user          - The user to export the data from.
@@ -19,6 +21,7 @@ def initialize(user, name, export_format = DEFAULT_EXPORT_FORMAT)
       @name = name
     end
 
+    # i18n-tasks-use t("decidim.download_your_data.show.download_your_data")
     def export
       user_export = user.private_exports.build
       user_export.export_type = name
@@ -38,6 +41,7 @@ def data
       buffer = Zip::OutputStream.write_buffer do |out|
         save_user_data(out, user_data)
         save_user_attachments(out, user_attachments)
+        save_readme(out)
       end
 
       buffer.rewind
@@ -50,7 +54,8 @@ def data_and_attachments_for_user
 
       download_your_data_entities.each do |object|
         klass = Object.const_get(object)
-        export_data << [klass.model_name.name.parameterize.pluralize, Exporters.find_exporter(export_format).new(klass.user_collection(user), klass.export_serializer).export]
+        exporter = Exporters.find_exporter(export_format).new(klass.user_collection(user), klass.export_serializer)
+        export_data << [klass.model_name.name.parameterize.pluralize, exporter.export]
         attachments = klass.download_your_data_images(user)
         export_attachments << [klass.model_name.name.parameterize.pluralize, attachments.flatten] unless attachments.nil?
       end
@@ -86,5 +91,28 @@ def save_user_attachments(output, user_attachments)
         end
       end
     end
+
+    def save_readme(output)
+      output.put_next_entry("README.md")
+      output.write readme
+    end
+
+    def readme
+      readme_file = "# #{I18n.t("decidim.download_your_data.help.core.title", organization: translated_attribute(user.organization.name))}\n\n"
+      readme_file << "#{I18n.t("decidim.download_your_data.help.core.description", user_name: "#{user.name} (#{user.nickname})")}\n\n"
+      help_definition = DownloadYourDataSerializers.help_definitions_for(user)
+
+      help_definition.each do |entity, headers|
+        next if headers.empty?
+
+        readme_file << "\n\n## #{entity}\n\n"
+
+        headers.each do |header, help_value|
+          readme_file << "* #{header}: #{help_value}\n"
+        end
+      end
+
+      readme_file
+    end
   end
 end
diff --git a/decidim-core/app/views/decidim/application/_accordion_section.html.erb b/decidim-core/app/views/decidim/application/_accordion_section.html.erb
@@ -0,0 +1,14 @@
+<div class="card-accordion" data-component="accordion">
+  <div class="card-accordion-divider">
+    <button class="card-accordion-divider-button" data-open="<%= open_accordion ||= false %>" data-controls="panel-title--<%= panel_id %>" type="button">
+      <h2 class="card-accordion-title" id="title">
+        <%= title %>
+      </h2>
+      <%= icon "arrow-down-s-line", class: "mb-4" %>
+    </button>
+  </div>
+
+  <div id="panel-title--<%= panel_id %>" class="card-accordion-section editor-content" aria-hidden="true">
+    <%= yield %>
+  </div>
+</div>
diff --git a/decidim-core/app/views/decidim/download_your_data/_export.html.erb b/decidim-core/app/views/decidim/download_your_data/_export.html.erb
@@ -1,10 +1,15 @@
 <tr>
-  <td class="text-left py-4 font-bold"><%= t(export.export_type, scope:"decidim.download_your_data.show") %></td>
+  <td class="text-left p-4"><%= t(export.export_type, scope:"decidim.download_your_data.show") %></td>
   <td class="text-center"><%= export.expired? ? t("expired", scope:"decidim.download_your_data.show") : l(export.expires_at, format: :decidim_short) %></td>
-  <td class="text-left py-4">
-    <%= button_to t("download", scope:"decidim.download_your_data.show"), download_download_your_data_path(export),
-                  class: "button button__sm button__secondary ml-auto",
+  <td class="py-4">
+    <%= button_to download_download_your_data_path(export),
+                  class: "button button__sm button__transparent-secondary m-auto block",
                   disabled: export.expired?,
-                  method: :get %>
+                  aria: { label: t("download", scope:"decidim.download_your_data.show") },
+                  method: :get do %>
+                    <span class="hidden lg:block"><%= t("download", scope:"decidim.download_your_data.show") %></span>
+                    <span class="lg:hidden"><%= icon "download-line", class: "text-secondary fill-current" %></span>
+    <% end %>
+
   </td>
 </tr>