CodeAPI

Hooks

Hooks that can be added to wix-data operations.

Data hooks run code before or after certain interactions with your site's collections. A data hook allows you to intercept the interaction immediately before or immediately after it occurs. The hook's code can even be used to affect the interaction itself. For example, you may want to intercept an item before it is added to your collection to perform a final validation or tweak the data that actually makes it into the collection.

In general, hooks are run whether the interaction with your collection is initiated by a page element, programmatically, or when using the Content Manager. However, a Data API call from the backend code of your site may pass the optional WixDataOptions object and use it to suppress hooks from being called on that particular operation.

To add a hook to a collection, in the Content Manager click on the Hooks button and choose which hooks to add. Code for the hooks is written in the data.js file which resides in Backend section of your site. Hook functions are defined using the following pattern:

 export function <collectionName>_<hookName>(<parameters>) { }

Table of Contents

FUNCTIONS

?
Perform actions on an object.
afterCount( )A hook that is triggered after a count() operation.
afterGet( )A hook that is triggered after a get() operation.
afterInsert( )A hook that is triggered after an insert() operation.
afterQuery( )A hook that is triggered after a find operation, for each of the items in the query results.
afterRemove( )A hook that is triggered after a remove() operation.
afterUpdate( )A hook that is triggered after an update() operation.
beforeCount( )A hook that is triggered before a count() operation.
beforeGet( )A hook that is triggered before a get() operation.
beforeInsert( )A hook that is triggered before an insert() operation.
beforeQuery( )A hook that is triggered before a find() operation.
beforeRemove( )A hook that is called before a remove() operation.
beforeUpdate( )A hook that is triggered before an update() operation.
onFailure( )A hook that is triggered on any error or rejected Promise from any of the wix-data operations.

OBJECTS

?
Objects used when setting, getting, or calling the properties and methods listed above.
HookContextAn object that contains contextual information about the hook being called.

afterCount( )

A hook that is triggered after a count() operation.

Description

The afterCount() hook runs when:

  • The count() function is called.
  • The collection is viewed in the Content Manager.

Return a number or a Promise that resolves to number from the afterCount() function. The returned number will be used as the result of the call to count() instead of the actual count of items found in the collection. If returning a Promise, the number is used as the result, whether the Promise is fulfilled or rejected.

If the returned value is of the wrong type, the value is ignored.

A rejected Promise also calls the onFailure() hook if it has been registered.

Syntax

function afterCount(count: number, context: HookContext): Promise<number>
PARAMETERS
?
Values that you pass to a function.
count
number
The number of items the count operation has found.
context
Contextual information about the hook.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<number>

Fulfilled - The count to return to count() instead of the original count. Rejected - Returning a rejected promise will not block the operation, but will return a rejected promise to the caller as well as trigger the onFailure() hook.

Examples

A hook after a count

// In data.js

export function myCollection_afterCount(count, context) {
  let originalCount = count;  // 5
  let hookContext = context;  // see below

  // some change to the received count

  return newCount;
}

/*
 * hookContext:
 *
 * {
 *   "collectionName": "myCollection",
 *   "userId":         "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3",
 *   "userRole":       "siteOwner"
 * }
 */

Change the count

// In data.js

export function myCollection_afterCount(count, context) {
  let originalCount = count;  // 5
  let hookContext = context;  // see below

  // some change to the received count
  let newCount = originalCount + 1;

  return newCount;
}

/*
 * hookContext:
 *
 * {
 *   "collectionName": "myCollection",
 *   "userId":         "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3",
 *   "userRole":       "siteOwner"
 * }
 */

afterGet( )

A hook that is triggered after a get() operation.

Description

The afterGet() hook runs when the get() function is called.

The hook does not run when the find function is called or when a dataset retrieves items from the collection it is connected to.

Return an object or a Promise that resolves to an object from the afterGet() function. The returned object will be used as the result of the call to the get() function instead of the actual item found in the collection. If returning a Promise, the object is used as the result, whether the Promise is fulfilled or rejected.

If the returned value is of the wrong type, the value is ignored.

A rejected Promise also calls the onFailure() hook if it has been registered.

Syntax

function afterGet(item: Object, context: HookContext): Promise<Object>
PARAMETERS
?
Values that you pass to a function.
item
Object
The item that was retrieved from the collection.
context
Contextual information about the hook.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<Object>

