Mongoid
This is the official documentation of the agent_ruby
Ruby agent.
The Mongoid data source allows importing collections from a Mongoid instance gem.
To make everything work as expected, you need to install the package "forest_admin_datasource_mongoid", ">= 1.0.0.beta"
.
module ForestAdminRails
class CreateAgent
def self.setup!
datasource = ForestAdminDatasourceMongoid::Datasource.new(
options: {
flatten_mode: 'auto',
}
)
@create_agent = ForestAdminAgent::Builder::AgentFactory.instance.add_datasource(datasource, {})
customize
@create_agent.build
end
end
end
Dealing with deeply nested models

When using flatten_mode: 'none'
with the Mongoid data source, each Mongoid model is mapped directly to a single Forest Admin collection without any structural transformations.
Since Mongoid allows deeply nested embedded documents, this behavior may not always be ideal:
Embedded documents (embeds_one, embeds_many) will not be treated as separate collections in Forest Admin. Instead, they will be displayed as raw JSON inside the parent document. Relations between embedded documents and their parent will not be visible as structured relationships. Forest Admin will use a JSON editor to display and modify embedded fields, rather than providing dedicated collections for them.
Understanding flattenMode
flattenMode
flattenMode: 'auto'
Automatic conversion: Embedded documents (embeds_one, embeds_many) are turned into separate collections in Forest Admin. This aligns with Mongoid’s approach, where embedded documents are tightly coupled to their parent but still modeled as distinct objects.
flattenMode: 'manual'
You are in full control on which virtual collections are created, and which fields are moved
flattenMode: 'none'
No transformation: Mongoid models are displayed as-is, with embedded objects appearing as raw JSON instead of separate collections.
not defined
Equivalent to auto
but a warning is displayed at server startup
Example
Supposing that persons
records have the following format:
{
"name": "Sherlock Holmes",
"age": 54,
"address": {
"street_name": "Baker Street",
"city": "London",
"country": "Great Britain"
},
"bills": [
{
"title": "Rent",
"amount": 0,
"issue_date": "1887-04-17",
"payed_by": ["Sherlock", "John", "Mrs Hudson"]
}
]
}
With flatten_mode: 'auto'
, Forest Admin will automatically generate two separate collections:
persons
fields:
name
,age
,address->street_name
,address->city
,address->country
.the
address
fields are flattened into separate attributes ofpersons
persons_bills
fields:
title
,amount
,issue_date
,payed_by
the
bills
array is extracted as a relation, where each bill is a separate record
# Automatic mode
datasource = ForestAdminDatasourceMongoid::Datasource.new(
options: {
flatten_mode: 'auto',
}
)
# Manual mode
datasource = ForestAdminDatasourceMongoid::Datasource.new(
options: {
flatten_mode: 'manual',
flatten_options: {
# name of the Mongoid model
person: {
# paths that should be converted to independent collections
as_models: ['bills'],
# paths that should be moved to the root of the collection
as_fields: ['address'],
# or
# as_fields: ['address.street_name', 'address.city', 'address.country'],
# or
# as_fields: [{ field: 'address', level: 1 }],
},
},
}
)
Data Navigation
When customizing your agent, you need a consistent way to navigate through your data. This section explains how to structure paths based on different field types.
Separator Behavior
Forest Admin uses two different separators depending on the field type:
Nested Fields (
@@@
) – Used when accessing a nested field.Related Data (
:
) – Used when accessing related data.
Example
Consider a User
collection with an address
relation that contains a city
field, which itself has a nested name
field.
User (collection) → address (relation) → city (field) → name (nested field)
To access the name
field inside city
, the path would be:
address:city@@@name
This structure ensures a clear distinction between relationships (:
) and nested properties (@@@
), allowing for precise and predictable data navigation
Last updated
Was this helpful?