wix-data.Hooks

wix-data.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:

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

Contents

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.
HookContext An object that contains contextual information about the hook being called.
afterCount( )

afterCount( )

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

export function <collectionName>_afterCount(count: Number,
  context: HookContext): Promise<Number>

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.

Parameters

count Number The number of items the count operation has found.
context HookContext Contextual information about the hook.

Return Value

Returns a Promise

On fulfillment Number The count to return to count() instead of the original count.
On rejection Error 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

Ly8gSW4gZGF0YS5qcwoKZXhwb3J0IGZ1bmN0aW9uIG15Q29sbGVjdGlvbl9hZnRlckNvdW50KGNvdW50LCBjb250ZXh0KSB7CiAgbGV0IG9yaWdpbmFsQ291bnQgPSBjb3VudDsgIC8vIDUKICBsZXQgaG9va0NvbnRleHQgPSBjb250ZXh0OyAgLy8gc2VlIGJlbG93CgogIC8vIHNvbWUgY2hhbmdlIHRvIHRoZSByZWNlaXZlZCBjb3VudAoKICByZXR1cm4gbmV3Q291bnQ7Cn0KCi8qCiAqIGhvb2tDb250ZXh0OgogKgogKiB7CiAqICAgImNvbGxlY3Rpb25OYW1lIjogIm15Q29sbGVjdGlvbiIsCiAqICAgInVzZXJJZCI6ICAgICAgICAgImY0NWpmOGQyLWdya2otMm9wZC00b3ZrLTlyZmo0d281dHZqMyIsCiAqICAgInVzZXJSb2xlIjogICAgICAgInNpdGVPd25lciIKICogfQogKi8K
// 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

Ly8gSW4gZGF0YS5qcwoKZXhwb3J0IGZ1bmN0aW9uIG15Q29sbGVjdGlvbl9hZnRlckNvdW50KGNvdW50LCBjb250ZXh0KSB7CiAgbGV0IG9yaWdpbmFsQ291bnQgPSBjb3VudDsgIC8vIDUKICBsZXQgaG9va0NvbnRleHQgPSBjb250ZXh0OyAgLy8gc2VlIGJlbG93CgogIC8vIHNvbWUgY2hhbmdlIHRvIHRoZSByZWNlaXZlZCBjb3VudAogIGxldCBuZXdDb3VudCA9IG9yaWdpbmFsQ291bnQgKyAxOwoKICByZXR1cm4gbmV3Q291bnQ7Cn0KCi8qCiAqIGhvb2tDb250ZXh0OgogKgogKiB7CiAqICAgImNvbGxlY3Rpb25OYW1lIjogIm15Q29sbGVjdGlvbiIsCiAqICAgInVzZXJJZCI6ICAgICAgICAgImY0NWpmOGQyLWdya2otMm9wZC00b3ZrLTlyZmo0d281dHZqMyIsCiAqICAgInVzZXJSb2xlIjogICAgICAgInNpdGVPd25lciIKICogfQogKi8K
// 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( )

afterGet( )

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

export function <collectionName>_afterGet(item: Object,
  context: HookContext): Promise<Object>

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.

Parameters

item Object The item that was retrieved from the collection.
context HookContext Contextual information about the hook.

Return Value

Returns a Promise

On fulfillment Object The item to return to get() instead of the retrieved item.
On rejection Error 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

Ly8gSW4gZGF0YS5qcwoKZXhwb3J0IGZ1bmN0aW9uIG15Q29sbGVjdGlvbl9hZnRlckdldChpdGVtLCBjb250ZXh0KSB7CiAgbGV0IGhvb2tDb250ZXh0ID0gY29udGV4dDsgIC8vIHNlZSBiZWxvdwoKICAvLyBzb21lIGNoYW5nZXMgdG8gdGhlIHJlY2VpdmVkIGl0ZW0KCiAgcmV0dXJuIGl0ZW07Cn0KCi8qCiAqIGhvb2tDb250ZXh0OgogKgogKiB7CiAqICAgImNvbGxlY3Rpb25OYW1lIjogIm15Q29sbGVjdGlvbiIsCiAqICAgInVzZXJJZCI6ICAgICAgICAgImY0NWpmOGQyLWdya2otMm9wZC00b3ZrLTlyZmo0d281dHZqMyIsCiAqICAgInVzZXJSb2xlIjogICAgICAgInNpdGVPd25lciIKICogfQogKi8K
// 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

