Actions

An action is a custom code you can execute on one or multiple of your collections / models items.

By default, the only available action is the delete one, that is available everywhere.

For example, you want a custom action called "User KYC Validation" that will set a property in the user model, you can implement it like the code bellow.

{
  label: 'User KYC Validation',
  code: 'kyc_validation',
  target: 'item',
  filter: user => {
    return user.is_kyc === false;
  },
  handler: async (props, success, error) => {
    const user = await UserModel.findById(props.ids[0]);

    if (!user) {
      error({ message: `Ce freelance n'a pas déposé de CV` });
      return;
    }

    // Set the user is_kyc property to true
    user.is_kyc = true;
    await user.save();

    success({});
  }
},

As you can see there is some property that need to explained.

label property

This is the label that will be visible from the back-office UI.

code property

This should be a unique string representing the action.

⚠ Please avoid changing it once configured because it will be used as the action identifier in the Activity page.

target property

When creating a custom action, you can configure if the action will be available in the list page, the item page or both, with the target property.

There is two types of targets when talking about actions: item and bulk.

The item target is basically available from the item page only while the bulk type is available from the list page.

The target property can be an array combining both item and bulk as bellow.

target: ['item', 'bulk']

Note that by default, an action is available everywhere.

filter function

The filter function allow you to set a custom filtering function to make the action available & visible to specific model items.

handler function

The handler function is the one that will be executed when clicking on the proper action.

As you can see the handler function take the following parameters: ids, data, success, error.

---

ids: Array

The ID list of the selected items

---

data: Object

The optional Form data if you are configured a custom Form for the action

---

success: Function

The function that have to be executed if your custom action has succeed (ex: database update)

You can pass a custom object to this function.

For example you can set a custom success message:

success({ message: "Successfully update the user!" });

Open a new tab:

success({
  action: 'open_tab',
  link: 'https://link_to_open'
});

Download an inline generated file:

success({
  message: 'The invoice has been updated',
  action: 'download',
  data: InvoiceData,
  filename: 'invoice.pdf'
});

Or simply reload the back-office page

success({ reload: true });

---

error: Function

The function that have to be executed if your custom action has failed (ex: failed database update or when you need more info to execute the action)

You can pass a custom object to this function.

For example you can set a custom error message:

error({ message: "Cannot update the specific user" });

If you need more info to execute the action, you can configure a custom Form that will appear to the user screen like this:

if (!props.data.validation_date) {
  error({
    form: {
      title: 'KYC Check Form',
      submitLabel: 'Save',
      fields: [{
        label: 'Validation date',
        name: 'validation_date',
        type: 'date',
        required: true
      }]
    }
  });
}
else {
  // The form is filled correctly
  // Do what you want to do here

  success();
}

In the example above the user will be asked to fill the validation_date input. After the new form submission, the data parameter will include the validation_date property magically for you to use it freely in your handler function code ✌️