decidim 0.27.6 → 0.28.0.rc4

data/docs/modules/develop/pages/classes/commands.adoc

@@ -0,0 +1,102 @@
+= Commands
+
+A command is custom class that manages the logic between your input, usually a xref:develop:classes/forms.adoc[form] object, an object and an user.
+
+Usually, a command is used to create, update or delete a object.
+
+Commands are located in the `app/commands/decidim/<my_module>` directory, and named: `<action>_<my_resource>.rb`.
+
+In the below example, you will be able to see how the command (`CreateMyResource`), events (`Decidim::MyModule::MyResourceEvent`) and jobs (`Decidim::MyModule::MyCustomJob`) can be used.
+```ruby
+# frozen_string_literal: true
+
+# app/commands/decidim/my_module/create_my_resource.rb
+module Decidim
+  module MyModule
+    # A command with the business logic to create a resource.
+    class CreateMyResource < Decidim::Command
+      # Public: Initializes the command.
+      #
+      def initialize(form, resource)
+        @form = form
+        @resource = resource
+      end
+
+      def call
+      return broadcast(:invalid) if form.invalid?
+
+      transation do
+         create_resource
+         dispatch_event
+         process_jobs
+      end
+      broadcast(:ok)
+    end
+
+      private
+
+      attr_reader :form, :resource
+
+      def process_jobs
+      Decidim::MyModule::MyCustomJob.perform_later(resource)
+    end
+
+      def dispatch_event
+        Decidim::EventsManager.publish(
+          event: "decidim.events.my_module.my_resource_created",
+          event_class: Decidim::MyModule::MyResourceEvent,
+          resource:
+        )
+    end
+
+      def create_resource
+      @resource = Decidim.traceability.create!(
+        resource,
+        form.current_user,
+        **attributes,
+        visibility: "public-only"
+      )
+    end
+
+      # this is mapping of
+      # ActiveRecord::attribute => form.attribute
+      def attributes
+      {
+        title: form.title,
+        description: form.description,
+        resource: form.resource
+      }
+    end
+    end
+  end
+end
+```
+
+Sometimes you may need to extend a `Decidim` supplied command, then you can either override the `attributes` method, either extend it with a `super` call.
+
+```ruby
+# frozen_string_literal: true
+
+# app/lib/overrides/commands/create_my_resource.rb
+module Decidim
+  module Overrides
+    module Commands
+      module CreateMyResource
+        def attributes
+          super.merge(
+            {
+              my_custom_attribute: form.my_custom_attribute
+            }
+          )
+        end
+      end
+    end
+  end
+end
+
+Decidim::MyModule::CreateMyResource.prepend(Decidim::Overrides::Commands::CreateMyResource)
+```
+
+== More information
+
+- `Decidim::Command` is an internalization of https://github.com/andypike/rectify[Rectify] gem created by Andy Pike

data/docs/modules/develop/pages/classes/controllers.adoc

