= Activity log

In order to make your component compatible with the activity log, you need to follow these steps:

. Make your model include the `Decidim::Traceable` module. This will let Decidim create versions every time your model records are changed. It uses https://github.com/airblade/paper_trail[`paper_trail`] to generate the versions.
. Make your commands use `Decidim.traceability` to create and update records. Documentation can be found in `Decidim::Traceability`. This should set the author of the change in your record properly.

That is all you need to do to get it working, really. We have a default way to present logs that Just Works™. Keep reading if you want to customize how the logs for your resources look!

== The default renderer

The default renderer does not know many things. It knows the author, what action was done, the resource affected and the space where the resource resides. When the resource is updated it shows the diff of all the fields that have been changed, with the old and new values for each field. values are not formatted in any specific way, so you might see some weirdly formatted values on the log diff: that is how it is rendered from the database.

== Customizing the logs for your resources

The default presenter does not fulfill your needs? You might want to create your own presenter if you find yourself in one of these cases:

* You want to show what type of resource is affected by the action log
* The default renderer cannot find the correct field to render the resource name
* You want to show more info
* You want to change the order of the factors in the log sentence
* You want to change the format of the values in the diff

Next, you will learn how to create your own resource presenter.

Custom presenters should be named as `Decidim::<your module name>::<log name>::<your model name>Presenter`. There is currently only one log, `AdminLog`. This means that if your model is `Decidim::Accountability::Result`, then your admin log presenter is must be `Decidim::Accountability::AdminLog::ResultPresenter`. You can inherit from `Decidim::Log::BasePresenter` for simplicity:

[source,ruby]
----
module Decidim
  module Accountability
    module AdminLog
      class ResultPresenter < Decidim::Log::BasePresenter
      end
    end
  end
end
----

Some examples with basic customization follow, although you can read the source code docs and overwrite any method you need.

=== Changing the action log sentence

In order to change the default sentence to something that fits better to your resource, you can overwrite the `action_string` method in your presenter:

[source,ruby]
----
module Decidim
  module Accountability
    module AdminLog
      class ResultPresenter < Decidim::Log::BasePresenter
        private

        def action_string
          case action
          when "create"
            "decidim.accountability.admin_log.result.create"
          when "update"
            "decidim.accountability.admin_log.result.update"
          end
        end
      end
    end
  end
end
----

This is useful to show the resource type in the sentence.

=== Limiting what fields get presented in the diff

By default, all changed fields are presented in the diff. In order to limit them, overwrite the `diff_fields_mapping` method in your custom presenter. It has to return a `Hash`, where keys are the name of the attributes and values are the presenters that render the attributes. *Limitations*: we can only show diffs for column fields, not dynamic methods, so the `diff_fields_mapping` only accepts column names.

In this example, we are telling our presenter to only present the `start_date` as a date, the `title` as an i18n field, the `decidim_scope_id` with no particular presenter, and `progress` as a percentage:

[source,ruby]
----
module Decidim
  module Accountability
    module AdminLog
      class ResultPresenter < Decidim::Log::BasePresenter
        private

        def diff_fields_mapping
          {
            start_date: :date,
            title: :i18n,
            decidim_scope_id: :default,
            progress: :percentage
          }
        end
      end
    end
  end
end
----

==== Value types presenters

Decidim comes with some default value types presenters to be used in the diffs. They all live in `Decidim::Log::ValueTypes`, check the source code for the full list. These presenters are used with a symbol, but you can use your own value type presenter if you use a string:

[source,ruby]
----
module Decidim
  module Accountability
    module AdminLog
      class ResultPresenter < Decidim::Log::BasePresenter
        private

        def diff_fields_mapping
          {
            decidim_scope_id: "Decidim::Accountability::AdminLog::ValueTypes::MyCustomPresenter",
          }
        end
      end
    end
  end
end
----

Then you can write your own value presenter as:

[source,ruby]
----
module Decidim
  module Accountability
    module AdminLog
      module ValueTypes
        class MyCustomPresenter < Decidim::Log::Valuetypes::DefaultPresenter
          def present
            return unless value
            "My super duper value: #{value}"
          end
        end
      end
    end
  end
end
----

== Multiple logs

Although Decidim currently only has a log for the admin section, in the future we might need an activity log for the public part. It is easy to assume we might need to render the same data in different formats, so we need to differentiate the presenters for each log. The current system handles the case for multiple logs, although we only have one.