Ly8gSW4gZGF0YS5qcwoKZXhwb3J0IGZ1bmN0aW9uIG15Q29sbGVjdGlvbl9hZnRlckdldChpdGVtLCBjb250ZXh0KSB7CiAgbGV0IGhvb2tDb250ZXh0ID0gY29udGV4dDsgIC8vIHNlZSBiZWxvdwoKICAvLyBzb21lIGNoYW5nZXMgdG8gdGhlIHJlY2VpdmVkIGl0ZW0KICBpdGVtLmZ1bGxfbmFtZSA9IGl0ZW0uZmlyc3RfbmFtZSArICIgIiArIGl0ZW0ubGFzdF9uYW1lOwoKICByZXR1cm4gaXRlbTsKfQoKLyoKICogaG9va0NvbnRleHQ6CiAqCiAqIHsKICogICAiY29sbGVjdGlvbk5hbWUiOiAibXlDb2xsZWN0aW9uIiwKICogICAidXNlcklkIjogICAgICAgICAiZjQ1amY4ZDItZ3Jrai0yb3BkLTRvdmstOXJmajR3bzV0dmozIiwKICogICAidXNlclJvbGUiOiAgICAgICAic2l0ZU93bmVyIgogKiB9CiAqLwo=
// 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( )

afterInsert( )

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

export function <collectionName>_afterInsert(item: Object,
  context: HookContext): Promise<Object>

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().

Parameters

item Object The item that was inserted.
context HookContext Contextual information about the hook.

Return Value

Returns a Promise

On fulfillment Object The item to return to insert() instead of the inserted item.
On rejection Error 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

Ly8gSW4gZGF0YS5qcwoKZXhwb3J0IGZ1bmN0aW9uIG15Q29sbGVjdGlvbl9hZnRlckluc2VydChpdGVtLCBjb250ZXh0KSB7CiAgbGV0IGhvb2tDb250ZXh0ID0gY29udGV4dDsgIC8vIHNlZSBiZWxvdwoKICAvLyBzb21lIGNoYW5nZXMgdG8gdGhlIHJlY2VpdmVkIGl0ZW0KCiAgcmV0dXJuIGl0ZW07Cn0KCi8qCiAqIGhvb2tDb250ZXh0OgogKgogKiB7CiAqICAgImNvbGxlY3Rpb25OYW1lIjogIm15Q29sbGVjdGlvbiIsCiAqICAgInVzZXJJZCI6ICAgICAgICAgImY0NWpmOGQyLWdya2otMm9wZC00b3ZrLTlyZmo0d281dHZqMyIsCiAqICAgInVzZXJSb2xlIjogICAgICAgInNpdGVPd25lciIKICogfQogKi8K
// 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

Ly8gSW4gZGF0YS5qcwoKZXhwb3J0IGZ1bmN0aW9uIG15Q29sbGVjdGlvbl9hZnRlckluc2VydChpdGVtLCBjb250ZXh0KSB7CiAgbGV0IGhvb2tDb250ZXh0ID0gY29udGV4dDsgIC8vIHNlZSBiZWxvdwoKICAvLyBzb21lIGNoYW5nZXMgdG8gdGhlIHJlY2VpdmVkIGl0ZW0KICBpdGVtLmZ1bGxfbmFtZSA9IGl0ZW0uZmlyc3RfbmFtZSArICIgIiArIGl0ZW0ubGFzdF9uYW1lOwoKICByZXR1cm4gaXRlbTsKfQoKLyoKICogaG9va0NvbnRleHQ6CiAqCiAqIHsKICogICAiY29sbGVjdGlvbk5hbWUiOiAibXlDb2xsZWN0aW9uIiwKICogICAidXNlcklkIjogICAgICAgICAiZjQ1amY4ZDItZ3Jrai0yb3BkLTRvdmstOXJmajR3bzV0dmozIiwKICogICAidXNlclJvbGUiOiAgICAgICAic2l0ZU93bmVyIgogKiB9CiAqLwo=
// 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( )

afterQuery( )

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

export function <collectionName>_afterQuery(item: Object,
  context: HookContext): Promise<Object>

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.

Parameters

item Object One of the items of the query result. The hook is called for each item in the results.
context HookContext Contextual information about the hook.

Return Value

Returns a Promise

On fulfillment Object The item to return to find instead of the item retrieved from the database.
On rejection Error 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

