More info on documentation about event hooks (onBeforeItemUpsert) [Modified title]

[gdoumenc]

Hi,

In the event hooks SDK documentation, can you add the information on when the hook onBeforeItemUpsert is called : before or after the fields validation ? (Event hooks | Documentation — DatoCMS)

Regards

[roger]

Hey @gdoumenc,

I’ll try to update the docs for that shortly, but to answer your question, it happens before serverside validation, and regardless of clientside validation:

More details:

• Clientside validation happens on a per-field basis and only on blur (when the user clicks outside or otherwise exits the field)
• Serverside validation happens when you click “Save”, but:
  • The hook will run first, before anything is sent
  • If you return false from onBeforeItemUpsert(), the validation & save will never happen. The hook intercepts the event and prevents anything from getting sent.
  • If you return true, the hook will still run first, but then validation & saving will proceed normally.

Hope that helps!

[roger]

I should note that there currently appears to be a bug: If you have a validation error on the form and click Save, but with onBeforeItemUpsert() returning false and thus intercepting the request, the clientside form will think the validation succeeded and clear the validation errors.

I’ve reported that to the devs and will update here (and the documentation too) once it’s resolved.

Sorry about that

[roger]

@gdoumenc,

Thanks again for the suggestion! We’ve now updated the documentation to hopefully be clearer:

This hook is called when the user attempts to save a record. You can use it to block record saving.

If you return false, the record will NOT be saved. A small on-page error will say “A plugin blocked the action”. However, for better UX, consider also using ctx.alert() to better explain to the user why their save was blocked.

If you return true, the save will proceed as normal.

This hook runs BEFORE serverside validation. You can use it to do your own additional validation before returning.

Clientside validations are not affected by this hook, since those occur on individual fields’ onBlur() events.

You should now see this both in the online documentation and in the TypeScript defs of the latest Plugin SDK version.