# Override writing behavior

{% hint style="success" %}
This is the official documentation of the `agent_ruby` Ruby agent.
{% endhint %}

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](https://docs.forestadmin.com/developer-guide-agents-ruby/agent-customization/fields/computed) 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](https://docs.forestadmin.com/developer-guide-agents-ruby/agent-customization/hooks).

### Making a field read-only

{% hint style="info" %}
Can be achieved without any code [in the field settings](https://docs.forestadmin.com/user-guide/collections/customize-your-fields#basic-settings).
{% endhint %}

### 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`:

```ruby
@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`:

```ruby
@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`:

```ruby
@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`:

```ruby
@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

{% hint style="info" %}
Handling relationships inside a `replaceFieldWriting``replace_field_writing` will only work for `ManyToOne` and `OneToOne` relationships.
{% endhint %}

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`:

```ruby
@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`:

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

{% hint style="info" %}
If the relationships do not exist it will create them with the given field values.
{% endhint %}

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

#### Traditional Syntax

Using full context methods with `customize_collection`:

```ruby
@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`:

```ruby
@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`:

```ruby
@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`:

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