Ly8gSW4gZGF0YS5qcwoKZXhwb3J0IGZ1bmN0aW9uIG15Q29sbGVjdGlvbl9hZnRlclF1ZXJ5KGl0ZW0sIGNvbnRleHQpIHsKICBsZXQgaG9va0NvbnRleHQgPSBjb250ZXh0OyAgLy8gc2VlIGJlbG93CgogIC8vIHNvbWUgY2hhbmdlcyB0byB0aGUgcmVjZWl2ZWQgaXRlbQoKICByZXR1cm4gaXRlbTsKfQoKLyoKICogaG9va0NvbnRleHQ6CiAqCiAqIHsKICogICAiY29sbGVjdGlvbk5hbWUiOiAibXlDb2xsZWN0aW9uIiwKICogICAidXNlcklkIjogICAgICAgICAiZjQ1amY4ZDItZ3Jrai0yb3BkLTRvdmstOXJmajR3bzV0dmozIiwKICogICAidXNlclJvbGUiOiAgICAgICAic2l0ZU93bmVyIgogKiB9CiAqLwo=
// 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

Ly8gSW4gZGF0YS5qcwoKZXhwb3J0IGZ1bmN0aW9uIG15Q29sbGVjdGlvbl9hZnRlclF1ZXJ5KGl0ZW0sIGNvbnRleHQpIHsKICBsZXQgaG9va0NvbnRleHQgPSBjb250ZXh0OyAgLy8gc2VlIGJlbG93CgogIC8vIHNvbWUgY2hhbmdlcyB0byB0aGUgcmVjZWl2ZWQgaXRlbQogIGl0ZW0uZnVsbF9uYW1lID0gaXRlbS5maXJzdF9uYW1lICsgIiAiICsgaXRlbS5sYXN0X25hbWU7CgogIHJldHVybiBpdGVtOwp9CgovKgogKiBob29rQ29udGV4dDoKICoKICogewogKiAgICJjb2xsZWN0aW9uTmFtZSI6ICJteUNvbGxlY3Rpb24iLAogKiAgICJ1c2VySWQiOiAgICAgICAgICJmNDVqZjhkMi1ncmtqLTJvcGQtNG92ay05cmZqNHdvNXR2ajMiLAogKiAgICJ1c2VyUm9sZSI6ICAgICAgICJzaXRlT3duZXIiCiAqIH0KICovCg==
// 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( )

afterRemove( )

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

export function <collectionName>_afterRemove(item: Object,
  context: HookContext): Promise<Object>

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().

Parameters

item Object The item that was removed.
context HookContext Contextual information about the hook.

Return Value

Returns a Promise

On fulfillment Object The item to return to remove() instead of the deleted item.
On rejection Error 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

Ly8gSW4gZGF0YS5qcwoKZXhwb3J0IGZ1bmN0aW9uIG15Q29sbGVjdGlvbl9hZnRlclJlbW92ZShpdGVtLCBjb250ZXh0KSB7CiAgbGV0IGhvb2tDb250ZXh0ID0gY29udGV4dDsgIC8vIHNlZSBiZWxvdwoKICAvLyBzb21lIGNoYW5nZXMgdG8gdGhlIHJlbW92ZWQgaXRlbQoKICByZXR1cm4gaXRlbTsKfQoKLyoKICogaG9va0NvbnRleHQ6CiAqCiAqIHsKICogICAiY29sbGVjdGlvbk5hbWUiOiAibXlDb2xsZWN0aW9uIiwKICogICAidXNlcklkIjogICAgICAgICAiZjQ1amY4ZDItZ3Jrai0yb3BkLTRvdmstOXJmajR3bzV0dmozIiwKICogICAidXNlclJvbGUiOiAgICAgICAic2l0ZU93bmVyIgogKiB9CiAqLwo=
// 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

Ly8gSW4gZGF0YS5qcwoKZXhwb3J0IGZ1bmN0aW9uIG15Q29sbGVjdGlvbl9hZnRlclVwZGF0ZShpdGVtLCBjb250ZXh0KSB7CiAgbGV0IGhvb2tDb250ZXh0ID0gY29udGV4dDsgIC8vIHNlZSBiZWxvdwoKICAvLyBzb21lIGNoYW5nZXMgdG8gdGhlIHJlbW92ZWQgaXRlbQogIGl0ZW0uZnVsbF9uYW1lID0gaXRlbS5maXJzdF9uYW1lICsgIiAiICsgaXRlbS5sYXN0X25hbWU7CgogIHJldHVybiBpdGVtOwp9CgovKgogKiBob29rQ29udGV4dDoKICoKICogewogKiAgICJjb2xsZWN0aW9uTmFtZSI6ICJteUNvbGxlY3Rpb24iLAogKiAgICJ1c2VySWQiOiAgICAgICAgICJmNDVqZjhkMi1ncmtqLTJvcGQtNG92ay05cmZqNHdvNXR2ajMiLAogKiAgICJ1c2VyUm9sZSI6ICAgICAgICJzaXRlT3duZXIiCiAqIH0KICovCg==
// 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( )

