Widgets in Forms

This is the official documentation of the @forestadmin/agent Node.js agent.

Field Widgets empower your Actions Forms providing various options to display inputs and ease operators in their daily operations.

Widgets

Widget

Supported types

Minimal version

Description

The address autocomplete widget allows to input an address as a text value, autocompleted by the Google Maps API.

agent.customizeCollection('customer', collection => {
  collection.addAction('Update address', {
    scope: 'Single',
    form: [
      {
        label: 'Address',
        type: 'String',
        widget: 'AddressAutocomplete',
        placeholder: 'Type the address here',
      },
    ],
    execute: async context => {
      /* ... perform work here ... */
    },
  });
});

The above code will produce the following form (when empty):

And once the user starts typing:

Options

The checkbox widget allows to activate or deactivate a boolean value.

agent.customizeCollection('product', collection => {
  collection.addAction('Refresh price', {
    scope: 'Single',
    form: [
      {
        label: 'Send a notification',
        type: 'Boolean',
        widget: 'Checkbox',
        isRequired: true,
        defaultValue: false,
      },
    ],
    execute: async context => {
      /* ... perform work here ... */
    },
  });
});

The above code will produce the following form:

Options

The Checkbox widget has no specific options, but its behavior can be customized using the following already existing options on fields:

By default, the Checkbox widget allows 3 states:

null
true
false

To ensure having only 2 states, you need to:

set the isRequired option to true,
define a value for the defaultValue option.

The checkbox group widget allows to select multiple values from a list of options.

agent.customizeCollection('product', collection => {
  collection.addAction('Leave a review', {
    scope: 'Single',
    form: [
      {
        label: 'Why do you like this product?',
        type: 'StringList',
        widget: 'CheckboxGroup',
        options: [
          { value: 'price', label: 'Good price' },
          { value: 'quality', label: 'Build quality' },
          { value: 'look', label: 'It looks good' },
        ],
      },
    ],
    execute: async context => {
      /* ... perform work here ... */
    },
  });
});

The above code will produce the following form:

Options

The color picker widget allows to select a color.

organization.addAction('Customize UI', {
  scope: 'Single',
  form: [
    {
      label: 'Background color',
      type: 'String',
      widget: 'ColorPicker',
      placeholder: 'Select the color',
      isRequired: true,
      enableOpacity: false,
      quickPalette: [
        '#6002ee',
        '#90ee02',
        '#021aee',
        '#d602ee',
        '#ee0290',
        '#ee6002',
      ],
    },
  ],
  execute: () => {},
});

The above code will produce the following form:

Options

The currency input widget allows to input a currency value.

agent.customizeCollection('product', collection => {
  collection.addAction('Change price', {
    scope: 'Single',
    form: [
      {
        label: 'Price',
        type: 'Number',
        widget: 'CurrencyInput',
        placeholder: 'Enter the new price',
        isRequired: true,
        min: 0,
        max: 1000,
        step: 1,
        currency: 'USD',
        base: 'Unit',
      },
    ],
    execute: async context => {
      /* ... perform work here ... */
    },
  });
});

The above code will produce the following form:

Options

The date picker widget allows to input a date in a form

agent.customizeCollection('order', collection => {
  collection.addAction('Set shipping date', {
    scope: 'Single',
    form: [
      {
        label: 'Shipping date',
        type: 'Date',
        widget: 'DatePicker',
        format: 'DD-MM-YYYY',
        min: new Date(Date.now() - 10 * 24 * 60 * 60 * 1000),
        max: new Date(),
        placeholder: 'please indicate when you shipped the item',
      },
    ],
    execute: async context => {
      /* ... perform work here ... */
    },
  });
});

The above code will produce the following form :

Note: using a Dateonly field type will hide the time section from the date picker

Options

The dates are sent as ISO 8601 formatted strings over the network. In order to use them as Date object in your hooks, you can parse them directly like so

const shippingDate = new Date(context.formValues['Shipping date']))

The dropdown widget allows to select a value from a list of options.

agent.customizeCollection('product', collection => {
  collection.addAction('Leave a review', {
    scope: 'Single',
    form: [
      {
        label: 'Rating',
        type: 'Number',
        widget: 'Dropdown',
        options: [
          { value: 0, label: 'Poor' },
          { value: 1, label: 'Fair' },
          { value: 2, label: 'Good' },
          { value: 3, label: 'Very good' },
          { value: 4, label: 'Excellent' },
        ],
        search: 'disabled',
        placeholder: 'Select a rating',
        isRequired: true,
      },
    ],
    execute: async context => {
      /* ... perform work here ... */
    },
  });
});

The above code will produce the following form:

