Scope and context
This is the official documentation of the @forestadmin/agent
Node.js agent.
Actions can have 3 different scopes: Single
, Bulk
, and Global
.
The scope of an action defines how it can be triggered and which records it will target.
- | Single | Bulk | Global |
---|---|---|---|
Targeted records | One at a time | All selected and matching the current segment / search | Your choice among all matching the current segment / search |
Can be triggered from the List View | When a single record is selected | When one or more records are selected | ✅ |
Can be triggered from the Details View or Summary View | ✅ | ✅ | 🚫 |
The context
object
context
objectThe context
object is central to writing Actions controllers in Forest Admin.
It is the bridge between all the data that your agent has access to and the action's execution. It is passed to the execute
function as the first argument and provides access to the following properties:
getRecord(fieldNames)
(orgetRecords(fieldNames)
forBulk
andGlobal
Actions)getRecordId()
(orgetRecordIds()
forBulk
andGlobal
Actions)collection
the collection on which the action is declared, which can be queried using the Forest Admin Query Interface.dataSource
the composite data source who contains all your collections, which can be queried using the Forest Admin Query Interfacefilter
a filter that can be used to query the collection, and which is based on action scope and the list of selected records.caller
an object containing information about the user who is performing the action (including email, username, timezone, team, role …)hasFieldChanged(fieldName)
the name of the field who has changed in the UI. See an example of usage
changedField
was deprecated in favor of hasFieldChanged(fieldName)
starting from @forestadmin/agent@1.28.3
see more information in this issue report ↗.
Example 1: Getting data from the selected records
We can simply use the getRecord(fieldNames)
method to get any column from the selected record or a relation.
Example 2: Updating a field of the selected record
For simple queries, use context.collection
and context.filter
to query the collection.
Those are instances of objects from the Forest Admin Query Interface.
Example 3: Coding any business logic
Forest Admin does not impose any restriction on the handler: you are free to write the execute
handler to fit your use case.
You are free to call external APIs, query your database, or perform any work in action handlers.
Last updated