This is the official documentation of the agent_ruby Ruby agent.
Forest Admin allows creating new Fields on any Collection, either computationally, by fetching data on an external API or based on other data that is available on the connected data sources.
By default, the fields that you create will be read-only, but you can make them filterable, sortable, and writable by using the relevant methods.
How does it work?
When creating a new field you will need to provide:
Field
Description
column_type
dependencies
List of fields that you need from the source records and linked records in order to run the handler
values
Handler which computes the new value for a batch of records
enum_values (optional)
When columnType is Enum, you must specify the values that the field will support
Examples
Adding a field by concatenating other fields
This example adds a user.displayName field, which is computed by concatenating the first and last names.
include ForestAdminDatasourceCustomizer::Decorators::Computed
# User Collection has the following structure: { id, firstName, lastName }
@create_agent.customize_collection('user') do |collection|
collection.add_field(
'displayName',
ComputedDefinition.new(
# Type of the new field
column_type: 'String',
# Dependencies which are needed to compute the new field (must not be empty)
dependencies: %w[firstName lastName],
# Compute function for the new field
# Note that the function computes the new values in batches: the return value must be
# an array which contains the new values in the same order than the provided records.
values: proc { |records| records.map { |record| "#{record["firstName"]} #{record["lastName"]}" } }
)
)
end
Adding a field that depends on another computed field
This example adds a user.displayName field, which is computed by concatenating the first and last names, and then another which capitalize it.
include ForestAdminDatasourceCustomizer::Decorators::Computed
# User Collection has the following structure: { id, firstName, lastName }
@create_agent.customize_collection('user') do |collection|
collection
# Create a first field which is computed by concatenating the first and last names
.add_field(
'displayName',
ComputedDefinition.new(
column_type: 'String',
dependencies: %w[firstName lastName],
values: proc { |records| records.map { |record| "#{record['firstName']} #{record['lastName']}" } }
)
)
# Create a second field which is computed by uppercasing the first field
.add_field(
'displayNameCaps',
ComputedDefinition.new(
column_type: 'String',
dependencies: ['displayName'], # It is legal to depend on another computed field
values: proc { |records| records.map { |record| record['displayName'].upcase } }
)
)
end
Adding a field that depends on a many-to-one relationship
We can improve the previous example by adding the city of the user to the display name.
include ForestAdminDatasourceCustomizer::Decorators::Computed
# Structure:
# User { id, addressId, firstName, lastName }
# Address { id, city }
@create_agent.customize_collection('user') do |collection|
collection.add_field(
'displayName',
ComputedDefinition.new(
column_type: 'String',
# We added 'address:city' in the list of dependencies,
# which tells forest to fetch the related record
dependencies: %w[firstName lastName address:city],
values: proc { |records| records.map { |record| "#{record['firstName']} #{record['lastName']} (from #{record['address']['city']})" } }
)
)
end
Adding a field that depends on a one-to-many relationship
Let's now add a user.totalSpending field by summing the amount of all orders.
include ForestAdminDatasourceCustomizer::Decorators::Computed
include ForestAdminDatasourceToolkit::Components::Query
include ForestAdminDatasourceToolkit::Components::Query::ConditionTree
# Structure:
# User { id }
# Order { id, customer_id, amount }
@create_agent.customize_collection('user') do |collection|
collection.add_field(
'totalSpending',
ComputedDefinition.new(
column_type: 'Number',
dependencies: ['id'],
values: proc do |records, context|
record_ids = records.map { |record| record['id'] }
# We're using Forest Admin's query interface
filter = Filter.new(condition_tree: Nodes::ConditionTreeLeaf.new('customer_id', Operators::IN, record_ids))
aggregation = Aggregation.new(operation: 'Sum', field: 'amount', groups: [ { field: 'customer_id' } ])
rows = context.datasource.get_collection('order').aggregate(filter, aggregation)
records.map do |record|
filtered = rows.select { |row| row['group']['customer_id'] == record['id'] }
filtered.empty? ? 0 : filtered[0]['value']
end
end
)
)
end
Adding a field fetching data from an API
Let's imagine that we want to check if the email address of our users is deliverable. We can use a verification API to perform that work.
The API we're using is fictional, and the structure of the response is:
