decidim 0.4.4 → 0.5.0

data/decidim-core/lib/decidim/exporters/json.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Decidim
+  module Exporters
+    # Exports a JSON version of a provided hash, given a collection and a
+    # Serializer.
+    class JSON < Exporter
+      # Public: Generates a JSON representation of a collection and a
+      # Serializer.
+      #
+      # Returns an ExportData with the export.
+      def export
+        data = ::JSON.pretty_generate(@collection.map do |resource|
+          @serializer.new(resource).serialize
+        end)
+
+        ExportData.new(data, "json")
+      end
+    end
+  end
+end

data/decidim-core/lib/decidim/exporters/serializer.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Decidim
+  module Exporters
+    # This is an abstract class with a very naive default implementation
+    # for the exporters to use. It can also serve as a superclass of your
+    # own implementation.
+    #
+    # It is used to be run against each element of an exportable collection
+    # in order to extract relevant fields. Every export should specify their
+    # own serializer or this default will be used.
+    class Serializer
+      attr_reader :resource
+
+      # Initializes the serializer with a resource.
+      #
+      # resource - The Object to serialize.
+      def initialize(resource)
+        @resource = resource
+      end
+
+      # Public: Returns a serialized view of the provided resource.
+      #
+      # Returns a nested Hash with the fields.
+      def serialize
+        @resource.to_h
+      end
+    end
+  end
+end

data/decidim-core/lib/decidim/faker/localized.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "faker"
+
+module Decidim
+  module Faker
+    # A Custom Faker wrapper so we can easily generate fake data for each
+    # locale in localized attributes.
+    module Localized
+      # Fakes a company name.
+      #
+      # Returns a Hash with a value for each locale.
+      def self.company
+        localized do
+          ::Faker::Company.name
+        end
+      end
+
+      # Fakes a person name.
+      #
+      # Returns a Hash with a value for each locale.
+      def self.name
+        localized do
+          ::Faker::Name.name
+        end
+      end
+
+      # Builds a Lorem Ipsum word.
+      #
+      # Returns a Hash with a value for each locale.
+      def self.word
+        localized do
+          ::Faker::Lorem.word
+        end
+      end
+
+      # Builds many Lorem Ipsum words. See Faker::Lorem for options.
+      #
+      # Returns a Hash with a value for each locale.
+      def self.words(*args)
+        localized do
+          ::Faker::Lorem.words(*args)
+        end
+      end
+
+      # Builds a Lorem Ipsum character.
+      #
+      # Returns a Hash with a value for each locale.
+      def self.character
+        localized do
+          ::Faker::Lorem.character
+        end
+      end
+
+      # Builds many Lorem Ipsum characters. See Faker::Lorem for options.
+      #
+      # Returns a Hash with a value for each locale.
+      def self.characters(*args)
+        localized do
+          ::Faker::Lorem.characters(*args)
+        end
+      end
+
+      # Builds a sentence with Lorem Ipsum words. See Faker::Lorem for options.
+      #
+      # Returns a Hash with a value for each locale.
+      def self.sentence(*args)
+        localized do
+          ::Faker::Lorem.sentence(*args)
+        end
+      end
+
+      # Builds many sentences with Lorem Ipsum words. See Faker::Lorem for options.
+      #
+      # Returns a Hash with a value for each locale.
+      def self.sentences(*args)
+        localized do
+          ::Faker::Lorem.sentences(*args)
+        end
+      end
+
+      # Builds a paragraph with Lorem Ipsum words. See Faker::Lorem for options.
+      #
+      # Returns a Hash with a value for each locale.
+      def self.paragraph(*args)
+        localized do
+          ::Faker::Lorem.paragraph(*args)
+        end
+      end
+
+      # Builds many paragraphs with Lorem Ipsum words. See Faker::Lorem for options.
+      #
+      # Returns a Hash with a value for each locale.
+      def self.paragraphs(*args)
+        localized do
+          ::Faker::Lorem.paragraphs(*args)
+        end
+      end
+
+      # Builds a question with Lorem Ipsum words. See Faker::Lorem for options.
+      #
+      # Returns a Hash with a value for each locale.
+      def self.question(*args)
+        localized do
+          ::Faker::Lorem.question(*args)
+        end
+      end
+
+      # Builds many questions with Lorem Ipsum words. See Faker::Lorem for options.
+      #
+      # Returns a Hash with a value for each locale.
+      def self.questions(*args)
+        localized do
+          ::Faker::Lorem.questions(*args)
+        end
+      end
+
+      # Sets the given text as the value for each locale.
+      #
+      # text - The String text to set for each locale.
+      #
+      # Returns a Hash with a value for each locale.
+      def self.literal(text)
+        Decidim.available_locales.inject({}) do |result, locale|
+          result.update(locale => text)
+        end.with_indifferent_access
+      end
+
+      # Wrapps a text build by the block with some other text.o
+      #
+      # before - The String text to inject at the begining of each value.
+      # after  - The String text to inject at the end of each value.
+      # block  - A Block that generates a Hash with a text for each locale.
+      #
+      # Example:
+      #
+      #   Decidim::Faker::Localized.wrapped("<p>", "</p>") do
+      #     Decidim::Faker::Localized.sentence(5)
+      #   end
+      #
+      # Returns a Hash with a value for each locale.
+      def self.wrapped(before, after)
+        result = yield
+        result.inject({}) do |wrapped, (locale, text)|
+          wrapped.update(locale => [before, text, after].join)
+        end
+      end
+
+      # nodoc
+      def self.localized
+        Decidim.available_locales.inject({}) do |result, locale|
+          text = ::Faker::Base.with_locale(locale) do
+            yield
+          end
+
+          result.update(locale => text)
+        end.with_indifferent_access
+      end
+
+      private_class_method :localized
+    end
+  end
+end

