Components

decidim --component engine_name

# :my_component is the unique name of the component that will be globally registered.
Decidim.register_component(:my_component) do |component|
  # The user will be redirected to the component's engine when accessing it through
  # the public page of a participatory space. A component's engine is isolated
  # from the outside so it can deal with its own dependencies without having to
  # know its render path or its parent resources.
  component.engine = MyComponent::Engine

  # A component's admin engine will get rendered on the admin panel and follows
  # the same principles as the engine. It is isolated from the outside and
  # does not care about external dependencies. It only needs to care about its
  # underlying `component`.
  component.admin_engine = MyComponent::AdminEngine

  # Component hooks get called whenever relevant lifecycle events happen, like
  # adding a new component o destroying it. You always get passed the instance
  # so you can act on it. Creating or destroying a comoponent is transactional
  # along with its hooks, so you can decide to halt the transaction by raising
  # an exception.
  #
  # Valid hook names are :create and :destroy.
  component.on(:create) do |component|
    MyComponent::DoSomething.with(component)
  end

  # Export definitions allow components to declare any number of exportable files.
  #
  # An export definition needs a unique name, a collection, and a Serializer. If
  # no serializer is provided, a default, naive one will be used.
  #
  # Exports are then exposed via the UI, so the implementer only needs to care
  # about the export definitions.
  component.exports :component_resources do |exports|
    exports.collection do |component|
      MyComponent::Resource.where(component: component)
    end

    exports.serializer MyComponent::ResourceSerializer
  end

  # Import definitions allow data to be imported into a component.
  #
  # For now supported formats for imports are CSV, JSON and Excel (.xlsx).
  # Every resource type needs it is own creator, which creates resource from
  # parsed data. You also need to define specific messages for the importer and
  # can provide some extra options, too.
  component.imports :component_resources do |imports|
    # Define a form partial if you want to add custom fields to the form
    # imports.form_view = "decidim/my_component/admin/imports/component_resources_fields"
    # Define a custom form class name if you want to customize the form object
    # imports.form_class_name = "MyComponent::Admin::CustomImportForm"

    # Define UI messages for the import functionality
    imports.messages do |msg|
      # The resource name is used in the success message:
      # "X your resources successfully imported" (the "your resources" part)
      msg.set(:resource_name) { |count: 1| I18n.t("decidim.my_component.admin.imports.resources.component_resources", count: count) }
      # The title is the message shown at the top of the import page
      msg.set(:title) { I18n.t("decidim.my_component.admin.imports.title.component_resources") }
      # The label is what is shown in the import dropdown menu
      msg.set(:label) { I18n.t("decidim.my_component.admin.imports.label.component_resources") }
      # The optional help message can be used to provide additional contextual
      # help for the import file, e.g. how it should be formatted
      # msg.set(:help) { I18n.t("decidim.my_component.admin.imports.help.component_resources") }
    end

    # Define the creator that is used to create resources from the import data
    imports.creator MyComponent::ResourceCreator

    # Define an example data set to guide the user how to format the import
    # file. This will be available for download in the import view for each
    # supported import format.
    imports.example do |import_component|
      organization = import_component.organization
      [
        organization.available_locales.map { |l| "title/#{l}" } + organization.available_locales.map { |l| "body/#{l}" },
        organization.available_locales.map { "Example title" } + organization.available_locales.map { "Example body" },
        organization.available_locales.map { "Example title 2" } + organization.available_locales.map { "Example body 2" },
      ]
    end
  end
end

# :my_component is the unique name of the component that will be globally registered.
Decidim.register_component(:my_component) do |component|
  ...

  component.settings(:global) do |settings|
    settings.attribute :a_boolean_setting, type: :boolean, default: true
    settings.attribute :an_enum_setting, type: :enum, default: "all", choices: %w(all one none)
  end

  component.settings(:step) do |settings|
    settings.attribute :a_text_setting, type: :text, default: false, required: true, translated: true, editor: true
    settings.attribute :a_lambda_enum_setting, type: :enum, default: "all", choices: -> { SomeClass.enum_options }
    settings.attribute :a_readonly_setting, type: :string, readonly: ->(context) { SomeClass.readonly?(context[:component]) }
  end

  ...
end