@@ -0,0 +1,96 @@
+= Controllers
+
+Decidim controllers are plain Rails controllers, that usually implement the other concepts that we have described in this section.
+
+Controller classes are located in the `app/controllers/decidim/<my_module>` directory, and named: `<my_resource>_controller.rb`.
+
+```ruby
+# frozen_string_literal: true
+
+# app/controllers/decidim/my_module/resource_controller.rb
+module Decidim
+  module MyModule
+    class MyResourceController < Decidim::MyModule::ApplicationController
+
+    end
+  end
+end
+```
+
+The admin controllers are following the `Decidim` conventions:
+In the below example, you will be able to see how the forms (`ResourceForm`), commands (`CreateMyResource`, `UpdateMyResource`), queries (`Decidim::MyModule::MyResourceQuery`) and permissions (`enforce_permission_to`) can be used.
+
+```ruby
+# frozen_string_literal: true
+
+# app/controllers/decidim/my_module/admin/resources_controller.rb
+module Decidim
+  module MyModule
+    module Admin
+      class ResourcesController < Decidim::MyModule::Admin::ApplicationController
+        def index
+          enforce_permission_to :read, :resource
+          @resources = paginate(resources)
+        end
+
+        def new
+          enforce_permission_to :create, :resource
+          @form = form(ResourceForm).from_params(params)
+        end
+
+        def create
+          enforce_permission_to :create, :resource
+          @form = form(ResourceForm).from_params(params)
+
+          CreateMyResource.call(@form) do
+            on(:ok) do
+              flash[:notice] = I18n.t("resource.create.success", scope: "decidim.my_module.admin")
+              redirect_to action: :index
+            end
+
+            on(:invalid) do
+              flash.now[:alert] = I18n.t("resource.create.invalid", scope: "decidim.my_module.admin")
+              render action: :new
+            end
+          end
+        end
+
+        def edit
+          enforce_permission_to :update, :resource, resource: resource
+          @form = form(ResourceForm).from_model(resource)
+        end
+
+        def update
+          enforce_permission_to :update, :resource, resource: resource
+          @form = form(ResourceForm).from_params(params)
+
+          UpdateMyResource.call(@form) do
+            on(:ok) do
+              flash[:notice] = I18n.t("resource.update.success", scope: "decidim.my_module.admin")
+              redirect_to action: :index
+            end
+
+            on(:invalid) do
+              flash.now[:alert] = I18n.t("resource.update.invalid", scope: "decidim.my_module.admin")
+              render action: :edit
+            end
+          end
+        end
+
+        private
+        def resources
+          @resources ||= Decidim::MyModule::MyQuery.for([current_component])
+        end
+
+        def resource
+          resources.find(params[:id])
+        end
+      end
+    end
+  end
+end
+```
+
+== More information
+
+- https://edgeguides.rubyonrails.org/action_controller_overview.html[Action Controller documentation]

data/docs/modules/develop/pages/classes/events.adoc

@@ -0,0 +1,33 @@
+= Events
+
+The concept regarding the notification is being described in the xref:develop:notifications.adoc[Notifications] page.
+
+- To dispatch notifications in the user account when something happens on a resource or a space they are following
+- To dispatch emails for the above notifications, if the user has not enabled the mail digest
+- To dispatch push notifications  when the installation is active and the user has enabled them
+- To show the activity done by the user in the user's account page
+- In admin panel to show the activity of other admins
+- To dispatch emails to admins when a resource or user is reported
+- To dispatch emails to users when an admin performs an action on the resource owned (like approving Proposal, accepting budgets etc )
+
+Event classes are located in the `app/events/decidim/<my_module>` directory, and named: `<my_resource>_event.rb`.
+
+```ruby
+# frozen_string_literal: true
+
+# app/events/decidim/my_module/my_resource_event.rb
+module Decidim
+  module MyModule
+    class MyResourceEvent < Decidim::Events::SimpleEvent
+      # Defines a list of methods that will be used to translate the resource inside the event.
+      i18n_attributes :example_resource_title
+
+      # The name of the method can be 100% customized, but it must return a string.
+      # the resource object used in the method body is the object that is being handled by the event.
+      def example_resource_title
+        translated_attribute(resource.title)
+      end
+    end
+  end
+end
+```

data/docs/modules/develop/pages/classes/forms.adoc

@@ -0,0 +1,36 @@
+= Forms
+
+This is a form example that can be implemented in your application.
+
+Form classes are located in the `app/forms/decidim/<my_module>` directory, and named: `<resource>_form.rb`.
+
+```ruby
+# frozen_string_literal: true
+
+# app/forms/decidim/my_module/resource_form.rb
+module Decidim
+  module MyModule
+    class ResourceForm < Decidim::Form
+      include Decidim::TranslatableAttributes
+
+      attribute :title, String
+      translatable_attribute :body, String
+
+      validates :title, length: { maximum: 150 }, translatable_presence: true
+      validates :body, translatable_presence: true
+
+      validate :some_custom_validation
+
+      private
+
+      def some_custom_validation
+        errors.add(:title, :invalid) if title == "invalid"
+      end
+    end
+  end
+end
+```
+
+== More information
+
+- `Decidim::Form` is an internalization of https://github.com/andypike/rectify[Rectify] gem created by Andy Pike