In this next example, we call a remote api to get a list of products and then perform a custom filter based on given fields of the json response, and return the first 25. This example uses search: 'dynamic' dropdown widget, which provides you with the searchValue in the callback context.

Note: when a search is performed, only the field on which it is performed will have its options recomputed.

agent.customizeCollection('product', collection => {
  collection.addAction('Add more products', {
    execute: async (context, resultBuilder) => {
      // ...
    },
    scope: 'Bulk',
    form: [
      {
        label: 'Select some products',
        type: 'StringList',
        widget: 'Dropdown',
        search: 'dynamic',
        options: async (context, searchValue) => {
          const products = await (
            await fetch('https://api.fake-eshop.com/v2/products')
          ).json();
          return products
            .filter(product => {
              return (
                !searchValue ||
                ['description', 'name', 'features', 'keyword', 'category'].some(
                  key =>
                    product[key]?.toLowerCase().includes(searchValue.toLowerCase()),
                )
              );
            })
            .slice(0, 25)
            .sort((a, b) => a.name.localeCompare(b.name))
            .map(product => ({ label: product.name, value: product.id }));
        },
      },
    ],
  });
});

Options

The file picker allows to upload files

import { File } from '@forestadmin/datasource-toolkit';
import fs from 'fs/promises';
import path from 'path';

import { UserCustomizer } from '../typings';

async function readFile(filePath: string): Promise<File> {
  const data = await fs.readFile(filePath);

  return {
    mimeType: 'image/png',
    buffer: Buffer.from(data),
    name: path.basename(filePath),
  };
}

async function writeFile(file: File, directoryPath: string): Promise<void> {
  await fs.mkdir(directoryPath, { recursive: true });
  await fs.writeFile(
    path.join(directoryPath, path.basename(file.name)),
    file.buffer,
  );
}

export default async (collection: UserCustomizer) => {
  collection.addAction('Update user identification details', {
    scope: 'Single',
    execute: async (context, resultBuilder) => {
      try {
        const username = await context.getRecord(['username']).username;
        const userDirectory = path.join(
          __dirname,
          'data/documents',
          sanitize(username),
        );
        await Promise.all([
          await writeFile(context.formValues['Avatar picture'], userDirectory),
          ...context.formValues.Identification.map(async (file: File) => {
            await writeFile(file, path.join(userDirectory, 'identification'));
          }),
        ]);
        return resultBuilder.success(`Profile updated`);
      } catch (e) {
        return resultBuilder.error(
          `Upload failed with error: ${(e as Error).message}`,
        );
      }
    },
    form: [
      {
        label: 'Avatar picture',
        type: 'File',
        widget: 'FilePicker',
        description: 'Upload a profile picture or leave it to use the default one',
        extensions: ['png', 'jpg'],
        maxSizeMb: 20,
        defaultValue: readFile(
          path.join(__dirname, './data/avatars/default-avatar.png'),
        ),
      },
      {
        label: 'Identification',
        type: 'FileList',
        widget: 'FilePicker',
        description: 'Upload up to 4 documents to identify the user',
        extensions: ['png', 'jpg', 'bmp', 'pdf', 'gif'],
        maxSizeMb: 2,
        maxCount: 4,
        isRequired: true,
      },
    ],
  });
};

The above code will produce the following form:

Options

The JSON editor widget display a rich editor with syntax highlighting for JSON.

agent.customizeCollection('product', collection => {
  collection.addAction('Set properties', {
    scope: 'Single',
    form: [
      {
        label: 'Properties',
        type: 'Json',
        widget: 'JsonEditor',
        defaultValue: { color: 'red' },
      },
    ],
    execute: async context => {
      /* ... perform work here ... */
    },
  });
});

The above code will produce the following form:

Options

This widget does not have any options.

The number input widget allows to input a number value.

agent.customizeCollection('product', collection => {
  collection.addAction('Change price', {
    scope: 'Single',
    form: [
      {
        label: 'Price',
        type: 'Number',
        widget: 'NumberInput',
        placeholder: 'Enter the new price',
        isRequired: true,
        min: 0,
        max: 1000,
        step: 1,
      },
    ],
    execute: async context => {
      /* ... perform work here ... */
    },
  });
});

The above code will produce the following form:

Options

The number input list widget allows to input a list of number values.

agent.customizeCollection('product', collection => {
  collection.addAction('Change step values', {
    scope: 'Single',
    form: [
      {
        label: 'Step values',
        type: 'NumberList',
        widget: 'NumberInputList',
        placeholder: 'Enter the new step value',
        isRequired: true,
        min: 0,
        max: 1000,
        step: 1,
      },
    ],
    execute: async context => {
      /* ... perform work here ... */
    },
  });
});

