Other documentations
DemoCommunityGitHub

Use a Smart Action Form

Please be sure of your agent type and version and pick the right documentation accordingly.

This is the documentation of the forest-express-sequelize and forest-express-mongoose Node.js agents that will soon reach end-of-support.

forest-express-sequelize v9 and forest-express-mongoose v9 are replaced by @forestadmin/agent v1.

Please check your agent type and version and read on or switch to the right documentation.

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.

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 license 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
const { PermissionMiddlewareCreator } = require('forest-express-sequelize');
const permissionMiddlewareCreator = new PermissionMiddlewareCreator('companies');

...

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;

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

widget

string

(optional) The following widgets are available to your smart action fields (text area, date, boolean, file, dateonly)

The widget property is only partially supported. If you want to use a custom widget via a Smart Action Hook, you'll need to use the syntax mentioned in the next section.

Use components to better layout your form

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

you must define your layout in a load hook at minima, and repeat it in each change hook.

This feature is useful when dealing with long/complex forms, with many fields. It will let you organize them and add useful information to guide the end user. The layout must contain the fields as they should be rendered on the form.

List of supported layout components

// Page
{
  type: 'Layout',
  component: 'Page',
  elements: [] // An array of fields or other layout elements (except other pages)
},

// Row
{
  type: 'Layout',
  component: 'Row',
  fields: [] // An array of one or two fields
}

// Separator
{
  type: 'Layout',
  component: 'Separator',
}

// Html bloc
{
  type: 'Layout',
  component: 'HtmlBlock',
  content: '...' // A text content, which supports html tags
}

Example

Here's an example of an action form with many fields, that we want to improve with some layout components, to make it easier for the end user to fill in.

forest/customers.js
const applyLayout = (fields) => {
  const fieldByName = (name) => fields.find((field) => field.field === name);
  return [
    {
      type: 'Layout',
      component: 'Page',
      elements: [
        {
          type: 'Layout',
          component: 'HtmlBlock',
          content: '<h3>Please fill in the customer details <b>first</b>, following this <a href="https://how-to-invoice.doc.example">guide</a></h3>'
        },
        {
          type: 'Layout',
          component: 'Row',
          fields: [fieldByName('firstname'), fieldByName('lastname')]
        },
        { type: 'Layout', component: 'Separator' },
        fieldByName('username'),
        fieldByName('email'),
      ]
    },
    {
      type: 'Layout',
      component: 'Page',
      elements: [
        {
          type: 'Layout',
          component: 'HtmlBlock',
          content: 'You may now enter his address details'
        },
        {
          type: 'Layout',
          component: 'Row',
          fields: [fieldByName('city'), fieldByName('zip code')]
        },
        fieldByName('country'),
      ]
    }
  ]
}

collection('customers', {
  actions: [
    {
      name: 'Send invoice',
      type: 'single',
      fields: [
        {
          field: 'firstname',
          type: 'String',
          isRequired: true,
        },
        {
          field: 'lastname',
          type: 'String',
          isRequired: true,
        },
        {
          field: 'username',
          type: 'String',
        },
        {
          field: 'email',
          type: 'String',
          isRequired: true,
        },
        {
          field: 'country',
          type: 'Enum',
          enums: [],
        },
        {
          field: 'city',
          type: 'String',
          hook: 'onCityChange',
        },
        {
          field: 'zip code',
          type: 'String',
          hook: 'onZipCodeChange',
        },
      ],
      hooks: {
        load: async ({ fields }) => {
          return applyLayout(fields);
        },
        change: {
          onCityChange: async ({ fields }) => {
            return applyLayout(fields);
          },
          onZipCodeChange: async ({ fields }) => {
            return applyLayout(fields);
          },
        },
      },
    },
  ],
  fields: [],
  segments: [],
});

The resulting action form will be:

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.

/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;
      },
    },
  }],
  ...
});