Fulfilled - The item to return to get() instead of the retrieved item. Rejected - returning a rejected promise will not block the operation, but will return a rejected promise to the operation caller as well as trigger the onFailure() hook.

Examples

A hook after a get

// In data.js

export function myCollection_afterGet(item, context) {
  let hookContext = context;  // see below

  // some changes to the received item

  return item;
}

/*
 * hookContext:
 *
 * {
 *   "collectionName": "myCollection",
 *   "userId":         "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3",
 *   "userRole":       "siteOwner"
 * }
 */

Change the retrieved item

// In data.js

export function myCollection_afterGet(item, context) {
  let hookContext = context;  // see below

  // some changes to the received item
  item.full_name = item.first_name + " " + item.last_name;

  return item;
}

/*
 * hookContext:
 *
 * {
 *   "collectionName": "myCollection",
 *   "userId":         "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3",
 *   "userRole":       "siteOwner"
 * }
 */

afterInsert( )

A hook that is triggered after an insert() operation.

Description

The afterInsert() hook runs when:

  • The insert() function is called.
  • An action is performed on a dataset that inserts a new item into the collection.
  • An item is inserted using the Content Manager.
  • An item is imported into the collection. (Sandbox only.)

Return an object or a Promise that resolves to an object from the afterInsert() function. The returned object will be used as the result of the call to the insert() function instead of the actual item inserted into the collection. If returning a Promise, the object is used as the result, whether the Promise is fulfilled or rejected.

If the returned value is of the wrong type, the value is ignored.

A rejected Promise also calls the onFailure() hook if it has been registered.

Because the afterInsert hook is called after the insert() is executed, it cannot affect the item that is inserted into the collection. It can only affect the item returned by insert().

Syntax

function afterInsert(item: Object, context: HookContext): Promise<Object>
PARAMETERS
?
Values that you pass to a function.
item
Object
The item that was inserted.
context
Contextual information about the hook.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<Object>

Fulfilled - The item to return to insert() instead of the inserted item. Rejected - Returning a rejected promise will not block the operation, but will return a rejected promise to the caller as well as trigger the onFailure() hook.

Examples

A hook after an insert

// In data.js

export function myCollection_afterInsert(item, context) {
  let hookContext = context;  // see below

  // some changes to the received item

  return item;
}

/*
 * hookContext:
 *
 * {
 *   "collectionName": "myCollection",
 *   "userId":         "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3",
 *   "userRole":       "siteOwner"
 * }
 */

Change the retrieved item

// In data.js

export function myCollection_afterInsert(item, context) {
  let hookContext = context;  // see below

  // some changes to the received item
  item.full_name = item.first_name + " " + item.last_name;

  return item;
}

/*
 * hookContext:
 *
 * {
 *   "collectionName": "myCollection",
 *   "userId":         "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3",
 *   "userRole":       "siteOwner"
 * }
 */

afterQuery( )

A hook that is triggered after a find operation, for each of the items in the query results.

Description

The afterQuery() hook runs when:

  • The find function is called.
  • An action is performed on a dataset that retrieves items from the collection.
  • The collection is viewed in the Content Manager.
  • An item is imported into the collection. (Sandbox only.)
  • An item is exported from the collection. (Sandbox only.)

The hook runs once for each item in the collection.

Return an object or a Promise that resolves to an object from the afterQuery() function. The returned object will be used as the result of the call to the find function instead of the actual item found in the collection. If returning a Promise, the object is used as the result, whether the Promise is fulfilled or rejected.

If the returned value is of the wrong type, the value is ignored.

A rejected Promise also calls the onFailure() hook if it has been registered.

Syntax

function afterQuery(item: Object, context: HookContext): Promise<Object>
PARAMETERS
?
Values that you pass to a function.
item
Object
One of the items of the query result. The hook is called for each item in the results.
context
Contextual information about the hook.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<Object>

Fulfilled - The item to return to find instead of the item retrieved from the database. Rejected - Returning a rejected promise will not block the operation, but will return a rejected promise to the operation caller as well as trigger the onFailure() hook.

Examples

A hook after a find

// In data.js

export function myCollection_afterQuery(item, context) {
  let hookContext = context;  // see below

  // some changes to the received item

  return item;
}

/*
 * hookContext:
 *
 * {
 *   "collectionName": "myCollection",
 *   "userId":         "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3",
 *   "userRole":       "siteOwner"
 * }
 */

