Data Hooks Best Practices

Working with multiple fields in record hooks

When working with record hooks, it is useful to be able to validate information using multiple fields. For example, say you require an email or user Id. You can use record hooks to compare the two fields, and if both are blank, you can mark the data with an error message on one or both fields to indicate to the user that one field or the other is required. In working with these two fields, you can reference

record.email
and
record.userId
and return an error when neither have a value.

Here's an example of the above usage:

Splitting record hooks by init or change

It's key to note that while record hooks run both on

init
and on
change
, you have access to differentiate between the two mode types with a third, optional
mode
parameter in the
registerRecordHooks
method. This will identify each call to the record hook as either
init
or
change
. This split can be used to perform different tasks depending on what mode is being executed. There are many reasons why you might want to use these different states in the validation process, but one of the most common is for working with external data (which we discuss in our guide for working with external data).

For the example here, we will add a different message onto the same field, one on

init
and the other will update the message and error level on
change
of the record.

In the above example, when the file is dropped and the review stage begins, any record with an email would have red highlighting and display the message "On Init: Email in error state to show init" when the cell is hovered over. When any record on the field is updated, the email field for that record will then change to yellow highlighting and display the message "On Change: Email in warning state to show changed record" when hovered over.

Validating with external data

In our guide for working with external data, we have an example and more details about this, but we think it is fair to also point out here the common uses and mistakes for using Data Hooks with external data.

In the above section, you can see how to split the record hooks based on

init
or
change
. The key for validating with external data is to not use the record hooks on
init
, but only on
change
when making API calls inside hook. If you need to make them on
init
, you should use a field hook to grab all the values of the field in bulk and then perform the necessary actions on all of the items in the field before returning the data. You may then perform the same or similar call on each field as they are changed using the
change
event on record hooks.

Data Hooks: run order and flow

When considering Data Hooks best practices, it is important to re-iterate the order of which these hooks will process. In any import, field hooks will be run in the order that they are presented in the code (and will only run once), then record hooks on

init
would be run. After these have finished running, the Review stage of the import begins. As each record is updated, the
change
record hooks will run on the record that has been updated.