afterUpdate( )

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

export function <collectionName>_afterUpdate(item: Object,
  context: HookContext): Promise<Object>

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().

Parameters

item Object The updated item.
context HookContext Contextual information about the hook.

Return Value

Returns a Promise

On fulfillment Object The item to return to update() instead of the updated item.
On rejection Error 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

Ly8gSW4gZGF0YS5qcwoKZXhwb3J0IGZ1bmN0aW9uIG15Q29sbGVjdGlvbl9hZnRlclVwZGF0ZShpdGVtLCBjb250ZXh0KSB7CiAgbGV0IGhvb2tDb250ZXh0ID0gY29udGV4dDsgIC8vIHNlZSBiZWxvdwoKICAvLyBzb21lIGNoYW5nZXMgdG8gdGhlIHJlY2VpdmVkIGl0ZW0KCiAgcmV0dXJuIGl0ZW07Cn0KCi8qCiAqIGhvb2tDb250ZXh0OgogKgogKiB7CiAqICAgImNvbGxlY3Rpb25OYW1lIjogIm15Q29sbGVjdGlvbiIsCiAqICAgInVzZXJJZCI6ICAgICAgICAgImY0NWpmOGQyLWdya2otMm9wZC00b3ZrLTlyZmo0d281dHZqMyIsCiAqICAgInVzZXJSb2xlIjogICAgICAgInNpdGVPd25lciIKICogfQogKi8K
// 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

Ly8gSW4gZGF0YS5qcwoKZXhwb3J0IGZ1bmN0aW9uIG15Q29sbGVjdGlvbl9hZnRlclVwZGF0ZShpdGVtLCBjb250ZXh0KSB7CiAgbGV0IGhvb2tDb250ZXh0ID0gY29udGV4dDsgIC8vIHNlZSBiZWxvdwoKICAvLyBzb21lIGNoYW5nZXMgdG8gdGhlIHJlY2VpdmVkIGl0ZW0KICBpdGVtLmZ1bGxfbmFtZSA9IGl0ZW0uZmlyc3RfbmFtZSArICIgIiArIGl0ZW0ubGFzdF9uYW1lOwoKICByZXR1cm4gaXRlbTsKfQoKLyoKICogaG9va0NvbnRleHQ6CiAqCiAqIHsKICogICAiY29sbGVjdGlvbk5hbWUiOiAibXlDb2xsZWN0aW9uIiwKICogICAidXNlcklkIjogICAgICAgICAiZjQ1amY4ZDItZ3Jrai0yb3BkLTRvdmstOXJmajR3bzV0dmozIiwKICogICAidXNlclJvbGUiOiAgICAgICAic2l0ZU93bmVyIgogKiB9CiAqLwo=
// 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( )

beforeCount( )

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

export function <collectionName>_beforeCount(query: WixDataQuery,
  context: HookContext): Promise<WixDataQuery>

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().

Parameters

query WixDataQuery The original query as defined by count().
context HookContext Contextual information about the hook.

Return Value

Returns a Promise

On fulfillment WixDataQuery The query to be used for the count() operation instead of the original query.
On rejection Error 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

Ly8gSW4gZGF0YS5qcwoKZXhwb3J0IGZ1bmN0aW9uIG15Q29sbGVjdGlvbl9iZWZvcmVDb3VudChxdWVyeSwgY29udGV4dCkgewogIGxldCBob29rQ29udGV4dCA9IGNvbnRleHQ7ICAvLyBzZWUgYmVsb3cKCiAgLy8gc29tZSBjaGFuZ2UgdG8gdGhlIHJlY2VpdmVkIHF1ZXJ5CgogIHJldHVybiBuZXdRdWVyeTsKfQoKLyoKICogaG9va0NvbnRleHQ6CiAqCiAqIHsKICogICAiY29sbGVjdGlvbk5hbWUiOiAibXlDb2xsZWN0aW9uIiwKICogICAidXNlcklkIjogICAgICAgICAiZjQ1amY4ZDItZ3Jrai0yb3BkLTRvdmstOXJmajR3bzV0dmozIiwKICogICAidXNlclJvbGUiOiAgICAgICAic2l0ZU93bmVyIgogKiB9CiAqLwo=
// 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