data/docs/modules/develop/pages/classes/jobs.adoc

@@ -0,0 +1,26 @@
+= Jobs
+
+Decidim jobs classes are not do not implement anything different than what `ActiveJob` has to offer.
+
+Jobs classes are located in the `app/jobs/decidim/<my_module>` directory, and named: `<my_custom>_job.rb`.
+
+```ruby
+# frozen_string_literal: true
+
+# app/jobs/decidim/my_module/my_custom_job.rb
+module Decidim
+  module MyModule
+    class MyCustomJob < ActiveJob::Base
+      queue_as :default
+
+      def perform(*args)
+        # Do something later
+      end
+    end
+  end
+end
+```
+
+== More information
+
+- https://edgeguides.rubyonrails.org/active_job_basics.html[Active Job documentation]

data/docs/modules/develop/pages/classes/mailers.adoc

@@ -0,0 +1,31 @@
+= Mailers
+
+The mailer class, is not that different than what default Rails has to offer.
+
+Mail classes are located in the `app/mailers/decidim/<my_module>` directory, and named: `<my_custom>_mailer.rb`.
+
+```ruby
+# frozen_string_literal: true
+
+# app/mailers/decidim/my_module/my_custom_mailer.rb
+module Decidim
+  module MyModule
+    class MyCustomMailer < Decidim::ApplicationMailer
+      def greeting(user)
+        with_user(user) do
+          @user = user
+
+          subject = I18n.t("greeting.subject", scope: "decidim.my_module.mailer.my_custom_mailer")
+          mail(to: user.email, subject:)
+        end
+      end
+    end
+  end
+end
+```
+
+Please notice the `with_user` method, that is being used to set the locale of the mailer to the user's locale.
+
+== More information
+
+- https://edgeguides.rubyonrails.org/action_mailer_basics.html[Action Mailer documentation]

data/docs/modules/develop/pages/classes/models.adoc

@@ -0,0 +1,97 @@
+= Models
+
+The models in Decidim are just plain `ActiveRecord` models, so you can use all the methods that come with it.
+
+A model class example would be:
+
+```ruby
+# frozen_string_literal: true
+
+# app/models/decidim/my_module/my_resource.rb
+module Decidim
+  module MyModule
+    class MyResource < Decidim::MyModule::ApplicationRecord
+      include Decidim::HasComponent
+      include Decidim::Traceable
+      include Decidim::Loggable
+      include Decidim::Authorable
+      include Decidim::TranslatableResource
+    end
+  end
+end
+```
+
+== Scopes
+
+Within core provided classes there are no `default_scopes`.
+
+== Validations
+
+All the validations are defined in the models themselves.
+
+== Callbacks
+
+The number of the callbacks is reduced to the minimum.
+
+== Concerns
+
+The concerns are used to share code between models. They are located in `app/models/concerns`.
+
+Most commonly used concerns are:
+
+- xref:`Decidim::ActsAsAuthor`
+- `Decidim::ActsAsTree`
+- `Decidim::Amendable`
+- `xref:develop:authorable.adoc[Decidim::Authorable]`
+- `xref:develop:authorable.adoc[Decidim::Coauthorable]`
+- `Decidim::DownloadYourData`
+- `xref:develop:endorsable.adoc[Decidim::Endorsable]`
+- `Decidim::FilterableResource`
+- `Decidim::Fingerprintable`
+- `xref:develop:followable.adoc[Decidim::Followable]`
+- `Decidim::FriendlyDates`
+- `Decidim::HasArea`
+- `Decidim::HasAttachmentCollections`
+- `Decidim::HasAttachments`
+- `Decidim::HasCategory`
+- `Decidim::HasComponent`
+- `Decidim::HasPrivateUsers`
+- `Decidim::HasReference`
+- `Decidim::HasResourcePermission`
+- `Decidim::HasUploadValidations`
+- `Decidim::Loggable`
+- `Decidim::NewsletterParticipant`
+- `Decidim::Paddable`
+- `Decidim::Participable`
+- `Decidim::ParticipatorySpaceResourceable`
+- `Decidim::ParticipatorySpaceUser`
+- `Decidim::Publicable`
+- `Decidim::Randomable`
+- `Decidim::RecordEncryptor`
+- `xref:develop:reportable.adoc[Decidim::Reportable]`
+- `Decidim::Resourceable`
+- `Decidim::ScopableParticipatorySpace`
+- `Decidim::ScopableResource`
+- `Decidim::Searchable`
+- `xref:develop:share_tokens.adoc[Decidim::ShareableWithToken]`
+- `xref:develop:traceable.adoc[Decidim::Traceable]`
+- `xref:develop:machine_translations.adoc[Decidim::TranslatableAttributes]`
+- `xref:develop:machine_translations.adoc[Decidim::TranslatableResource]`
+
+=== Module specific concerns
+
+- `Decidim::Comments::Commentable`
+- `Decidim::Comments::CommentableWithComponent`
+- `Decidim::Comments::HasAvailabilityAttributes`
+- `Decidim::Forms::HasQuestionnaire`
+- `Decidim::Initiatives::HasArea`
+- `Decidim::Initiatives::InitiativeSlug`
+- `Decidim::Proposals::CommentableCollaborativeDraft`
+- `Decidim::Proposals::CommentableProposal`
+- `Decidim::Proposals::ParticipatoryTextSection`
+- `Decidim::Proposals::Valuatable`
+- `Decidim::Templates::Templatable`
+
+== More information
+
+- https://edgeguides.rubyonrails.org/active_record_basics.html[Active Record documentation]

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