The above code will produce the following form (once the user entered two step values):

Options

The radio group widget allows to select a value from a list of options.

agent.customizeCollection('product', collection => {
  collection.addAction('Leave a review', {
    scope: 'Single',
    form: [
      {
        label: 'Appreciation',
        type: 'Number',
        widget: 'RadioGroup',
        options: [
          { value: 1, label: 'Good' },
          { value: 0, label: 'Average' },
          { value: -1, label: 'Bad' },
        ],
      },
    ],
    execute: async context => {
      /* ... perform work here ... */
    },
  });
});

The above code will produce the following form:

Options

Using the options function, you can dynamically change the list of options based on the context, which contains information about the selected records and other values in the form. More info about dynamic configuration.

The rich text widget allows to input a formatted text value.

agent.customizeCollection('product', collection => {
  collection.addAction('Leave a review', {
    scope: 'Single',
    form: [
      {
        label: 'Comment',
        type: 'String',
        widget: 'RichText',
        isRequired: true,
        placeholder: 'Type your comment here',
      },
    ],
    execute: async context => {
      /* ... perform work here ... */
    },
  });
});

The above code will produce the following form:

Options

The text area widget allows to input a multiline string value.

agent.customizeCollection('product', collection => {
  collection.addAction('Leave a review', {
    scope: 'Single',
    form: [
      {
        label: 'Comment',
        type: 'String',
        widget: 'TextArea',
        isRequired: true,
        placeholder: 'Type your comment here...',
        rows: 10,
      },
    ],
    execute: async context => {
      /* ... perform work here ... */
    },
  });
});

The above code will produce the following form:

Options

The text input widget allows to input a string value.

agent.customizeCollection('customer', collection => {
  collection.addAction('Send notification', {
    scope: 'Single',
    form: [
      {
        label: 'Message',
        type: 'String',
        widget: 'TextInput',
        placeholder: 'Enter your message here',
      },
    ],
    execute: async context => {
      /* ... perform work here ... */
    },
  });
});

The above code will produce the following form:

Options

The text input list widget allows to input a list of string values.

agent.customizeCollection('product', collection => {
  collection.addAction('Add tags', {
    scope: 'Single',
    form: [
      {
        label: 'Tag',
        type: 'StringList',
        widget: 'TextInputList',
        isRequired: true,
        placeholder: 'Enter a tag',
        allowDuplicates: false,
        allowEmptyValues: false,
        enableReorder: false,
      },
    ],
    execute: async context => {
      /* ... perform work here ... */
    },
  });
});

The above code will produce the following form (once the user entered two tags):

Options

The time picker widget allows to select a time

agent.customizeCollection('store', collection => {
  collection.addAction('set opening and closing time', {
    scope: 'Single',
    form: [
      {
        label: 'Opening time',
        type: 'Time',
        widget: 'TimePicker',
      },
      {
        label: 'Closing time',
        type: 'Time',
        widget: 'TimePicker',
      },
    ],
    execute: async context => {
      /* ... perform work here ... */
    },
  });
});

The above code will produce the following form :

time picker does not support additional options

The user dropdown widget allows to input a user or list of users from the project

agent.customizeCollection('Ticket', collection => {
  collection.addAction('Assign to the record', {
    scope: 'Single',
    form: [
      {
        type: 'String',
        label: 'Manager',
        widget: 'UserDropdown',
        placeholder: 'Select the manager in charge',
      },
      {
        type: 'StringList',
        label: 'Operators',
        widget: 'UserDropdown',
        placeholder: 'Select operators for this record',
      },
    ],
    execute: async context => {
      /* ... perform work here ... */
    },
  });
});

The above code will produce the following form (once the user has selected some users)

Widgets

Address autocomplete widget

Options

Checkbox widget

Options

Checkbox group widget

Options

Color picker widget

Options

Currency input widget

Options

DatePicker widget

Options

Options

File picker widget

Options

JSON editor widget

Options

Number input widget

Options

Number input list widget

Options

Radio group widget

Options

Rich text widget

Options

Text area widget

Options

Text input widget

Options

Text input list widget

Options

Time picker widget

Options

Widgets

Address autocomplete widget

Options

Checkbox widget

Options

Checkbox group widget

Options

Color picker widget

Options

Currency input widget

Options

DatePicker widget

Options

Dropdown widget

Options

File picker widget

Options

JSON editor widget

Options

Number input widget

Options

Number input list widget

Options

Radio group widget

Options

Rich text widget

Options

Text area widget

Options

Text input widget

Options

Text input list widget

Options

Time picker widget

User dropdown widget

Options