Use a Smart Action Form

We've just introduced Smart actions: they're great because you can execute virtually any business logic. However, there is one big part missing: how do you let your users provide more information or have interaction when they trigger the Smart action? In short, you need to open a Smart Action Form.

Opening a Smart Action Form

Very often, you will need to ask user inputs before triggering the logic behind a Smart Action. For example, you might want to specify a reason if you want to block a user account. Or set the amount to charge a user’s credit card.

SQL
Mongodb
Rails
SQL

On our Live Demo example, we’ve defined 4 input fields on the Smart Action Upload Legal Docs on the collection companies.

/forest/companies.js
const { collection } = require('forest-express-sequelize');
collection('companies', {
actions: [{
name: 'Upload Legal Docs',
type: 'single',
fields: [{
field: 'Certificate of Incorporation',
description: 'The legal document relating to the formation of a company or corporation.',
type: 'File',
isRequired: true
}, {
field: 'Proof of address',
description: '(Electricity, Gas, Water, Internet, Landline & Mobile Phone Invoice / Payment Schedule) no older than 3 months of the legal representative of your company',
type: 'File',
isRequired: true
}, {
field: 'Company bank statement',
description: 'PDF including company name as well as IBAN',
type: 'File',
isRequired: true
}, {
field: 'Valid proof of ID',
description: 'ID card or passport if the document has been issued in the EU, EFTA, or EEA / ID card or passport + resident permit or driving licence if the document has been issued outside the EU, EFTA, or EEA of the legal representative of your company',
type: 'File',
isRequired: true
}]
}]
});
/routes/companies.js
...
router.post('/actions/upload-legal-docs', permissionMiddlewareCreator.smartAction(),
(req, res) => {
// Get the current company id
let companyId = req.body.data.attributes.ids[0];
// Get the values of the input fields entered by the admin user.
let attrs = req.body.data.attributes.values;
let certificate_of_incorporation = attrs['Certificate of Incorporation'];
let proof_of_address = attrs['Proof of address'];
let company_bank_statement = attrs['Company bank statement'];
let passport_id = attrs['Valid proof of id'];
// The business logic of the Smart Action. We use the function
// UploadLegalDoc to upload them to our S3 repository. You can see the full
// implementation on our Forest Live Demo repository on Github.
return P.all([
uploadLegalDoc(companyId, certificate_of_incorporation, 'certificate_of_incorporation_id'),
uploadLegalDoc(companyId, proof_of_address, 'proof_of_address_id'),
uploadLegalDoc(companyId, company_bank_statement,'bank_statement_id'),
uploadLegalDoc(companyId, passport_id, 'passport_id'),
])
.then(() => {
// Once the upload is finished, send a success message to the admin user in the UI.
res.send({ success: 'Legal documents are successfully uploaded.' });
});
});
...
module.exports = router;
Mongodb

On our Live Demo example, we’ve defined 4 input fields on the Smart Action Upload Legal Docs on the collection companies.