Change the retrieved item

// In data.js

export function myCollection_afterQuery(item, context) {
  let hookContext = context;  // see below

  // some changes to the received item
  item.full_name = item.first_name + " " + item.last_name;

  return item;
}

/*
 * hookContext:
 *
 * {
 *   "collectionName": "myCollection",
 *   "userId":         "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3",
 *   "userRole":       "siteOwner"
 * }
 */

afterRemove( )

A hook that is triggered after a remove() operation.

Description

The afterRemove() hook runs when:

  • The remove() function is called.
  • An action is performed on a dataset that removes an item from the collection.
  • An item is deleted using the Content Manager.

Return an object or a Promise that resolves to an object. The returned object will be used as the result of the call to the remove() function instead of the actual item removed from the collection. If returning a Promise, the object is used as the result, whether the Promise is fulfilled or rejected.

If the returned value is of the wrong type, the value is ignored.

A rejected Promise also calls the onFailure() hook if it has been registered.

Because the afterRemove() hook is called after the remove() is executed, it cannot prevent the item from being removed from the collection. It can only affect the item returned by remove().

Syntax

function afterRemove(item: Object, context: HookContext): Promise<Object>
PARAMETERS
?
Values that you pass to a function.
item
Object
The item that was removed.
context
Contextual information about the hook.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<Object>

Fulfilled - The item to return to remove() instead of the deleted item. Rejected - Returning a rejected promise will not block the operation, but will return a rejected promise to the caller as well as trigger the onFailure() hook.

Examples

A hook after a remove

// In data.js

export function myCollection_afterRemove(item, context) {
  let hookContext = context;  // see below

  // some changes to the removed item

  return item;
}

/*
 * hookContext:
 *
 * {
 *   "collectionName": "myCollection",
 *   "userId":         "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3",
 *   "userRole":       "siteOwner"
 * }
 */

Change the retrieved item

// In data.js

export function myCollection_afterUpdate(item, context) {
  let hookContext = context;  // see below

  // some changes to the removed item
  item.full_name = item.first_name + " " + item.last_name;

  return item;
}

/*
 * hookContext:
 *
 * {
 *   "collectionName": "myCollection",
 *   "userId":         "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3",
 *   "userRole":       "siteOwner"
 * }
 */

afterUpdate( )

A hook that is triggered after an update() operation.

Description

The afterUpdate() hook runs when:

  • The update() function is called.
  • An action is performed on a dataset that updates an item from the collection.
  • An item is updated using the Content Manager.

Return an object or a Promise that resolves to an object from the afterUpdate() function. The returned object will be used as the result of the call to the update() function instead of the actual item updated in the collection. If returning a Promise, the object is used as the result, whether the Promise is fulfilled or rejected.

If the returned value is of the wrong type, the value is ignored.

A rejected Promise also calls the onFailure() hook if it has been registered.

Because the afterUpdate hook is called after the update() is executed, it cannot affect the item that is being updated in the collection. It can only affect the item returned by update().

Syntax

function afterUpdate(item: Object, context: HookContext): Promise<Object>
PARAMETERS
?
Values that you pass to a function.
item
Object
The updated item.
context
Contextual information about the hook.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<Object>

Fulfilled - The item to return to update() instead of the updated item. Rejected - Returning a rejected promise will not block the operation, but will return a rejected promise to the caller as well as trigger the onFailure() hook.

Examples

A hook after an update

// In data.js

export function myCollection_afterUpdate(item, context) {
  let hookContext = context;  // see below

  // some changes to the received item

  return item;
}

/*
 * hookContext:
 *
 * {
 *   "collectionName": "myCollection",
 *   "userId":         "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3",
 *   "userRole":       "siteOwner"
 * }
 */

Change the retrieved item

// In data.js

export function myCollection_afterUpdate(item, context) {
  let hookContext = context;  // see below

  // some changes to the received item
  item.full_name = item.first_name + " " + item.last_name;

  return item;
}

/*
 * hookContext:
 *
 * {
 *   "collectionName": "myCollection",
 *   "userId":         "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3",
 *   "userRole":       "siteOwner"
 * }
 */

beforeCount( )

A hook that is triggered before a count() operation.

Description

The beforeCount() hook runs when:

  • The count() function is called.
  • The collection is viewed in the Content Manager.

