ActiveInteraction

When an interaction wraps a model operation (like save), you can use errors.merge!(model.errors) inside the #execute method. This transfers validation errors from the underlying model to the interaction outcome, allowing the controller to handle them as if they were interaction errors.

  def execute
    account = Account.new(inputs)

    unless account.save
      errors.merge!(account.errors)
    end

    account
  end

You can run one interaction from within another using the #compose method.

• If the composed interaction succeeds, it returns the result (equivalent to calling .run!).
• If the composed interaction fails, execution halts immediately and its errors are merged into the caller's errors.

You can also use .import_filters to bring in input filters from another interaction, which is useful when delegating to another interaction using inputs.

class Add < ActiveInteraction::Base
  integer :x, :y

  def execute
    x + y
  end
end

class AddThree < ActiveInteraction::Base
  integer :x

  def execute
    compose(Add, x: x, y: 3)
  end
end

# Using import_filters to delegate
class AddAndDouble < ActiveInteraction::Base
  import_filters Add

  def execute
    compose(Add, inputs) * 2
  end
end

To use ActiveInteraction in your project, add it to your Gemfile or install it manually via the command line. It is recommended to use version ~> 5.5.

gem 'active_interaction', '~> 5.5'

Interactions behave like ActiveModel, meaning they can be initialized with .new and used directly in Rails forms.

To make an interaction work effectively with Rails forms, implement the #to_model method. This ensures the view uses the correct model context.

In the controller, you can initialize a new interaction instance to pass to the new action:

def new
  @account = CreateAccount.new
end

class CreateAccount < ActiveInteraction::Base
  string :first_name, :last_name

  validates :first_name, :last_name, presence: true

  def to_model
    Account.new
  end

  def execute
    account = Account.new(inputs)

    unless account.save
      errors.merge!(account.errors)
    end

    account
  end
end

Calling .run! on an interaction that fails to find a record will raise an ActiveInteraction::InvalidInteractionError. In Rails, this results in a 500 error instead of a 404.

To correctly trigger a 404, use .run and manually raise ActiveRecord::RecordNotFound if the outcome is invalid.

# GET /accounts/:id
def show
  @account = find_account!
end

private

def find_account!
  outcome = FindAccount.run(params)

  if outcome.valid?
    outcome.result
  else
    fail ActiveRecord::RecordNotFound, outcome.errors.full_messages.to_sentence
  end
end

ActiveInteraction integrates with ActiveModel validations. After ActiveInteraction verifies the input types via filters, it then runs any validates declarations you have defined. If either the type filters or the validations fail, the #execute method will not run.

class SayHello < ActiveInteraction::Base
  string :name

  validates :name, presence: true

  def execute
    "Hello, #{name}!"
  end
end

# This will raise an error because of the ActiveModel presence validation
SayHello.run!(name: '')
# => ActiveInteraction::InvalidInteractionError: Name can't be blank

An interaction can be used as a form object in Rails. To make it behave like a specific model (e.g., for form_for to generate correct URLs and parameter names), implement the to_model method to return an instance of that model.

When using .run, the returned outcome can be used to check validity and display errors in the view, similar to an ActiveRecord object.

# In the interaction class
class CreateAccount < ActiveInteraction::Base
  def to_model
    Account.new
  end
end

# In the controller
def create
  outcome = CreateAccount.run(params.fetch(:account, {}))
  if outcome.valid?
    redirect_to(outcome.result)
  else
    @account = outcome
    render(:new)
  end
end

# In the view
<%= form_for @account do |f| %>
  <%= f.text_field :first_name %>
<% end %>

ActiveInteraction can replace models or controllers for handling business logic in Rails applications.

Recommended Directory Structure

It is recommended to place interactions in app/interactions and group them by model to maintain organization:

app/
  controllers/
    accounts_controller.rb
  interactions/
    accounts/
      create_account.rb
      destroy_account.rb
      find_account.rb
      list_accounts.rb
      update_account.rb
  models/
    account.rb
  views/
    account/
      edit.html.erb
      index.html.erb
      new.html.erb
      show.html.erb

ActiveInteraction is i18n aware. You can customize error messages and attribute names by adding translations to your locale files (e.g., config/locales/en.yml).

Key translation namespaces:

• active_interaction.types: To rename type names (e.g., string to text).
• active_interaction.errors.messages: To customize error message templates.
• active_interaction.attributes: To provide human-readable names for specific interaction attributes.

en:
  active_interaction:
    attributes:
      product:
        num: 'Number'
    types:
      string: 'text'
    errors:
      messages:
        invalid_type: '%{type} is not valid'