Override writing behavior

This is the official documentation of the agent_ruby Ruby agent.

Forest Admin allows replacing the default field writing behavior with your own custom logic.

This is useful when you want to change how a given field behaves, but also to make computed fields writable.

How does it work

The replace_field_writing function allows to change the behavior of any change by creating a new patch that will be applied to the record.

You should refrain from using handlers that have side effects (to perform error handling, validation, ...) and use hooks instead.

Making a field read-only

Can be achieved without any code in the field settings ↗.

Examples

Changing other fields in the same record

In the following example, editing or creating a fullName will update both firstName and lastName fields of the record.

Traditional Syntax

Using full context methods with customize_collection:

@create_agent.customize_collection('customer') do |collection|
  collection.replace_field_writing('fullName') do |value|
    first_name, last_name = value.split(' ')
    {
      'firstName' => first_name,
      'lastName' => last_name
    }
  end
end

DSL Syntax

Using simplified DSL with collection:

@create_agent.collection :customer do |collection|
  collection.replace_writing :fullName do |value|
    first_name, last_name = value.split(' ')
    {
      'firstName' => first_name,
      'lastName' => last_name
    }
  end
end

Having specific behavior only for updates

You can have different behavior for creations and updates.

In this example, each time the firstName field is edited, we also want to update a timestamp field.

Traditional Syntax

Using full context methods with customize_collection:

@create_agent.customize_collection('customer') do |collection|
  collection.replace_field_writing('firstName') do |value, context|
    case context.action
    when 'create'
      {
        'firstName' => value,
        'firstNameLastEdited' => nil
      }
    when 'update'
      {
        'firstName' => value,
        'firstNameLastEdited' => Time.now.iso8601
      }
    else
      raise 'Unexpected value'
    end
  end
end

DSL Syntax

Using simplified DSL with collection:

@create_agent.collection :customer do |collection|
  collection.replace_writing :firstName do |value, context|
    case context.action
    when 'create'
      {
        'firstName' => value,
        'firstNameLastEdited' => nil
      }
    when 'update'
      {
        'firstName' => value,
        'firstNameLastEdited' => Time.now.iso8601
      }
    else
      raise 'Unexpected value'
    end
  end
end

Changing fields in related records

Handling relationships inside a replaceFieldWriting``replace_field_writing will only work for ManyToOne and OneToOne relationships.

In this simple example, we have two collections that are linked together:

• The Users collection has a job and a portfolioId as foreignKey

• The Portfolios collection has a title

When the user updates his job field we want also to update the title of the portfolio by the job name.

Traditional Syntax

Using full context methods with customize_collection:

@create_agent.customize_collection('customer') do |collection|
  collection.replace_field_writing('job') do |value, _context|
    {
      'job' => value,
      'portfolio' => { 'title' => value }
    }
  end
end

DSL Syntax

Using simplified DSL with collection:

@create_agent.collection :customer do |collection|
  collection.replace_writing :job do |value|
    {
      'job' => value,
      'portfolio' => { 'title' => value }
    }
  end
end

If the relationships do not exist it will create them with the given field values.

You can also provide another portfolioId to update the relationships and their fields:

Traditional Syntax

Using full context methods with customize_collection:

@create_agent.customize_collection('customer') do |collection|
  collection.replace_field_writing('job') do |value, _context|
    {
      'job' => value,
      'portfolioId' => 8,
      'portfolio' => { 'title' => value }
    }
  end
end

DSL Syntax

Using simplified DSL with collection:

@create_agent.collection :customer do |collection|
  collection.replace_writing :job do |value|
    {
      'job' => value,
      'portfolioId' => 8,
      'portfolio' => { 'title' => value }
    }
  end
end

Of course, you can chain the relationships. For example, if a portfolio has a one-to-one relationship with the formats collection, you can update it by writing the right path.

Traditional Syntax

Using full context methods with customize_collection:

@create_agent.customize_collection('customer') do |collection|
  collection.replace_field_writing('job') do |value, _context|
    {
      'job' => value,
      'portfolioId' => 8,
      'portfolio' => {
        'title' => value,
        'format' => { 'name' => 'pdf' }
      }
    }
  end
end

DSL Syntax

Using simplified DSL with collection:

@create_agent.collection :customer do |collection|
  collection.replace_writing :job do |value|
    {
      'job' => value,
      'portfolioId' => 8,
      'portfolio' => {
        'title' => value,
        'format' => { 'name' => 'pdf' }
      }
    }
  end
end