Return a query or a Promise that resolves to a query from the beforeCount() function. The returned query will be used as the query for the count() operation.

Often, you will modify the query that is received in the query parameter by calling one or more WixDataQuery functions.

If the returned value is of the wrong type, the value is ignored.

A rejected Promise blocks the call to count() and also calls the onFailure() hook if it has been registered.

Because the beforeCount() hook is called before count() is executed, it can affect how items are counted or block the count().

Syntax

function beforeCount(query: WixDataQuery, context: HookContext): Promise<WixDataQuery>
PARAMETERS
?
Values that you pass to a function.
query
The original query as defined by count().
context
Contextual information about the hook.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<WixDataQuery>

Fulfilled - The query to be used for the count() operation instead of the original query. Rejected - Returning a rejected promise will block the operation and will return a rejected promise to the caller as well as trigger the onFailure() hook.

Examples

A hook before a count

// In data.js

export function myCollection_beforeCount(query, context) {
  let hookContext = context;  // see below

  // some change to the received query

  return newQuery;
}

/*
 * hookContext:
 *
 * {
 *   "collectionName": "myCollection",
 *   "userId":         "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3",
 *   "userRole":       "siteOwner"
 * }
 */

Change the count

// In data.js

export function myCollection_beforeCount(query, context) {
  let hookContext = context;  // see below

  // some change to the received query
  let newQuery = query.eq("status", "active");

  return newQuery;
}

/*
 * hookContext:
 *
 * {
 *   "collectionName": "myCollection",
 *   "userId":         "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3",
 *   "userRole":       "siteOwner"
 * }
 */

beforeGet( )

A hook that is triggered before a get() operation.

Description

The beforeGet() hook runs when the get() function is called.

The hook does not run when the find function is called or when a dataset retrieves items from the collection it is connected to.

Return a string or a Promise that resolves to a string from the beforeGet() function. The returned string will be used as the itemId parameter for the get() operation. The item with the new itemId will be retrieved instead of the item with the original itemId.

If the returned value is of the wrong type, the value is ignored.

A rejected Promise blocks the call to get() and also calls the onFailure() hook if it has been registered.

Because the beforeGet() hook is called before get() is executed, it can affect which item is retrieved or block the get().

Syntax

function beforeGet(itemId: string, context: HookContext): Promise<string>
PARAMETERS
?
Values that you pass to a function.
itemId
string
The ID of the original item to be retrieved.
context
Contextual information about the hook.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<string>

Fulfilled - The ID to be used for the get() operation instead of the original itemId specified by the caller. Rejected - Returning a rejected promise will block the operation and will return a rejected promise to the caller as well as trigger the onFailure() hook.

Examples

A hook before a get

// In data.js

export function myCollection_beforeGet(itemId, context) {
  let hookContext = context;  // see below

  // change the item to get

  return newItemId;
}

/*
 * hookContext:
 *
 * {
 *   "collectionName": "myCollection",
 *   "userId":         "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3",
 *   "userRole":       "siteOwner"
 * }
 */

Change the item to get

// In data.js

export function myCollection_beforeGet(itemId, context) {
  let hookContext = context;  // see below

  // change the item to get
  let newItemId = "1234";

  return newItemId;
}

/*
 * hookContext:
 *
 * {
 *   "collectionName": "myCollection",
 *   "userId":         "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3",
 *   "userRole":       "siteOwner"
 * }
 */

beforeInsert( )

A hook that is triggered before an insert() operation.

Description

The beforeInsert() hook runs when:

  • The insert() function is called.
  • An action is performed on a dataset that inserts a new item into the collection.
  • An item is inserted using the Content Manager.
  • An item is imported into the collection. (Sandbox only.)

The hook also runs when an action is performed on a dataset that inserts a new item into the collection that the dataset is connected to.

Return an object or a Promise that resolves to an object from the beforeInsert() function. The returned object will be inserted into the collection instead of the original item passed to the insert() function.

If the returned value is of the wrong type, the value is ignored.

A rejected Promise blocks the call to insert() and also calls the onFailure() hook if it has been registered.

Because the beforeInsert() hook is called before insert() is executed, it can affect the item that is inserted into the collection or block the insert().

Syntax

function beforeInsert(item: Object, context: HookContext): Promise<Object>
PARAMETERS
?
Values that you pass to a function.
item
Object
The original item to be inserted.
context
Contextual information about the hook.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<Object>