Ly8gSW4gZGF0YS5qcwoKZXhwb3J0IGZ1bmN0aW9uIG15Q29sbGVjdGlvbl9iZWZvcmVDb3VudChxdWVyeSwgY29udGV4dCkgewogIGxldCBob29rQ29udGV4dCA9IGNvbnRleHQ7ICAvLyBzZWUgYmVsb3cKCiAgLy8gc29tZSBjaGFuZ2UgdG8gdGhlIHJlY2VpdmVkIHF1ZXJ5CiAgbGV0IG5ld1F1ZXJ5ID0gcXVlcnkuZXEoInN0YXR1cyIsICJhY3RpdmUiKTsKCiAgcmV0dXJuIG5ld1F1ZXJ5Owp9CgovKgogKiBob29rQ29udGV4dDoKICoKICogewogKiAgICJjb2xsZWN0aW9uTmFtZSI6ICJteUNvbGxlY3Rpb24iLAogKiAgICJ1c2VySWQiOiAgICAgICAgICJmNDVqZjhkMi1ncmtqLTJvcGQtNG92ay05cmZqNHdvNXR2ajMiLAogKiAgICJ1c2VyUm9sZSI6ICAgICAgICJzaXRlT3duZXIiCiAqIH0KICovCg==
// 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( )

beforeGet( )

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

export function <collectionName>_beforeGet(itemId: string,
  context: HookContext): Promise<string>

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().

Parameters

itemId String The ID of the original item to be retrieved.
context HookContext Contextual information about the hook.

Return Value

Returns a Promise

On fulfillment String The ID to be used for the get() operation instead of the original itemId specified by the caller.
On rejection Error 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

Ly8gSW4gZGF0YS5qcwoKZXhwb3J0IGZ1bmN0aW9uIG15Q29sbGVjdGlvbl9iZWZvcmVHZXQoaXRlbUlkLCBjb250ZXh0KSB7CiAgbGV0IGhvb2tDb250ZXh0ID0gY29udGV4dDsgIC8vIHNlZSBiZWxvdwoKICAvLyBjaGFuZ2UgdGhlIGl0ZW0gdG8gZ2V0CgogIHJldHVybiBuZXdJdGVtSWQ7Cn0KCi8qCiAqIGhvb2tDb250ZXh0OgogKgogKiB7CiAqICAgImNvbGxlY3Rpb25OYW1lIjogIm15Q29sbGVjdGlvbiIsCiAqICAgInVzZXJJZCI6ICAgICAgICAgImY0NWpmOGQyLWdya2otMm9wZC00b3ZrLTlyZmo0d281dHZqMyIsCiAqICAgInVzZXJSb2xlIjogICAgICAgInNpdGVPd25lciIKICogfQogKi8K
// 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

Ly8gSW4gZGF0YS5qcwoKZXhwb3J0IGZ1bmN0aW9uIG15Q29sbGVjdGlvbl9iZWZvcmVHZXQoaXRlbUlkLCBjb250ZXh0KSB7CiAgbGV0IGhvb2tDb250ZXh0ID0gY29udGV4dDsgIC8vIHNlZSBiZWxvdwoKICAvLyBjaGFuZ2UgdGhlIGl0ZW0gdG8gZ2V0CiAgbGV0IG5ld0l0ZW1JZCA9ICIxMjM0IjsKCiAgcmV0dXJuIG5ld0l0ZW1JZDsKfQoKLyoKICogaG9va0NvbnRleHQ6CiAqCiAqIHsKICogICAiY29sbGVjdGlvbk5hbWUiOiAibXlDb2xsZWN0aW9uIiwKICogICAidXNlcklkIjogICAgICAgICAiZjQ1amY4ZDItZ3Jrai0yb3BkLTRvdmstOXJmajR3bzV0dmozIiwKICogICAidXNlclJvbGUiOiAgICAgICAic2l0ZU93bmVyIgogKiB9CiAqLwo=
// 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( )

beforeInsert( )

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