@@ -0,0 +1,116 @@
+= Permissions
+
+The permission class allows you to customize the security. You can use the permission class to enforce the security on the basis of the user, group, or role.
+You can read more about Decidim permissions in its own dedicated xref:develop:permissions.adoc[page].
+
+Permission classes are located in the `app/permissions/decidim/<my_module>` directory, and named: `permissions.rb`.
+
+The permission class is a simple class that inherits from `Decidim::DefaultPermissions`. And can be registered in a Permission chain among other chains that are provided by Decidim
+
+```ruby
+# frozen_string_literal: true
+
+# app/permissions/decidim/my_module/permissions.rb
+module Decidim
+  module MyModule
+    class Permissions < Decidim::DefaultPermissions
+      def permissions
+        # skip to the next chain
+        return permission_action unless user
+        # pass to the next chain, as the requested authorization
+        # is not in scope of this permission class
+        return permission_action if permission_action.scope != :public
+
+        # allow public read of the resource
+        permission_action.allow! if permission_action.action == :read
+
+        # allow full access to the resource if the user is the owner
+        # authored_by? is a method that you need to implement in your model by including
+        # Decidim::Authorable concern
+        permission_action.allow! if my_object.authored_by?(user)
+
+        # we return the permission chain
+        permission_action
+      end
+
+      private
+
+      def my_object
+        @my_object ||= context.fetch(:my_object, nil)
+      end
+
+    end
+  end
+end
+```
+
+Now that you have defined the permission class, you will need to properly register. Inside your component definition, you can populate the permissions_class_name parameter as follows:
+
+```ruby
+
+Decidim.register_component(:meetings) do |component|
+  component.permissions_class_name = "Decidim::MyModule::Permissions"
+end
+```
+
+If your controller does not handle a Decidim component (or associated), you can customize as follows in your controller:
+
+```ruby
+# frozen_string_literal: true
+
+# app/controllers/decidim/my_module/my_resource_controller.rb
+module Decidim
+  module MyModule
+    class MyResourceController < Decidim::MyModule::ApplicationController
+      include NeedsPermission
+
+      register_permissions(Decidim::MyModule::MyResourceController,
+                           ::Decidim::MyModule::Permissions,
+                           ::Decidim::Permissions)
+
+      private
+
+      def permission_class_chain
+        ::Decidim.permissions_registry.chain_for(::Decidim::MyModule::MyResourceController)
+      end
+
+      def permission_scope
+        :public
+      end
+    end
+  end
+end
+```
+
+Once you have defined those changes, you can use in your controllers the following statement:
+
+```ruby
+def index
+  enforce_permission_to :read, :resource
+  # other code specific for your business model
+end
+```
+You can also pass parameters to the `enforce_permission_to` method, as follows:
+
+```ruby
+def index
+  enforce_permission_to :read, :resource, my_object: resource
+  # other code specific for your business model
+end
+
+```
+
+Or you can check for permissions in the views:
+
+```erb
+<% if allowed_to? :read, :resource %>
+  <p> You can read this resource </p>
+<% end %>
+```
+You can also pass parameters to the `allowed_to` method, as follows:
+
+```erb
+<% if allowed_to? :read, :resource, my_object: resource %>
+  <p> You can read this resource </p>
+<% end %>
+```