Fulfilled - The item to be inserted instead of the original item specified by the caller. Rejected - Returning a rejected promise will block the operation and will return a rejected promise to the caller as well as trigger the onFailure() hook.

Examples

A hook before an insert

// In data.js

export function myCollection_beforeInsert(item, context) {
  let hookContext = context;  // see below

  // some change to the received item

  return item;
}

/*
 * hookContext:
 *
 * {
 *   "collectionName": "myCollection",
 *   "userId":         "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3",
 *   "userRole":       "siteOwner"
 * }
 */

Change the item to insert

// In data.js

export function myCollection_beforeInsert(item, context) {
  let hookContext = context;  // see below

  // some change to the received item
  item.title = toUpperFirst(item.title);
  item.first_name = toUpperFirst(item.first_name);
  item.last_name = toUpperFirst(item.last_name);

  return item;
}

function toUpperFirst(s) {
  return s.charAt(0).toUpperCase() + s.slice(1);
}

/*
 * hookContext:
 *
 * {
 *   "collectionName": "myCollection",
 *   "userId":         "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3",
 *   "userRole":       "siteOwner"
 * }
 */

beforeQuery( )

A hook that is triggered before a find() operation.

Description

The beforeQuery() hook runs when:

  • The find function is called.
  • An action is performed on a dataset that retrieves items from the collection.
  • The collection is viewed in the Content Manager.
  • An item is imported into the collection. (Sandbox only.)
  • An item is exported from the collection. (Sandbox only.)

The hook also runs when an action is performed on a dataset that retrieves items from the collection that the dataset is connected to.

Return a query or a Promise that resolves to a query from the beforeQuery() function. The returned query will be used as the query for the find operation.

Often, you will modify the query that is received in the query parameter by calling one or more WixDataQuery functions.

If the returned value is of the wrong type, the value is ignored.

A rejected Promise blocks the call to find() and also calls the onFailure() hook if it has been registered.

Because the beforeQuery() hook is called before find() is executed, it can affect the query that is used to retrieve items or block the find().

Syntax

function beforeQuery(query: WixDataQuery, context: HookContext): Promise<WixDataQuery>
PARAMETERS
?
Values that you pass to a function.
query
The original query as specified by the caller.
context
Contextual information about the hook.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<WixDataQuery>

Fulfilled - The query to use instead of the original query specified by the caller. Rejected - returning a rejected promise will block the operation and will return a rejected promise to the operation caller as well as trigger the onFailure() hook.

Examples

A hook before a find

// In data.js

export function myCollection_beforeQuery(query, context) {
  let hookContext = context;  // see below

  // some change to the received query

  return newQuery;
}

/*
 * hookContext:
 *
 * {
 *   "collectionName": "myCollection",
 *   "userId":         "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3",
 *   "userRole":       "siteOwner"
 * }
 */

Change the query

// In data.js

export function myCollection_beforeQuery(query, context) {
  let hookContext = context;  // see below

  // some change to the received query
  let newQuery = query.eq("status", "active");

  return newQuery;
}

/*
 * hookContext:
 *
 * {
 *   "collectionName": "myCollection",
 *   "userId":         "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3",
 *   "userRole":       "siteOwner"
 * }
 */

beforeRemove( )

A hook that is called before a remove() operation.

Description

The beforeRemove() hook runs when:

  • The remove() function is called.
  • An action is performed on a dataset that removes an item from the collection.
  • An item is deleted using the Content Manager.

The hook also runs when an action is performed on a dataset that removes an item from the collection that the dataset is connected to.

Return a string or a Promise that resolves to a string from the beforeRemove() function. The returned string will be used as the itemId parameter for the remove() operation. The item with the new itemId will be removed instead of the item with the original itemId.

If the returned value is of the wrong type, the value is ignored.

A rejected Promise blocks the call to remove() and also calls the onFailure() hook if it has been registered.

Because the beforeRemove() hook is called before remove() is executed, it can affect the item that is removed from the collection or block the remove().

Syntax

function beforeRemove(itemId: string, context: HookContext): Promise<string>
PARAMETERS
?
Values that you pass to a function.
itemId
string
The ID of the original item to be removed.
context
Contextual information about the hook.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<string>

Fulfilled - The ID to be used for the remove() instead of the original itemId specified by the caller.. Rejected - Returning a rejected promise will block the operation and will return a rejected promise to the caller as well as trigger the onFailure() hook.