export function <collectionName>_beforeInsert(item: Object,
  context: HookContext): Promise<Object>

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().

Parameters

item Object The original item to be inserted.
context HookContext Contextual information about the hook.

Return Value

Returns a Promise

On fulfillment Object The item to be inserted instead of the original item specified by the caller.
On rejection Error 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

Ly8gSW4gZGF0YS5qcwoKZXhwb3J0IGZ1bmN0aW9uIG15Q29sbGVjdGlvbl9iZWZvcmVJbnNlcnQoaXRlbSwgY29udGV4dCkgewogIGxldCBob29rQ29udGV4dCA9IGNvbnRleHQ7ICAvLyBzZWUgYmVsb3cKCiAgLy8gc29tZSBjaGFuZ2UgdG8gdGhlIHJlY2VpdmVkIGl0ZW0KCiAgcmV0dXJuIGl0ZW07Cn0KCi8qCiAqIGhvb2tDb250ZXh0OgogKgogKiB7CiAqICAgImNvbGxlY3Rpb25OYW1lIjogIm15Q29sbGVjdGlvbiIsCiAqICAgInVzZXJJZCI6ICAgICAgICAgImY0NWpmOGQyLWdya2otMm9wZC00b3ZrLTlyZmo0d281dHZqMyIsCiAqICAgInVzZXJSb2xlIjogICAgICAgInNpdGVPd25lciIKICogfQogKi8K
// 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

Ly8gSW4gZGF0YS5qcwoKZXhwb3J0IGZ1bmN0aW9uIG15Q29sbGVjdGlvbl9iZWZvcmVJbnNlcnQoaXRlbSwgY29udGV4dCkgewogIGxldCBob29rQ29udGV4dCA9IGNvbnRleHQ7ICAvLyBzZWUgYmVsb3cKCiAgLy8gc29tZSBjaGFuZ2UgdG8gdGhlIHJlY2VpdmVkIGl0ZW0KICBpdGVtLnRpdGxlID0gdG9VcHBlckZpcnN0KGl0ZW0udGl0bGUpOwogIGl0ZW0uZmlyc3RfbmFtZSA9IHRvVXBwZXJGaXJzdChpdGVtLmZpcnN0X25hbWUpOwogIGl0ZW0ubGFzdF9uYW1lID0gdG9VcHBlckZpcnN0KGl0ZW0ubGFzdF9uYW1lKTsKCiAgcmV0dXJuIGl0ZW07Cn0KCmZ1bmN0aW9uIHRvVXBwZXJGaXJzdChzKSB7CiAgcmV0dXJuIHMuY2hhckF0KDApLnRvVXBwZXJDYXNlKCkgKyBzLnNsaWNlKDEpOwp9CgovKgogKiBob29rQ29udGV4dDoKICoKICogewogKiAgICJjb2xsZWN0aW9uTmFtZSI6ICJteUNvbGxlY3Rpb24iLAogKiAgICJ1c2VySWQiOiAgICAgICAgICJmNDVqZjhkMi1ncmtqLTJvcGQtNG92ay05cmZqNHdvNXR2ajMiLAogKiAgICJ1c2VyUm9sZSI6ICAgICAgICJzaXRlT3duZXIiCiAqIH0KICovCg==
// 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( )

beforeQuery( )

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

export function <collectionName>_beforeQuery(query: WixDataQuery,
  context: HookContext): Promise<WixDataQuery>

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().

Parameters

query WixDataQuery The original query as specified by the caller.
context HookContext Contextual information about the hook.

Return Value

Returns a Promise

On fulfillment WixDataQuery The query to use instead of the original query specified by the caller.
On rejection Error 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

Ly8gSW4gZGF0YS5qcwoKZXhwb3J0IGZ1bmN0aW9uIG15Q29sbGVjdGlvbl9iZWZvcmVRdWVyeShxdWVyeSwgY29udGV4dCkgewogIGxldCBob29rQ29udGV4dCA9IGNvbnRleHQ7ICAvLyBzZWUgYmVsb3cKCiAgLy8gc29tZSBjaGFuZ2UgdG8gdGhlIHJlY2VpdmVkIHF1ZXJ5CgogIHJldHVybiBuZXdRdWVyeTsKfQoKLyoKICogaG9va0NvbnRleHQ6CiAqCiAqIHsKICogICAiY29sbGVjdGlvbk5hbWUiOiAibXlDb2xsZWN0aW9uIiwKICogICAidXNlcklkIjogICAgICAgICAiZjQ1amY4ZDItZ3Jrai0yb3BkLTRvdmstOXJmajR3bzV0dmozIiwKICogICAidXNlclJvbGUiOiAgICAgICAic2l0ZU93bmVyIgogKiB9CiAqLwo=
// 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

