Collaboration API

Per-option reference for the collaboration add-on. For task-oriented documentation, installation, and worked examples, see the Collaboration guide.

Collaboration is configured per resource through the self.collaboration hash, plus the collaboration_timeline DSL method and a set of policy methods:

# app/avo/resources/project.rb
class Avo::Resources::Project < Avo::BaseResource
  self.collaboration = {
    # options listed below
  }

  def fields
    # ...
    collaboration_timeline
  end
end

Resource configuration

Keys of the self.collaboration hash.

-> author

Configures how the timeline displays the author of comments, reactions, and automatic entries. The author itself is always resolved from Avo::Current.user; this hash only controls display.

self.collaboration = {
  author: {
    name_property: :name
  }
}

• Type: Hash
• Default: nil
• Keys:

Key	Type	Description
name_property	Symbol or String	The attribute on the author object holding their display name

-> watchers

An array of watchers. Each watcher records an automatic timeline entry whenever the given attribute changes on the record.

self.collaboration = {
  watchers: [
    {
      property: :name,
      message: -> { "#{property} changed: #{old_value} → #{new_value}" }
    },
    { property: :status, i18n_message_key: "avo.collaboration.custom_property_changed_html" },
    { property: :stage }
  ]
}

• Type: Array of Hashes
• Default: nil
• Keys:

Key	Type	Description
property	Symbol or String	(required) The attribute to watch for changes.
message	Proc	Builds a custom message for the entry. Executed with resource, record, property, old_value, and new_value in scope.
i18n_message_key	String	An I18n key used to translate the message instead of a message proc.

When a watcher provides neither message nor i18n_message_key, Avo falls back to the avo.collaboration.property_changed translation.

Safe HTML translations

When the translation key ends in _html, Rails treats the value as safe HTML, so message translations may contain markup. See Rails' safe HTML translations.

-> reactions

Customizes the emoji available when reacting to timeline entries.

self.collaboration = {
  reactions: {
    options: %w[👍 👎 ❤️ 🚀 👀]
  }
}

• Type: Hash with key options (Array of Strings)
• Default: 👍 👎 😀 🎉 😕 ❤️ 🚀 👀 💡 🔥
• Behavior: Reactions are always enabled. When reactions is omitted, the default set above is used; supply options to replace it with your own list.

Timeline

-> collaboration_timeline

DSL method called inside a resource's fields block. Renders the collaboration timeline — comments, reactions, and automatic property-change entries — at the position where it's called.

def fields
  field :id, as: :id
  field :name

  collaboration_timeline
end

• Type: DSL method (no arguments)

Authorization

Policy methods, defined on your resource's Pundit-style policy, that gate access to the timeline. Each returns a boolean. These extend Avo's authorization system.

-> collaboration_view_timeline?

Whether the user can view the timeline on a record.

# app/policies/project_policy.rb
def collaboration_view_timeline?
  show?
end

• Type: Policy method returning Boolean

-> collaboration_create_entry?

Whether the user can create new entries (comments and messages).

# app/policies/project_policy.rb
def collaboration_create_entry?
  current_user.team_member? && show?
end

• Type: Policy method returning Boolean

-> collaboration_destroy_entry?

Whether the user can destroy an entry. The record passed to the policy is either an action entry (generated automatically when a watched attribute changes) or a comment entry (Avo::Collaboration::Comment, posted by a user).

# app/policies/project_policy.rb
def collaboration_destroy_entry?
  return true if current_user.admin?

  record.is_a?(Avo::Collaboration::Comment) && record.author == current_user
end

• Type: Policy method returning Boolean