data/docs/modules/develop/pages/classes/presenters.adoc

@@ -0,0 +1,129 @@
+= Presenters
+
+There are more types of presenters, that Decidim is using:
+
+- ResourcePresenter - This presenter type is used to ensure consistency by properly format the resource in the views, like creating links to the resource, formatting or escaping the resource texts, ensure the references are being correctly represented.
+- AdminLogPresenter - This presenter type is used to properly display the resource in the admin area, so that Decidim is able to display any changes done on a resource, or provide additional links, etc.
+
+== ResourcePresenter
+
+This presenter is used to show in the views the resource.
+
+The presenter classes are located in the `app/presenter/decidim/<my_module>/` directory, and named: `<my_resource>_presenter.rb`.
+
+If you need to use this, you can add in your model a method like this:
+
+``` ruby
+# Returns the presenter for this author, to be used in the views.
+# Required by ResourceRenderer.
+def presenter
+  Decidim::MyModule::MyResourcePresenter.new(self)
+end
+
+```
+
+Then, you can implement the presenter like this:
+
+```ruby
+# frozen_string_literal: true
+
+# app/presenters/decidim/my_module/my_resource_presenter.rb
+module Decidim
+  module MyModule
+    class MyResourcePresenter < Decidim::ResourcePresenter
+    end
+  end
+end
+```
+
+
+== AdminLogPresenter
+
+This presenter is used to show the admin log in the admin panel.
+
+The presenter classes are located in the `app/presenter/decidim/<my_module>/admin_log` directory, and named: `<my_resource>_presenter.rb`.
+
+If you need to use this, you can add in your model a method like this:
+
+```ruby
+def self.log_presenter_class_for(_log)
+  Decidim::MyModule::AdminLog::MyResourcePresenter
+end
+```
+
+Then, you can implement the presenter like this:
+
+```ruby
+# frozen_string_literal: true
+
+# app/presenters/decidim/my_module/admin_log/my_resource_presenter.rb
+module Decidim
+  module MyModule
+    module AdminLog
+      class MyResourcePresenter < Decidim::Log::BasePresenter
+
+        # This is the list of field types that we want to show in the admin log, in the revision history
+        def diff_fields_mapping
+          {
+            title: :i18n,
+            some_field: :boolean,
+            some_other_field: :string
+          }
+        end
+
+        # This is the i18n key that we are using to load any strings
+        def i18n_labels_scope
+          "activemodel.attributes.my_resource"
+        end
+
+        def action_string
+          case action
+          when "publish"
+            "decidim.my_module.admin_log.my_resource.#{action}"
+          else
+            super
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+When handling custom events, like `publish`, you need to add the translation to the `decidim.my_module.admin_log.my_resource` scope.
+You will also need to use a command to handle the event, having a method like this:
+
+```ruby
+# frozen_string_literal: true
+
+# app/commands/decidim/my_module/publish_my_resource.rb
+module Decidim
+  module MyModule
+    # A command with the business logic to invite an user to an organization.
+    class PublishMyResource < Decidim::Command
+      # Public: Initializes the command.
+      #
+      # form
+      # resource
+      def initialize(resource, current_user)
+        @resource = resource
+        @current_user = current_user
+      end
+
+      def call
+        return broadcast(:invalid) unless resource.condition?
+
+        Decidim.traceability.perform_action!(
+          "publish",
+          @resource,
+          @current_user
+        ) do
+          resource.publish!
+        end
+
+        broadcast(:ok)
+      end
+    end
+  end
+end
+```