/forest/companies.js
const { collection } = require('forest-express-mongoose');
collection('companies', {
actions: [{
name: 'Upload Legal Docs',
type: 'single',
fields: [{
field: 'Certificate of Incorporation',
description: 'The legal document relating to the formation of a company or corporation.',
type: 'File',
isRequired: true
}, {
field: 'Proof of address',
description: '(Electricity, Gas, Water, Internet, Landline & Mobile Phone Invoice / Payment Schedule) no older than 3 months of the legal representative of your company',
type: 'File',
isRequired: true
}, {
field: 'Company bank statement',
description: 'PDF including company name as well as IBAN',
type: 'File',
isRequired: true
}, {
field: 'Valid proof of ID',
description: 'ID card or passport if the document has been issued in the EU, EFTA, or EEA / ID card or passport + resident permit or driving licence if the document has been issued outside the EU, EFTA, or EEA of the legal representative of your company',
type: 'File',
isRequired: true
}],
});
/routes/companies.js
...
router.post('/actions/upload-legal-docs',
(req, res) => {
// Get the current company id
let companyId = req.body.data.attributes.ids[0];
// Get the values of the input fields entered by the admin user.
let attrs = req.body.data.attributes.values;
let certificate_of_incorporation = attrs['Certificate of Incorporation'];
let proof_of_address = attrs['Proof of address'];
let company_bank_statement = attrs['Company bank statement'];
let passport_id = attrs['Valid proof of id'];
// The business logic of the Smart Action. We use the function
// UploadLegalDoc to upload them to our S3 repository. You can see the full
// implementation on our Forest Live Demo repository on Github.
return P.all([
uploadLegalDoc(companyId, certificate_of_incorporation, 'certificate_of_incorporation_id'),
uploadLegalDoc(companyId, proof_of_address, 'proof_of_address_id'),
uploadLegalDoc(companyId, company_bank_statement,'bank_statement_id'),
uploadLegalDoc(companyId, passport_id, 'passport_id'),
])
.then(() => {
// Once the upload is finished, send a success message to the admin user in the UI.
res.send({ success: 'Legal documents are successfully uploaded.' });
});
});
...
module.exports = router;

Rails

On our Live Demo example, we’ve defined 4 input fields on the Smart Action Upload Legal Docs on the collection Company.

/lib/forest_liana/collections/company.rb
class Forest::Company
include ForestLiana::Collection
collection :Company
action 'Upload Legal Docs', type: 'single', fields: [{
field: 'Certificate of Incorporation',
description: 'The legal document relating to the formation of a company or corporation.',
type: 'File',
is_required: true
}, {
field: 'Proof of address',
description: '(Electricity, Gas, Water, Internet, Landline & Mobile Phone Invoice / Payment Schedule) no older than 3 months of the legal representative of your company',
type: 'File',
is_required: true
}, {
field: 'Company bank statement',
description: 'PDF including company name as well as IBAN',
type: 'File',
is_required: true
}, {
field: 'Valid proof of ID',
description: 'ID card or passport if the document has been issued in the EU, EFTA, or EEA / ID card or passport + resident permit or driving licence if the document has been issued outside the EU, EFTA, or EEA of the legal representative of your company',
type: 'File',
is_required: true
}]
end
/config/routes.rb
Rails.application.routes.draw do
# MUST be declared before the mount ForestLiana::Engine.
namespace :forest do
post '/actions/upload-legal-docs' => 'companies#upload_legal_docs'
end
mount ForestLiana::Engine => '/forest'
end
/app/controllers/forest/companies_controller.rb
class Forest::CompaniesController < ForestLiana::SmartActionsController
def upload_legal_doc(company_id, doc, field)
id = SecureRandom.uuid
Forest::S3Helper.new.upload(doc, "livedemo/legal/#{id}")
company = Company.find(company_id)
company[field] = id
company.save
Document.create({
file_id: company[field],
is_verified: true
})
end
def upload_legal_docs
# Get the current company id
company_id = ForestLiana::ResourcesGetter.get_ids_from_request(params).first
# Get the values of the input fields entered by the admin user.
attrs = params.dig('data', 'attributes', 'values')
certificate_of_incorporation = attrs['Certificate of Incorporation'];
proof_of_address = attrs['Proof of address'];
company_bank_statement = attrs['Company bank statement'];
passport_id = attrs['Valid proof of ID'];
# The business logic of the Smart Action. We use the function
# upload_legal_doc to upload them to our S3 repository. You can see the
# full implementation on our Forest Live Demo repository on Github.
upload_legal_doc(company_id, certificate_of_incorporation, 'certificate_of_incorporation_id')
upload_legal_doc(company_id, proof_of_address, 'proof_of_address_id')
upload_legal_doc(company_id, company_bank_statement, 'bank_statement_id')
upload_legal_doc(company_id, passport_id, 'passport_id')
# Once the upload is finished, send a success message to the admin user in the UI.
render json: { success: 'Legal documents are successfully uploaded.' }
end
end

Handling input values

Here is the list of available options to customize your input form.

Name

Type

Description

field

string

Label of the input field.

type

string or array

Type of your field.

  • string: Boolean, Date, Dateonly, Enum, File, Number, String

  • array: ['Enum'], ['Number'], ['String']

reference

string

(optional) Specify that the input is a reference to another collection. You must specify the primary key (ex: category.id).

enums

array of strings

(optional) Required only for the Enum type. This is where you list all the possible values for your input field.

description

string

(optional) Add a description for your admin users to help them fill correctly your form

isRequired

boolean

(optional) If true, your input field will be set as required in the browser. Default is false.

hook

string

(optional) Specify the change hook. If specified the corresponding hook is called when the input change

Making a form dynamic with hooks

Business logic often requires your forms to adapt to its context. Forest Admin makes this possible through a powerful way to extend your form's logic.

To make Smart Action Forms dynamic, we've introduced the concept of hooks: hooks allow you to run some logic upon a specific event.

The load hook is called when the form loads, allowing you to change its properties upon load.

The change hook is called whenever you interact with a field of the form.

Prefill a form with default values

Forest Admin allows you to set default values of your form. In this example, we will prefill the form with data coming from the record itself (1), with just a few extra lines of code.

SQL
Mongodb
Rails
SQL
/forest/customers.js
const { collection } = require('forest-express-sequelize');
const { customers } = require('../models');
collection('Customers', {
actions: [{
name: 'Charge credit card',
type: 'single',
fields: [{
field: 'amount',
isRequired: true,
description: 'The amount (USD) to charge the credit card. Example: 42.50',
type: 'Number'
}, {
field: 'description',
isRequired: true,
description: 'Explain the reason why you want to charge manually the customer here',
type: 'String'
}, {
// we added a field to show the full potential of prefilled values in this example
field: 'stripe_id',
isRequired: true,
type: 'String'
}],
hooks: {
load: async ({ fields, request }) => {
const amount = fields.find(field => field.field === 'amount');
const stripeId = fields.find(field => field.field === 'stripe_id');
amount.value = 4520;
const id = request.body.data.attributes.ids[0];
const customer = await customers.findByPk(id);
stripeId.value = customer.stripe_id;
return fields;
},
},
}],
...
});
Mongodb
/forest/customers.js
const { collection } = require('forest-express-mongoose');
const { customers } = require('../models');
collection('Customers', {
actions: [{
name: 'Charge credit card',
type: 'single',
fields: [{
field: 'amount',
isRequired: true,
description: 'The amount (USD) to charge the credit card. Example: 42.50',
type: 'Number'
}, {
field: 'description',
isRequired: true,
description: 'Explain the reason why you want to charge manually the customer here',
type: 'String'
}, {
// we added a field to show the full potential of prefilled values in this example
field: 'stripe_id',
isRequired: true,
type: 'String'
}],
hooks: {
load: async ({ fields, request }) => {
const amount = fields.find(field => field.field === 'amount');
const stripeId = fields.find(field => field.field === 'stripe_id');
amount.value = 4520;
const id = request.body.data.attributes.ids[0];
const customer = await customers.findByPk(id);
stripeId.value = customer.stripe_id;
return fields;
},
},
}],
...
});
Rails
lib/forest_liana/customers.rb
class Forest::Customers
include ForestLiana::Collection
collection :Customers
action 'Charge credit card',
type: 'single',
fields: [{
field: 'amount',
isRequired: true,
description: 'The amount (USD) to charge the credit card. Example: 42.50',
type: 'Number'
}, {
field: 'description',
isRequired: true,
description: 'Explain the reason why you want to charge manually the customer here',
type: 'String'
}, {
# we added a field to show the full potential of prefilled values in this example
field: 'stripe_id',
isRequired: true,
type: 'String'
}],
:hook => {
:load => -> (context) {
amount = context[:fields].find{|field| field[:field] == 'amount'}
stripeId = context[:fields].find{|field| field[:field] == 'stripe_id'}
amount[:value] = 4520;
id = context[:params][:data][:attributes][:ids][0];
customer = Customers.find(id);
stripeId[:value] = customer['stripe_id'];
return context[:fields];
}
}
...
end

Making a field read-only

To make a field read only, you can use the isReadOnly property:

Name

Type

Description

isReadOnly

boolean

(optional) If true, the Smart action field won’t be editable in the form. Default is false

Combined with the load hook feature, this can be used to make a field read-only dynamically:

const { customers } = require('../models');
collection('customers', {
actions: [{
name: 'Some action',
type: 'single',
fields: [
{
field: 'country',
type: 'String',
isReadOnly: true
},
{
field: 'city',
type: 'String'
},
],
hooks: {
load: async ({ fields, request }) => {
const country = fields.find(field => field.field === 'country');
country.value = 'France';
const id = request.body.data.attributes.ids[0];
const customer = await customers.findById(id);
// If customer country is not France, empty field and make it editable
if (customer.country !== 'France') {
country.value = '';
country.isReadOnly = false;
}
return fields;
},
},
}],
fields: [],
segments: [],
});

Change your form's data based on previous field values

This feature is only available from version 6.6.0 (forest-express-sequelize and forest-express-mongoose) / version 5.3.3 (forest-rails) and for single Smart actions.

Here's a typical example: Selecting a City within a list of cities from the Country you just selected. Then selecting a Zipcode within a list of zipcodes located in the City you just selected.

SQL
Mongodb
Rails
SQL
forest/customers.js
const { getEnumsFromDatabaseForThisRecord } = require('./my-own-helper');
const { getZipCodeFromCity } = require('...');
const { collection } = require('forest-express-sequelize');
const { customers } = require('../models');
collection('customers', {
actions: [{
name: 'Send invoice',
type: 'single',
fields: [
{
field: 'country',
type: 'Enum',
enums: []
},
{
field: 'city',
type: 'String',
hook: 'onCityChange'
},
{
field: 'zip code',
type: 'String',
hook: 'onZipCodeChange'
},
],
hooks: {
load: async ({ fields, request }) => {
const country = fields.find(field => field.field === 'country');
const id = request.body.data.attributes.ids[0];
const customer = await customers.findByPk(id);
country.enums = getEnumsFromDatabaseForThisRecord(customer);
return fields;
},
change: {
onCityChange: async ({ fields, request, changedField }) => {
const zipCode = fields.find(field => field.field === 'zip code');
const id = request.body.data.attributes.ids[0];
const customer = await customers.findByPk(id);
zipCode.value = getZipCodeFromCity(
customer,
changedField.value
);
return fields;
},
onZipCodeChange: async ({ fields, request, changedField }) => {
const city = fields.find(field => field.field === 'city');
const id = request.body.data.attributes.ids[0];
const customer = await customers.findByPk(id);
city.value = getCityFromZipCode(
customer,
changedField.value
);
return fields;
},
},
},
}],
fields: [],
segments: [],
});
Mongodb
forest/customers.js
const { getEnumsFromDatabaseForThisRecord } = require('./my-own-helper');
const { getZipCodeFromCity } = require('...');
const { collection } = require('forest-express-mongoose');
const { customers } = require('../models');
collection('customers', {
actions: [{
name: 'Send invoice',
type: 'single',
fields: [
{
field: 'country',
type: 'Enum',
enums: []
},
{
field: 'city',
type: 'String',
hook: 'onCityChange'
},
{
field: 'zip code',
type: 'String',
hook: 'onZipCodeChange'
},
],
hooks: {
load: async ({ fields, request }) => {
const country = fields.find(field => field.field === 'country');
const id = request.body.data.attributes.ids[0];
const customer = await customers.findById(id);
country.enums = getEnumsFromDatabaseForThisRecord(customer);
return fields;
},
change: {
onCityChange: async ({ fields, request, changedField }) => {
const zipCode = fields.find(field => field.field === 'zip code');
const id = request.body.data.attributes.ids[0];
const customer = await customers.findById(id);
zipCode.value = getZipCodeFromCity(
customer,
changedField.value
);
return fields;
},
onZipCodeChange: async ({ fields, request, changedField }) => {
const city = fields.find(field => field.field === 'city');
const id = request.body.data.attributes.ids[0];
const customer = await customers.findById(id);
city.value = getCityFromZipCode(
customer,
changedField.value
);
return fields;
},
},
},
}],
fields: [],
segments: [],
});
Rails
/lib/forest_liana/collections/company.rb
actions 'Send invoice',
type: 'single',
fields: [
{
field: 'country',
type: 'Enum',
enums: []
},
{
field: 'city',
type: 'String',
hook: 'oncityChange'
},
{
field: 'zip code',
type: 'String',
hook: 'onZipCodeChange'
},
],
hooks: {
:load => -> (context){
country = context[:fields].find{|field| field[:field] == 'country'}
id = context[:params][:data][:attributes][:ids][0];
customer = Customers.find(id);
country[:enums] = getEnumsFromDatabaseForThisRecord(customer)
return context[:fields]
},
:change => {
'oncityChange'=> -> (context){
zipCode = context[:fields].find{|field| field[:field] == 'zip code'}
id = context[:params][:data][:attributes][:ids][0];
customer = Customers.find(id);
zipCode[:value] = getZipCodeFromCity(
context[:record],
context[:context][:changed_field][:value]
)
return context[:fields]
},
'onZipCodeChange'=> -> (context) {
city = context[:fields].find{|field| field[:field] == 'city'}
id = context[:params][:data][:attributes][:ids][0];
customer = Customers.find(id);
city[:value] = getCityFromZipCode(
context[:record],
context[:context][:changed_field][:value]
)
return context[:fields]
},
},
}

How does it work?

The hooks property receives a context object containing:

  • the fields array in its current state (containing also the current values)

  • the request object containing all the informations related to the records selection. Explained here.

  • the changedField is the current field who trigger the hook (only for change hook)

fields must be returned. Note that fields is an array containing existing fields with properties described in this section.

To dynamically change a property within a load or change hook, just set it! For instance, setting a new description for the field city:

SQL
Mongodb
Rails
SQL
const city = fields.find(field => field.field === 'city');
city.description = "Please enter the name of your favorite city";
Mongodb
const city = fields.find(field => field.field === 'city');
city.description = "Please enter the name of your favorite city";
Rails
city = context[:fields].find{|field| field[:field] == 'city'}
city[:description] = "Please enter the name of your favorite city"

As a result, the correct way to set a default value is using the value property within a load hook, as follows:

SQL
Mongodb
Rails
SQL
hooks: {
load: ({ fields, request }) => {
const country = fields.find(field => field.field === 'country');
country.value = "France";
return fields;
},
}
Mongodb
hooks: {
load: ({ fields, request }) => {
const country = fields.find(field => field.field === 'country');
country.value = "France";
return fields;
},
}
Rails
hooks: {
:load => -> (context){
country = context[:fields].find{|field| field[:field] == 'country'}
country[:value] = "France"
return context[:fields]
},
}

Add/remove fields dynamically

This feature is only available from version 8.0.0 (forest-express-sequelize and forest-express-mongoose) / version 7.0.0 (forest-rails).

You can add a field dynamically inside the fields array, like so:

SQL
Mongodb
Rails
SQL
[...]
hooks: {
change: {
onFieldChanged: ({ fields, request, changedField }) => {
[...]
fields.push({
field: 'another field',
type: 'Boolean',
});
return fields;
}
}
}
[...]
Mongodb
[...]
hooks: {
change: {
onFieldChanged: ({ fields, request, changedField }) => {
[...]
fields.push({
field: 'another field',
type: 'Boolean',
});
return fields;
}
}
}
[...]
Rails
:hooks => {
:change => {
'onFieldChanged' => -> (context) {
[...]
context[:fields].push({
field: 'another field',
type: 'Boolean',
});
return context[:fields];
}
}
}

We added the changedField attribute so that you can easily know what changed.

Note that you may add a change hook on a dynamically-added field. Simply use the following syntax:

SQL
Mongodb
Rails
SQL
[...]
hooks: {
change: {
onFieldChanged: ({ fields, request, changedField }) => {
[...]
fields.push({
field: 'another field',
type: 'Boolean',
hook: 'onAnotherFieldChanged',
});
return fields;
},
onAnotherFieldChanged: ({fields, request, changedField }) => {
// Do what you want
return fields;
}
}
}
[...]
Mongodb
[...]
hooks: {
change: {
onFieldChanged: ({ fields, request, changedField }) => {
[...]
fields.push({
field: 'another field',
type: 'Boolean',
hook: 'onAnotherFieldChanged',
});
return fields;
},
onAnotherFieldChanged: ({fields, request, changedField }) => {
// Do what you want
return fields;
}
}
}
[...]
Rails
:hooks => {
:change => {
'onFieldChanged' => -> (context) {
[...]
context[:fields].push({
field: 'another field',
type: 'Boolean',
hook: 'onAnotherFiledChanged',
});
return context[:fields];
},
'onAnotherFiledChanged' => -> (context) {
# Do what you want
return context[:fields];
}
}
}

Get selected records with bulk action

When using hooks with a bulk Smart action, you'll probably need te get the values or ids of the selected records. See below how this can be achieved.

SQL
Mongodb
Rails
SQL
/forest/customers.js
const { collection, RecordsGetter } = require('forest-express-sequelize');
const { customers } = require('../models');
const customersHaveSameCountry = require('../services/customers-have-same-country');
collection('customers', {
actions: [{
name: 'Some action',
type: 'bulk',
fields: [
{
field: 'country',
type: 'String',
isReadOnly: true
},
{
field: 'city',
type: 'String'
},
],
hooks: {
load: async ({ fields, request }) => {
const country = fields.find(field => field.field === 'country');
const ids = await new RecordsGetter(forest, request.user, request.query)
.getIdsFromRequest(request);
const customers = await customers.findAll({ where: { id }});
country.value = '';
country.isReadOnly = false;
// If customers have the same country, set field to this country and make it not editable
if (customersHaveSameCountry(customers)) {
country.value = customers.country;
country.isReadOnly = true;
}
return fields;
},
},
}],
fields: [],
segments: [],
});
Mongodb
/forest/customers.js
const { collection, RecordsGetter } = require('forest-express-mongoose');
const { customers } = require('../models');
const customersHaveSameCountry = require('../services/customers-have-same-country');
collection('customers', {
actions: [{
name: 'Some action',
type: 'bulk',
fields: [
{
field: 'country',
type: 'String',
isReadOnly: true
},
{
field: 'city',
type: 'String'
},
],
hooks: {
load: async ({ fields, request }) => {
const country = fields.find(field => field.field === 'country');
const ids = await new RecordsGetter(forest, request.user, request.query)
.getIdsFromRequest(request);
const customers = await customers.findAll({ _id: { $in: ids } });
country.value = '';
country.isReadOnly = false;
// If customers have the same country, set field to this country and make it not editable
if (customersHaveSameCountry(customers)) {
country.value = customers.country;
country.isReadOnly = true;
}
return fields;
},
},
}],
fields: [],
segments: [],
});
Rails
class Forest::Customers
include ForestLiana::Collection
collection :Customers
action 'Some action',
type: 'bulk',
fields: [
{
field: 'country',
type: 'String',
is_read_only: true
},
{
field: 'city',
type: 'String'
},
],
:hooks => {
:load => -> (context) {
country = context[:fields].find{|field| field[:field] == 'country'}
ids = ForestLiana::ResourcesGetter.get_ids_from_request(context[:params]);
customers = Customers.find(id);
country[:value] = '';
country[:is_read_only] = false;
# If customers have the same country, set field to this country and make it not editable
if customers_have_same_country(customers)
country[:value] = customers.country;
country[:is_read_only] = true;
end
return context[:fields];
},
},
end