Ly8gSW4gZGF0YS5qcwoKZXhwb3J0IGZ1bmN0aW9uIG15Q29sbGVjdGlvbl9iZWZvcmVRdWVyeShxdWVyeSwgY29udGV4dCkgewogIGxldCBob29rQ29udGV4dCA9IGNvbnRleHQ7ICAvLyBzZWUgYmVsb3cKCiAgLy8gc29tZSBjaGFuZ2UgdG8gdGhlIHJlY2VpdmVkIHF1ZXJ5CiAgbGV0IG5ld1F1ZXJ5ID0gcXVlcnkuZXEoInN0YXR1cyIsICJhY3RpdmUiKTsKCiAgcmV0dXJuIG5ld1F1ZXJ5Owp9CgovKgogKiBob29rQ29udGV4dDoKICoKICogewogKiAgICJjb2xsZWN0aW9uTmFtZSI6ICJteUNvbGxlY3Rpb24iLAogKiAgICJ1c2VySWQiOiAgICAgICAgICJmNDVqZjhkMi1ncmtqLTJvcGQtNG92ay05cmZqNHdvNXR2ajMiLAogKiAgICJ1c2VyUm9sZSI6ICAgICAgICJzaXRlT3duZXIiCiAqIH0KICovCg==
// 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( )

beforeRemove( )

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

export function <collectionName>_beforeRemove(itemId: string,
  context: HookContext): Promise<string>

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().

Parameters

itemId String The ID of the original item to be removed.
context HookContext Contextual information about the hook.

Return Value

Returns a Promise

On fulfillment String The ID to be used for the remove() instead of the original itemId specified by the caller..
On rejection Error 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

Ly8gSW4gZGF0YS5qcwoKZXhwb3J0IGZ1bmN0aW9uIG15Q29sbGVjdGlvbl9iZWZvcmVSZW1vdmUoaXRlbUlkLCBjb250ZXh0KSB7CiAgbGV0IGhvb2tDb250ZXh0ID0gY29udGV4dDsgIC8vIHNlZSBiZWxvdwoKICAvLyBjaGFuZ2UgdG8gdGhlIGl0ZW0gdG8gcmVtb3ZlCgogIHJldHVybiBuZXdJdGVtSWQ7Cn0KCi8qCiAqIGhvb2tDb250ZXh0OgogKgogKiB7CiAqICAgImNvbGxlY3Rpb25OYW1lIjogIm15Q29sbGVjdGlvbiIsCiAqICAgInVzZXJJZCI6ICAgICAgICAgImY0NWpmOGQyLWdya2otMm9wZC00b3ZrLTlyZmo0d281dHZqMyIsCiAqICAgInVzZXJSb2xlIjogICAgICAgInNpdGVPd25lciIKICogfQogKi8K
// 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

Ly8gSW4gZGF0YS5qcwoKZXhwb3J0IGZ1bmN0aW9uIG15Q29sbGVjdGlvbl9iZWZvcmVSZW1vdmUoaXRlbUlkLCBjb250ZXh0KSB7CiAgbGV0IGhvb2tDb250ZXh0ID0gY29udGV4dDsgIC8vIHNlZSBiZWxvdwoKICAvLyBjaGFuZ2UgdG8gdGhlIGl0ZW0gdG8gcmVtb3ZlCiAgbGV0IG5ld0l0ZW1JZCA9ICIxMjM0IjsKCiAgcmV0dXJuIG5ld0l0ZW1JZDsKfQoKLyoKICogaG9va0NvbnRleHQ6CiAqCiAqIHsKICogICAiY29sbGVjdGlvbk5hbWUiOiAibXlDb2xsZWN0aW9uIiwKICogICAidXNlcklkIjogICAgICAgICAiZjQ1amY4ZDItZ3Jrai0yb3BkLTRvdmstOXJmajR3bzV0dmozIiwKICogICAidXNlclJvbGUiOiAgICAgICAic2l0ZU93bmVyIgogKiB9CiAqLwo=
// 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( )

beforeUpdate( )

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

export function <collectionName>_beforeUpdate(item: Object,
  context: HookContext): Promise<Object>

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().

