This is the official documentation of the @forestadmin/agent Node.js agent.
Business logic often requires your forms to adapt to their context. Forest Admin makes this possible through a powerful way to extend your form's logic.
To make an action form dynamic, simply use functions instead of a static value on the compatible properties.
But you can also define entirely your form to be dynamic.
Note that:
Both synchronous and asynchronous functions are supported
And finally, those two extra properties are available and can only be used as functions:
Property
Description
if
Only display the field if the function returns true.
value
Set the current value of the field.
Examples
Example 1: Dynamic fields based on form values
In this example we make a field required only if the user enters a value greater than 1000 in another field.
agent.customizeCollection('customer', collection => {
collection.addAction('Charge credit card', {
scope: 'Single',
form: [
{
label: 'amount',
type: 'Number',
description: 'The amount (USD) to charge the credit card. Example: 42.50',
isRequired: true,
},
{
label: 'description',
type: 'String',
description: 'Explain why you want to charge the customer manually',
/**
* The field will only be required if the function returns true.
*/
isRequired: context => context.formValues['amount'] > 1000,
},
],
execute: async (context, resultBuilder) => {
// ...
},
});
});
Example 2: Conditional field display based on record data
Unlike the previous example, this one will only display the field if the record has a specific value.
It is still a dynamic field, but this time, the condition does not depend on the form values but on the record data.
agent.customizeCollection('product', collection => {
collection.addAction('Leave a review', {
scope: 'Single',
form: [
{ label: 'Rating', type: 'Enum', enumValues: ['1', '2', '3', '4', '5'] },
// Only display this field the data does not have comment already
{
label: 'Put a comment',
type: 'String',
if: async context => {
const existingComment = await context.getRecord(['comment']).comment;
return !existingComment;
},
},
],
execute: async context => {
/* ... perform work here ... */
},
});
});
Example 3: Conditional enum values based on both record data and form values
You can mix and match the previous examples to create complex forms.
In this example, the form will display a different set of enum values depending on both the record data and the value of the form field.
The first field displays different denominations that can be used to address the customer, depending on the full name and gender of the customer.
The second field displays different levels of loudness depending on if the customer is Morgan Freeman, as to ensure that we never speak Very Loudly at him, for the sake of politeness.
agent.customizeCollection('customer', collection => {
collection.addAction('Tell me a greeting', {
scope: 'Single',
form: [
{
label: 'How should we refer to you?',
type: 'Enum',
enumValues: async context => {
// Enum values are computed based on the record data
// Use an async function to fetch the record data
const user = await context.getRecord(['firstName', 'lastName', 'gender']);
const base = [user.firstName, `${user.firstName} ${user.lastName}`];
if (gender === 'Female') {
return [...base, `Mrs. ${user.lastName}`, `Miss ${user.lastName}`];
} else {
return [...base, `Mr. ${user.lastName}`];
}
},
},
{
label: 'How loud should we say it?',
type: 'Enum',
enumValues: context => {
// Enum values are computed based on another form field value
// (no need to use an async function, but doing so would not be a problem)
const denomination = context.formValues['How should we refer to you?'];
return denomination === 'Morgan Freeman'
? ['Whispering', 'Softly', 'Loudly']
: ['Softly', 'Loudly', 'Very Loudly'];
},
},
],
execute: async (context, resultBuilder) => {
const denomination = context.formValues['How should we refer to you?'];
const loudness = context.formValues['How loud should we say it?'];
let text = `Hello ${denomination}`;
if (loudness === 'Whispering') {
text = text.toLowerCase();
} else if (loudness === 'Loudly') {
text = text.toUpperCase();
} else if (loudness === 'Very Loudly') {
text = text.toUpperCase() + '!!!';
}
return resultBuilder.success(text);
},
});
});
Example 4: Using hasFieldChanged to reset value
In this example we reset a field based on change on another one.
In this example we define the fields to be all the fields of the current collection. Doing that will allow the form to be always up to date and to be able to enforce the edition of a record through this action for example.
