Collection hook

Forest Admin allows customizing at a very low level the behavior of any given Collection via the usage of Collection Hooks.

Collection Hooks are a very powerful feature and require special care when using them.

How it works

Any given Collection should implement all of the following functions:

  • list

  • create

  • update

  • delete

  • aggregate

The Collection Hooks feature allows executing code before and/or after any of these functions, providing an easy way to interact with your Collections.

To declare a Hook on a Collection, the following information is required:

  • A lifecycle position (Before | After)

  • An action type (List | Create | Update | Delete | Aggregate)

  • A callback, that will receive a context matching the provided hook position and hook definition.

Basic use cases

In the following example, we want to prevent a set of users from updating any records of the Transactions table. We want to check if the user email is allowed to update a record via an external API call.

@create_agent.customize_collection('transactions') do |collection|
  collection.add_hook('Before', 'Update') do |context|
    # context.caller contains information about the current user, the defined timezone, etc.
    # In this case, context.caller.email is the email used in Forest Admin by the user that initiated the call
    is_allowed = my_function_to_check_user_is_allowed(context.caller.email)
    unless is_allowed
      # Raising an error here will prevent the execution of the update function,
      # as well as any other hooks that may be defined afterwards.
      context.throw_forbidden_error("#{context.caller.email} is not allowed!")
    end
  end
end

Another good example would be the following: Each time a new User is created in the database, I want to send him an email.

@create_agent.customize_collection('user') do |collection|
  collection.add_hook('After', 'Create') do |context|
    # The result of the create function always return a record
    email = context.record['email']
    MyEmailSender.send_email(
      from: '[email protected]',
      to: email,
      message: 'Hey, a new account was created with this email.'
    )
  end
end

Last updated

Was this helpful?