Examples

A hook before a remove

// In data.js

export function myCollection_beforeRemove(itemId, context) {
  let hookContext = context;  // see below

  // change to the item to remove

  return newItemId;
}

/*
 * hookContext:
 *
 * {
 *   "collectionName": "myCollection",
 *   "userId":         "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3",
 *   "userRole":       "siteOwner"
 * }
 */

Change the item to remove

// In data.js

export function myCollection_beforeRemove(itemId, context) {
  let hookContext = context;  // see below

  // change to the item to remove
  let newItemId = "1234";

  return newItemId;
}

/*
 * hookContext:
 *
 * {
 *   "collectionName": "myCollection",
 *   "userId":         "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3",
 *   "userRole":       "siteOwner"
 * }
 */

beforeUpdate( )

A hook that is triggered before an update() operation.

Description

The beforeUpdate() hook runs when:

  • The update() function is called.
  • An action is performed on a dataset that updates an item from the collection.
  • An item is updated using the Content Manager.

The hook also runs when an action is performed on a dataset that updates an item from the collection that the dataset is connected to.

Return an object or a Promise that resolves to an object from the beforeUpdate() function. The returned object will be updated in the collection instead of the original item passed to the update() function.

If the returned value is of the wrong type, the value is ignored.

A rejected Promise blocks the call to update() and also calls the onFailure() hook if it has been registered.

Because the beforeUpdate() hook is called before the update() is executed, it can affect the item that is updated in the collection or block the update().

Syntax

function beforeUpdate(item: Object, context: HookContext): Promise<Object>
PARAMETERS
?
Values that you pass to a function.
item
Object
The original item to be updated.
context
Contextual information about the hook.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<Object>

Fulfilled - The item to be updated instead of the original item specified by the caller. Rejected - Returning a rejected promise will block the operation and will return a rejected promise to the caller as well as trigger the onFailure() hook.

Examples

A hook before an update

// In data.js

export function myCollection_beforeUpdate(item, context) {
  let hookContext = context;  // see below

  // some change to the received item

  return item;
}

/*
 * hookContext:
 *
 * {
 *   "collectionName": "myCollection",
 *   "userId":         "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3",
 *   "userRole":       "siteOwner"
 * }
 */

Change the item to update

// In data.js

export function myCollection_beforeUpdate(item, context) {
  let hookContext = context;  // see below

  // some change to the received item
  item.title = toUpperFirst(item.title);
  item.first_name = toUpperFirst(item.first_name);
  item.last_name = toUpperFirst(item.last_name);

  return item;
}

function toUpperFirst(s) {
  return s.charAt(0).toUpperCase() + s.slice(1);
}

/*
 * hookContext:
 *
 * {
 *   "collectionName": "myCollection",
 *   "userId":         "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3",
 *   "userRole":       "siteOwner"
 * }
 */

onFailure( )

A hook that is triggered on any error or rejected Promise from any of the wix-data operations.

Description

The onFailure() hook is triggered whenever a wix-data operation or hook returns a rejected Promise or an error.

Syntax

function onFailure(error: Error, context: HookContext): Promise<Object>
PARAMETERS
?
Values that you pass to a function.
error
Error
The error that caused the failure.
context
Contextual information about the hook.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<Object>

Fulfilled - Returning a fulfilled promise will result in a fulfilled data operation with the provided result. Rejected - Returning a rejected promise will result in returning a rejected promise to the caller of the data operation.

Examples

A hook when a failure occurs

// In data.js

export function myCollection_onFailure(error, context) {
  let hookError = error;  // see below

  // handle error

  return ret;
}

/*
 * hookError:
 *
 * {
 *   "message": "An item with _id [1234] already exists.",
 *   "code":    -409
 * }
 */

HookContext

An object that contains contextual information about the hook being called.

Syntax

type HookContext = {
  collectionName: string
  userId: string
  userRole: string
  currentItem: Object
}
MEMBERS
?
The properties of an object.
collectionName
string
The name of the collection the hook affects.
userId
string
The current site user id. If no user is logged in to the site it may be null.
userRole
string
The permissions role of the current user. Possibilities are: anonymous, siteMember, siteOwner and dataOwner.
currentItem
Object

The item stored in the database before an update or delete operation. Will be undefined for all other operations.