data/decidim-core/lib/decidim/feature_manifest.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require "decidim/settings_manifest"
+require "decidim/features/export_manifest"
+
+module Decidim
+  # This class handles all the logic associated to configuring a feature
+  # associated to a participatory process.
+  #
+  # It's normally not used directly but through the API exposed through
+  # `Decidim.register_feature`.
+  class FeatureManifest
+    include ActiveModel::Model
+    include Virtus.model
+
+    attribute :admin_engine, Rails::Engine
+    attribute :engine, Rails::Engine
+
+    attribute :name, Symbol
+    attribute :hooks, Hash[Symbol => Array[Proc]], default: {}
+
+    # A path with the `scss` stylesheet this engine provides. It is used to
+    # mix this engine's stylesheets with the main app's stylesheets so it can
+    # use the scss variables and mixins provided by Decidim::Core.
+    attribute :stylesheet, String, default: nil
+
+    # A path with the `scss` admin stylesheet this engine provides. It is used
+    # to mix this engine's stylesheets with the main app's admin stylesheets so
+    # it can use the scss variables and mixins provided by Decidim::Admin.
+    attribute :admin_stylesheet, String, default: nil
+
+    # A String with the feature's icon. The icon must be stored in the
+    # engine's assets path.
+    attribute :icon, String
+
+    # Actions are used to validate permissions of a feature against particular
+    # authorizations or potentially other authorization rules.
+    #
+    # An example would be `vote` on participatory processes, or `create_meeting`
+    # on meetings.
+    #
+    # A Feature can expose as many actions as it wants and the admin panel will
+    # generate a UI to handle them. There's a set of controller helpers available
+    # as well that allows checking for those permissions.
+    attribute :actions, Array[String]
+
+    validates :name, presence: true
+
+    # Public: Registers a hook to this manifest. Hooks get fired when some
+    # lifecycle events happen, like the creation of a component or its
+    # destruction.
+    #
+    # event_name - A String or Symbol with the event name.
+    # &block     - The block to run when the hook gets triggered.
+    #
+    # Returns nothing.
+    def on(event_name, &block)
+      hooks[event_name.to_sym] ||= []
+      hooks[event_name.to_sym] << block
+    end
+
+    # Public: Runs all the hooks associated with this manifest and a particular
+    # event.
+    #
+    # event_name - A String or Symbol with the event name.
+    # context    - An optional context that will be provided to the block as a
+    #              parameter. Usually the subject of the hook.
+    #
+    # Returns nothing.
+    def run_hooks(event_name, context = nil)
+      return unless hooks[event_name]
+      hooks[event_name.to_sym].each do |hook|
+        hook.call(context)
+      end
+    end
+
+    # Semiprivate: Resets all the hooks of this manifest. Mostly useful when
+    # testing.
+    #
+    # Returns nothing.
+    def reset_hooks!
+      self.hooks = {}
+    end
+
+    # Public: A block that gets called when seeding for this feature takes place.
+    #
+    # Returns nothing.
+    def seeds(&block)
+      @seeds = block
+    end
+
+    # Public: Creates the seeds for this features in order to populate the database.
+    #
+    # Returns nothing.
+    def seed!(process)
+      @seeds&.call(process)
+    end
+
+    # Public: Adds configurable attributes for this feature, scoped to a name. It
+    # uses the DSL specified under `Decidim::SettingsManifest`.
+    #
+    # name - Either `global` or `step`
+    # &block - The DSL present on `Decidim::SettingsManifest`
+    #
+    # Examples:
+    #
+    #   feature.settings(:global) do |settings|
+    #     settings.attribute :voting_enabled, type: :boolean, default: true
+    #   end
+    #
+    # Returns nothing.
+    def settings(name = :global, &block)
+      @settings ||= {}
+      name = name.to_sym
+      settings = (@settings[name] ||= SettingsManifest.new)
+      yield(settings) if block
+      settings
+    end
+
+    # Public: Registers a resource inside a feature manifest. Exposes a DSL
+    # defined by `Decidim::ResourceManifest`.
+    #
+    # Resource manifests are a way to expose a resource from one engine to
+    # the whole system. This was resoruces can be linked between them.
+    #
+    # block - A Block that will be called to set the Resource attributes.
+    #
+    # Returns nothing.
+    def register_resource
+      manifest = ResourceManifest.new
+      manifest.feature_manifest = self
+      yield(manifest)
+      manifest.validate!
+      resource_manifests << manifest
+    end
+
+    # Public: Registers an export artifact with a name and its properties
+    # defined in `Decidim::Features::ExportManifest`.
+    #
+    # Export artifacts provide an unified way for features to register
+    # exportable collections serialized via a `Serializer` than eventually
+    # are transformed to their formats.
+    #
+    # name  - The name of the artifact. Should be unique in the context of
+    #         the feature.
+    # block - A block that receives the manifest as its only argument.
+    #
+    # Returns nothing.
+    def exports(name, &block)
+      @exports ||= []
+      @exports << [name, block]
+      @export_manifests = nil
+    end
+
+    # Pubic: Returns a collection of previously registered export manifests
+    # for this feature.
+    #
+    # Returns an Array<Decidim::Features::ExportManifest>.
+    def export_manifests
+      @export_manifests ||= @exports.map do |(name, block)|
+        Decidim::Features::ExportManifest.new(name).tap do |manifest|
+          block.call(manifest)
+        end
+      end
+    end
+
+    # Public: Finds all the registered resource manifest's via the
+    # `register_resource` method.
+    #
+    # Returns an Array[ResourceManifest].
+    def resource_manifests
+      @resource_manifests ||= []
+    end
+
+    # Public: Stores an instance of StatsRegistry
+    def stats
+      @stats ||= StatsRegistry.new
+    end
+
+    # Public: Registers a stat inside a feature manifest.
+    #
+    # name - The name of the stat
+    # options - A hash of options
+    #         * primary: Whether the stat is primary or not.
+    #         * priority: The priority of the stat used for render issues.
+    # block - A block that receive the features to filter out the stat.
+    #
+    # Returns nothing.
+    def register_stat(name, options = {}, &block)
+      stats.register(name, options, &block)
+    end
+  end
+end

data/decidim-core/lib/decidim/feature_validator.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# A custom validator to make sure features are correctly assigned to a model.
+#
+# Adds a presence validation and checks that the manifest is the correct one.
+class FeatureValidator < ActiveModel::EachValidator
+  # Validates the arguiments passed to the validator.
+  def check_validity!
+    raise ArgumentError, "You must include a `manifest` option with the name of the manifest to validate when validating a feature" unless options[:manifest].present?
+  end
+
+  # The actual validator method. It is called when ActiveRecord iterates
+  # over all the validators.
+  def validate_each(record, attribute, feature)
+    unless feature
+      record.errors[attribute] << :blank
+      return
+    end
+
+    record.errors[attribute] << :invalid if feature.manifest_name.to_s != options[:manifest].to_s
+  end
+end

data/decidim-core/lib/decidim/features.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Decidim
+  # This module contains all logic related to decidim's Features, the main
+  # building block to extend functionalities in a participatory process.
+  module Features
+    autoload :BaseController, "decidim/features/base_controller"
+  end
+end