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 Management System (CMS).
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.
Note: This feature is not yet supported in Wix Blocks.
Code for the hooks is written in the data.js file, which resides in the Backend section of your site. Hook functions are defined using the following pattern:
export function <collectionName>_<hookName>(<parameters>) { }
You can add these functions to the data.js file by writing them yourself, or by generating templates using the Velo sidebar.
To add a hook to a collection from the sidebar:
A hook that is triggered after a count()
operation.
The afterCount()
hook runs when:
count()
function is called.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.
function afterCount(
count: number,
context: HookContext,
): Promise<number> | number;
The number of items the count operation has found.
Contextual information about the hook.
// In data.js
export function myCollection_afterCount(count, context) {
let hookContext = context; // see below
// some change to the received count
return count;
}
/*
* hookContext:
*
* {
* "collectionName": "myCollection",
* "userId": "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3",
* "userRole": "siteOwner"
* }
*/
A hook that is triggered after a get()
operation.
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.
function afterGet(item: object, context: HookContext): Promise<object> | object;
The item that was retrieved from the collection.
Contextual information about the hook.
// 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"
* }
*/
A hook that is triggered after an insert()
operation.
The afterInsert()
hook runs when:
insert()
function is called.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()
.
function afterInsert(
item: object,
context: HookContext,
): Promise<object> | object;
The item that was inserted.
Contextual information about the hook.
// 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"
* }
*/
A hook that is triggered after a find
operation, for each of the items in the query results.
The afterQuery()
hook runs when:
find
function is called.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.
Note:
We recommend implementing afterQuery()
with in-memory operations only. Don't use network calls such as REST API requests
or other wix-data operations, as these can lead to timeouts and issues loading collection data.
function afterQuery(
item: object,
context: HookContext,
): Promise<object> | object;
One of the items of the query result. The hook is called for each item in the results.
Contextual information about the hook.
// 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"
* }
*/
A hook that is triggered after a remove()
operation.
The afterRemove()
hook runs when:
remove()
function is called.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()
.
function afterRemove(
item: object,
context: HookContext,
): Promise<object> | object;
The item that was removed.
Contextual information about the hook.
// 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"
* }
*/
A hook that is triggered after an update()
operation.
The afterUpdate()
hook runs when:
update()
function is called.Note: When scheduling an item's visibility change, the hook is triggered when the change is scheduled, not when it takes effect.
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()
.
function afterUpdate(
item: object,
context: UpdateHookContext,
): Promise<object> | object;
The updated item.
Contextual information about the hook.
// 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"
* }
*/
A hook that is triggered before a count()
operation.
The beforeCount()
hook runs when:
count()
function is called.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()
.
function beforeCount(
query: WixDataQuery,
context: HookContext,
): Promise<WixDataQuery> | WixDataQuery;
The original query as defined by count()
.
Contextual information about the hook.
// In data.js
export function myCollection_beforeCount(query, context) {
let hookContext = context; // see below
// some change to the received query
return query;
}
/*
* hookContext:
*
* {
* "collectionName": "myCollection",
* "userId": "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3",
* "userRole": "siteOwner"
* }
*/
A hook that is triggered before a get()
operation.
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()
.
function beforeGet(
itemId: string,
context: HookContext,
): Promise<string> | string;
The ID of the original item to be retrieved.
Contextual information about the hook.
// In data.js
export function myCollection_beforeGet(itemId, context) {
let hookContext = context; // see below
// change the item to get
return itemId;
}
/*
* hookContext:
*
* {
* "collectionName": "myCollection",
* "userId": "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3",
* "userRole": "siteOwner"
* }
*/
A hook that is triggered before an insert()
operation.
The beforeInsert()
hook runs when:
insert()
function is called.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()
.
function beforeInsert(
item: object,
context: HookContext,
): Promise<object> | object;
The original item to be inserted.
Contextual information about the hook.
// 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"
* }
*/
A hook that is triggered before a find()
operation.
The beforeQuery()
hook runs when:
find
function is called.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()
.
function beforeQuery(
query: WixDataQuery,
context: HookContext,
): Promise<WixDataQuery> | WixDataQuery;
The original query as specified by the caller.
Contextual information about the hook.
// In data.js
export function myCollection_beforeQuery(query, context) {
let hookContext = context; // see below
// some change to the received query
return query;
}
/*
* hookContext:
*
* {
* "collectionName": "myCollection",
* "userId": "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3",
* "userRole": "siteOwner"
* }
*/
A hook that is called before a remove()
operation.
The beforeRemove()
hook runs when:
remove()
function is called.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()
.
function beforeRemove(
itemId: string,
context: UpdateHookContext,
): Promise<string> | string;
The ID of the original item to be removed.
Contextual information about the hook.
// In data.js
export function myCollection_beforeRemove(itemId, context) {
let hookContext = context; // see below
// change to the item to remove
return itemId;
}
/*
* hookContext:
*
* {
* "collectionName": "myCollection",
* "userId": "f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3",
* "userRole": "siteOwner"
* }
*/
A hook that is triggered before an update()
operation.
The beforeUpdate()
hook runs when:
update()
function is called.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()
.
function beforeUpdate(
item: object,
context: UpdateHookContext,
): Promise<object> | object;
The original item to be updated.
Contextual information about the hook.
// 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"
* }
*/
A hook that is triggered on any error or rejected Promise from any of the wix-data operations.
The onFailure()
hook is triggered whenever a wix-data operation or hook returns a
rejected Promise or an error.
function onFailure(error: Error, context: HookContext): Promise<object>;
The error that caused the failure.
Contextual information about the hook.
// 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
* }
*/