Parameters

item Object The original item to be updated.
context HookContext Contextual information about the hook.

Return Value

Returns a Promise

On fulfillment Object The item to be updated instead of the original item specified by the caller.
On rejection Error 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

Ly8gSW4gZGF0YS5qcwoKZXhwb3J0IGZ1bmN0aW9uIG15Q29sbGVjdGlvbl9iZWZvcmVVcGRhdGUoaXRlbSwgY29udGV4dCkgewogIGxldCBob29rQ29udGV4dCA9IGNvbnRleHQ7ICAvLyBzZWUgYmVsb3cKCiAgLy8gc29tZSBjaGFuZ2UgdG8gdGhlIHJlY2VpdmVkIGl0ZW0KCiAgcmV0dXJuIGl0ZW07Cn0KCi8qCiAqIGhvb2tDb250ZXh0OgogKgogKiB7CiAqICAgImNvbGxlY3Rpb25OYW1lIjogIm15Q29sbGVjdGlvbiIsCiAqICAgInVzZXJJZCI6ICAgICAgICAgImY0NWpmOGQyLWdya2otMm9wZC00b3ZrLTlyZmo0d281dHZqMyIsCiAqICAgInVzZXJSb2xlIjogICAgICAgInNpdGVPd25lciIKICogfQogKi8K
// 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

Ly8gSW4gZGF0YS5qcwoKZXhwb3J0IGZ1bmN0aW9uIG15Q29sbGVjdGlvbl9iZWZvcmVVcGRhdGUoaXRlbSwgY29udGV4dCkgewogIGxldCBob29rQ29udGV4dCA9IGNvbnRleHQ7ICAvLyBzZWUgYmVsb3cKCiAgLy8gc29tZSBjaGFuZ2UgdG8gdGhlIHJlY2VpdmVkIGl0ZW0KICBpdGVtLnRpdGxlID0gdG9VcHBlckZpcnN0KGl0ZW0udGl0bGUpOwogIGl0ZW0uZmlyc3RfbmFtZSA9IHRvVXBwZXJGaXJzdChpdGVtLmZpcnN0X25hbWUpOwogIGl0ZW0ubGFzdF9uYW1lID0gdG9VcHBlckZpcnN0KGl0ZW0ubGFzdF9uYW1lKTsKCiAgcmV0dXJuIGl0ZW07Cn0KCmZ1bmN0aW9uIHRvVXBwZXJGaXJzdChzKSB7CiAgcmV0dXJuIHMuY2hhckF0KDApLnRvVXBwZXJDYXNlKCkgKyBzLnNsaWNlKDEpOwp9CgovKgogKiBob29rQ29udGV4dDoKICoKICogewogKiAgICJjb2xsZWN0aW9uTmFtZSI6ICJteUNvbGxlY3Rpb24iLAogKiAgICJ1c2VySWQiOiAgICAgICAgICJmNDVqZjhkMi1ncmtqLTJvcGQtNG92ay05cmZqNHdvNXR2ajMiLAogKiAgICJ1c2VyUm9sZSI6ICAgICAgICJzaXRlT3duZXIiCiAqIH0KICovCg==
// 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( )

onFailure( )

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

export function <collectionName>_onFailure(error: Error,
  context: HookContext): Promise<Object>

Description

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

Parameters

error Error The error that caused the failure.
context HookContext Contextual information about the hook.

Return Value

Returns a Promise

On fulfillment Object Returning a fulfilled promise will result in a fulfilled data operation with the provided result.
On rejection Error 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

Ly8gSW4gZGF0YS5qcwoKZXhwb3J0IGZ1bmN0aW9uIG15Q29sbGVjdGlvbl9vbkZhaWx1cmUoZXJyb3IsIGNvbnRleHQpIHsKICBsZXQgaG9va0Vycm9yID0gZXJyb3I7ICAvLyBzZWUgYmVsb3cKCiAgLy8gaGFuZGxlIGVycm9yCgogIHJldHVybiByZXQ7Cn0KCi8qCiAqIGhvb2tFcnJvcjoKICoKICogewogKiAgICJtZXNzYWdlIjogIkFuIGl0ZW0gd2l0aCBfaWQgWzEyMzRdIGFscmVhZHkgZXhpc3RzLiIsCiAqICAgImNvZGUiOiAgICAtNDA5CiAqIH0KICovCg==
// 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

HookContext

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

Properties

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.