From c22c7b3b023dc4e903c304ae9e1acce73ee82712 Mon Sep 17 00:00:00 2001 From: idanlib-wix Date: Mon, 14 Apr 2025 16:35:10 +0300 Subject: [PATCH 1/6] DocWorks for wix-data - 11 changes detected, but 26 issue detected changes: Service DataHooks was removed Service wix-data.Hooks operation afterAggregate has changed return doc Service wix-data.Hooks operation beforeAggregate has changed param context type Service wix-data.Hooks operation beforeAggregate has changed return type Service wix-data.Hooks operation beforeAggregate has changed description Service wix-data.Hooks has a new operation afterDistinct Service wix-data.Hooks has a new operation beforeDistinct Service wix-data operation get has changed description Service wix-data operation query has changed description Service wix-data operation queryReferenced has changed description Service wix-data.WixDataDistinct is new issues: Operation filter has an unknown param type WixDataFilter (distinct.js (44)) Operation eq has an unknown param type * (filterMixin.js (33)) Operation ne has an unknown param type * (filterMixin.js (59)) Operation hasSome has an unknown param type * (filterMixin.js (342)) Operation hasAll has an unknown param type * (filterMixin.js (378)) Operation beforeAggregate is defined two or more times (hooks.js (313, 337)) Operation beforeAggregate has an unknown return type WixDataAggregate (hooks.js (313)) Operation beforeAggregate has an unknown return type WixDataAggregate (hooks.js (313)) Operation beforeDistinct has an unknown return type WixDataDistinct (hooks.js (395)) Operation beforeDistinct has an unknown return type WixDataDistinct (hooks.js (395)) Operation onFailure has an unknown param type Error (hooks.js (608)) Operation truncate has an unknown return type null (data-api.js (451)) Message WixDataBulkRemoveResult has an unknown property type Error (data-api.js (485)) Message WixDataBulkResult has an unknown property type Error (data-api.js (877)) ERROR: The @snippet tag - file 'velo-docs/examples/WixDataDistinct-getFilter.es6' not found. File: distinct.js line: 29 ERROR: The @snippet tag - file 'velo-docs/examples/WixDataDistinct ... --- wix-data/DataHooks.service.json | 3 +- wix-data/wix-data.service.json | 62 +-- wix-data/wix-data/Hooks.service.json | 115 ++++- .../wix-data/WixDataDistinct.service.json | 409 ++++++++++++++++++ 4 files changed, 542 insertions(+), 47 deletions(-) create mode 100644 wix-data/wix-data/WixDataDistinct.service.json diff --git a/wix-data/DataHooks.service.json b/wix-data/DataHooks.service.json index 66417a6874..696308b951 100644 --- a/wix-data/DataHooks.service.json +++ b/wix-data/DataHooks.service.json @@ -1,6 +1,7 @@ { "name": "DataHooks", "mixes": [], - "labels": [], + "labels": + [ "removed" ], "location": { "lineno": 20, "filename": "hooks-standalone.js" }, diff --git a/wix-data/wix-data.service.json b/wix-data/wix-data.service.json index d503f68c25..6f40ed8d54 100644 --- a/wix-data/wix-data.service.json +++ b/wix-data/wix-data.service.json @@ -1,6 +1,7 @@ { "name": "wix-data", "mixes": [], - "labels": [], + "labels": + [ "changed" ], "location": { "lineno": 72, "filename": "data-api.js" }, @@ -152,7 +153,7 @@ { "type": "wix-data.WixDataAggregate", "doc": "An aggregate object." }, "locations": - [ { "lineno": 1069, + [ { "lineno": 1075, "filename": "data-api.js" } ], "docs": { "summary": "Creates an aggregation.", @@ -253,7 +254,7 @@ [ "wix-data.WixDataBulkResult" ] }, "doc": "Fulfilled - The results of the bulk insert.\nRejected - The error that caused the rejection." }, "locations": - [ { "lineno": 883, + [ { "lineno": 889, "filename": "data-api.js" } ], "docs": { "summary": "Adds a number of items to a collection.", @@ -522,7 +523,7 @@ [ "wix-data.WixDataBulkRemoveResult" ] }, "doc": "Fulfilled - The results of the bulk remove.\nRejected - The error that caused the rejection." }, "locations": - [ { "lineno": 490, + [ { "lineno": 495, "filename": "data-api.js" } ], "docs": { "summary": "Removes a number of items from a collection.", @@ -636,7 +637,7 @@ [ "wix-data.WixDataBulkResult" ] }, "doc": "Fulfilled - The results of the bulk save.\nRejected - The error that caused the rejection." }, "locations": - [ { "lineno": 946, + [ { "lineno": 952, "filename": "data-api.js" } ], "docs": { "summary": "Inserts or updates a number of items in a collection.", @@ -904,7 +905,7 @@ [ "wix-data.WixDataBulkResult" ] }, "doc": "Fulfilled - The results of the bulk save.\nRejected - The error that caused the rejection." }, "locations": - [ { "lineno": 1007, + [ { "lineno": 1013, "filename": "data-api.js" } ], "docs": { "summary": "Updates a number of items in a collection.", @@ -1107,7 +1108,7 @@ { "type": "wix-data.WixDataFilter", "doc": "A filter object." }, "locations": - [ { "lineno": 378, + [ { "lineno": 383, "filename": "data-api.js" } ], "docs": { "summary": "Creates a filter to be used with datasets and aggregations.", @@ -1135,7 +1136,8 @@ "extra": { } }, { "name": "get", - "labels": [], + "labels": + [ "changed" ], "nameParams": [], "params": [ { "name": "collectionId", @@ -1177,6 +1179,8 @@ " > **Notes:**", " > - When using the `query()` or `get()` functions or another data retrieval method following a change to your database collection, the data retrieved may not contain your most recent changes. See [Wix Data and Eventual Consistency](https://dev.wix.com/docs/velo/api-reference/wix-data/introduction#api-reference_wix-data_wix-data-and-eventual-consistency) for more information. To solve this problem, you can use the [`setTimeout()`](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous/Timeouts_and_intervals#setTimeout) function to delay retrieving data following any changes to your database collection.", " > - To speed up data retrieval, the results of certain data queries are cached. Learn more about [caching data query results](https://dev.wix.com/docs/develop-websites/articles/databases/wix-data/data-api/about-caching-data-query-results).", + " > - When using the `query()` or `get()` functions or another data retrieval method following a change to your database collection, the data retrieved may not contain your most recent changes. See [WiX Data and Eventual Consistency](https://dev.wix.com/docs/velo/api-reference/wix-data-v2/eventual-consistency) for more information. To solve this problem, you can use the [`setTimeout()`](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous/Timeouts_and_intervals#setTimeout) function to delay retrieving data following any changes to your database collection.", + " > - To speed up data retrieval, the results of certain data requests are cached. Learn more about [caching data query results](https://dev.wix.com/docs/develop-websites/articles/databases/wix-data/data-api/about-caching-data-query-results).", " > - An `itemId` is required to retrieve an item even from a single-item collection." ], "links": [], "examples": @@ -1266,7 +1270,7 @@ [ "Object" ] }, "doc": "Fulfilled - The item that was added.\nRejected - The error that caused the rejection." }, "locations": - [ { "lineno": 248, + [ { "lineno": 250, "filename": "data-api.js" } ], "docs": { "summary": "Adds an item to a collection.", @@ -1554,7 +1558,7 @@ [ "void" ] }, "doc": "Fulfilled - When the references have been inserted.\nRejected - The error that caused the rejection." }, "locations": - [ { "lineno": 737, + [ { "lineno": 743, "filename": "data-api.js" } ], "docs": { "summary": "Inserts a reference in the specified property.", @@ -1638,7 +1642,7 @@ [ "boolean" ] }, "doc": "Fulfilled - Whether the referring item contains a reference to the referenced item or not.\nRejected - The error that caused the rejection." }, "locations": - [ { "lineno": 839, + [ { "lineno": 845, "filename": "data-api.js" } ], "docs": { "summary": "Checks if a reference to the referenced item exists in the specified\n property of the referring item.", @@ -1674,7 +1678,8 @@ "extra": { } }, { "name": "query", - "labels": [], + "labels": + [ "changed" ], "nameParams": [], "params": [ { "name": "collectionId", @@ -1684,7 +1689,7 @@ { "type": "wix-data.WixDataQuery", "doc": "A query object." }, "locations": - [ { "lineno": 310, + [ { "lineno": 312, "filename": "data-api.js" } ], "docs": { "summary": "Creates a query for retrieving items from a database collection.", @@ -1732,7 +1737,10 @@ "", " > **Notes:**", " > - When using the `query()` or `get()` functions or another data retrieval method following a change to your database collection, the data retrieved may not contain your most recent changes. See [Wix Data and Eventual Consistency]https://dev.wix.com/docs/velo/api-reference/wix-data/introduction#api-reference_wix-data_wix-data-and-eventual-consistency) for more information. To solve this problem, you can use the [`setTimeout()`](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous/Timeouts_and_intervals#setTimeout) function to delay retrieving data following any changes to your database collection.", - "> - To speed up data retrieval, the results of certain data queries are cached. Learn more about [caching data query results](https://dev.wix.com/docs/develop-websites/articles/databases/wix-data/data-api/about-caching-data-query-results)." ], + "> - To speed up data retrieval, the results of certain data queries are cached. Learn more about [caching data query results](https://dev.wix.com/docs/develop-websites/articles/databases/wix-data/data-api/about-caching-data-query-results).", + " > **Note:**", + " When using the `query()` or `get()` functions or another data retrieval method following a change to your database collection, the data retrieved may not contain your most recent changes. See [Wix Data and Eventual Consistency](https://dev.wix.com/docs/velo/api-reference/wix-data-v2/eventual-consistency) for more information. To solve this problem, you can use the [`setTimeout()`](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous/Timeouts_and_intervals#setTimeout) function to delay retrieving data following any changes to your database collection.", + " > - To speed up data retrieval, the results of certain data requests are cached. Learn more about [caching data query results](https://dev.wix.com/docs/develop-websites/articles/databases/wix-data/data-api/about-caching-data-query-results)." ], "links": [], "examples": [ { "title": "Build a query", @@ -1927,7 +1935,8 @@ "extra": { } }, { "name": "queryReferenced", - "labels": [], + "labels": + [ "changed" ], "nameParams": [], "params": [ { "name": "collectionId", @@ -1952,7 +1961,7 @@ [ "wix-data.WixDataQueryReferencedResult" ] }, "doc": "Fulfilled - The referenced items.\nRejected - The error that caused the rejection." }, "locations": - [ { "lineno": 687, + [ { "lineno": 692, "filename": "data-api.js" } ], "docs": { "summary": "Gets the full items referenced in the specified property.", @@ -1981,6 +1990,7 @@ " > - Calling the `queryReferenced()` function does not trigger any hooks.", " > - You can only use the `queryReferenced()` function with [multiple-item reference fields](https://support.wix.com/en/article/about-referencing-multiple-items-in-one-field), and not with single-item (regular) reference fields.", " > - The `queryReferenced()` function is not supported for Single Item Collections.", + " > - To speed up data retrieval, the results of certain data requests are cached. Learn more about [caching data query results](https://dev.wix.com/docs/develop-websites/articles/databases/wix-data/data-api/about-caching-data-query-results).", "", " For a discussion of when to use the similar [`include()`](https://dev.wix.com/docs/velo/api-reference/wix-data/wix-data-query/include)", " function and when to use `queryReferenced()`, see [Querying Items that Reference Other Items](https://support.wix.com/en/article/including-referenced-data-when-filtering)." ], @@ -2078,7 +2088,7 @@ [ "Object" ] }, "doc": "Fulfilled - The removed item, or `null` if the item was not found.\nRejected - The error that caused the rejection." }, "locations": - [ { "lineno": 406, + [ { "lineno": 411, "filename": "data-api.js" } ], "docs": { "summary": "Removes an item from a collection.", @@ -2215,7 +2225,7 @@ [ "void" ] }, "doc": "Fulfilled - When the references have been removed.\nRejected - The error that caused the rejection." }, "locations": - [ { "lineno": 806, + [ { "lineno": 812, "filename": "data-api.js" } ], "docs": { "summary": "Removes a reference from the specified property.", @@ -2303,7 +2313,7 @@ [ "void" ] }, "doc": "Fulfilled - When the references have been inserted.\nRejected - The error that caused the rejection." }, "locations": - [ { "lineno": 772, + [ { "lineno": 778, "filename": "data-api.js" } ], "docs": { "summary": "Replaces current references with references in the specified property.", @@ -2375,7 +2385,7 @@ [ "Object" ] }, "doc": "Fulfilled - The item that was either inserted or updated, depending on whether it previously existed in the collection.\nRejected - The error that caused the rejection." }, "locations": - [ { "lineno": 530, + [ { "lineno": 535, "filename": "data-api.js" } ], "docs": { "summary": "Inserts or updates an item in a collection.", @@ -2611,7 +2621,7 @@ { "type": "wix-data.WixDataSort", "doc": "A sort object." }, "locations": - [ { "lineno": 392, + [ { "lineno": 397, "filename": "data-api.js" } ], "docs": { "summary": "Creates a sort to be used with the dataset `setSort()` function.", @@ -2656,7 +2666,7 @@ [ "null" ] }, "doc": "Fulfilled - When the items have been removed.\nRejected - The error that caused the rejection." }, "locations": - [ { "lineno": 446, + [ { "lineno": 451, "filename": "data-api.js" } ], "docs": { "summary": "Removes all items from a collection.", @@ -2737,7 +2747,7 @@ [ "Object" ] }, "doc": "Fulfilled - The object that was updated.\nRejected - The error that caused the rejection." }, "locations": - [ { "lineno": 586, + [ { "lineno": 591, "filename": "data-api.js" } ], "docs": { "summary": "Updates an item in a collection.", @@ -3042,7 +3052,7 @@ "messages": [ { "name": "WixDataBulkRemoveResult", "locations": - [ { "lineno": 480, + [ { "lineno": 485, "filename": "data-api.js" } ], "docs": { "summary": "An object returned by the `bulkRemove()` function.", @@ -3074,7 +3084,7 @@ "labels": [] }, { "name": "WixDataBulkResult", "locations": - [ { "lineno": 871, + [ { "lineno": 877, "filename": "data-api.js" } ], "docs": { "summary": "An object returned by Wix Data bulk operations.", @@ -3264,7 +3274,7 @@ "labels": [] }, { "name": "WixDataQueryReferencedOptions", "locations": - [ { "lineno": 654, + [ { "lineno": 659, "filename": "data-api.js" } ], "docs": { "summary": "An object for controlling the order of returned referenced items.", diff --git a/wix-data/wix-data/Hooks.service.json b/wix-data/wix-data/Hooks.service.json index ebff624895..f2b9f6a568 100644 --- a/wix-data/wix-data/Hooks.service.json +++ b/wix-data/wix-data/Hooks.service.json @@ -44,7 +44,8 @@ "properties": [], "operations": [ { "name": "afterAggregate", - "labels": [], + "labels": + [ "changed" ], "nameParams": [], "params": [ { "name": "item", @@ -59,7 +60,7 @@ "typeParams": [ "Object" ] }, "Object" ], - "doc": "The item to return to [`aggregate()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update) to replace the original aggregation result item.\n Returning a rejected promise returns a rejected promise to the caller and triggers the [`onFailure()`](#onFailure) hook without blocking the aggregation operation." }, + "doc": "The item to return to [`aggregate()`](https://dev.wix.com/docs/velo/api-reference/wix-data/aggregate) to replace the original aggregation result item." }, "locations": [ { "lineno": 56, "filename": "hooks.js" } ], @@ -142,7 +143,7 @@ "number" ], "doc": "The count to return to [`count()`](wix-data.WixDataQuery.html#count) instead of the original count.\n Returning a rejected promise will not block the operation, but will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." }, "locations": - [ { "lineno": 79, + [ { "lineno": 78, "filename": "hooks.js" } ], "docs": { "summary": "A hook that is triggered after a `count()` operation.", @@ -216,6 +217,41 @@ { } }, "extra": { } }, + { "name": "afterDistinct", + "labels": + [ "new" ], + "nameParams": [], + "params": + [ { "name": "item", + "type": "Object", + "doc": "The distinct query result item." }, + { "name": "context", + "type": "wix-data.Hooks.HookContext", + "doc": "Contextual information about the hook." } ], + "ret": + { "type": + [ { "name": "Promise", + "typeParams": + [ "Object" ] }, + "Object" ], + "doc": "The item to return to [`distinct()`](https://dev.wix.com/docs/velo/api-reference/wix-data/wix-data-query/distinct) to replace the original distinct query result item." }, + "locations": + [ { "lineno": 109, + "filename": "hooks.js" } ], + "docs": + { "summary": "A hook triggered after a distinct query operation.", + "description": + [ "The `afterDistinct()` hook allows you to modify the results of the distinct query before they are returned to the caller. The hook runs for each item in the `items` array within the [WixDataQueryResult](https://dev.wix.com/docs/velo/api-reference/wix-data/wix-data-query-result/introduction) object, after the distinct query operation finishes and before the [`distinct()`](https://dev.wix.com/docs/velo/api-reference/wix-data/wix-data-query/distinct) method returns.", + "", + "Return an object or a Promise that resolves to an object. If the returned value is of the wrong type, it is ignored.", + "", + "If returning a Promise, the object is used as the result regardless of whether the Promise is fulfilled or rejected. A rejected Promise also triggers the [`onFailure()`](#onFailure) hook, if it has been registered." ], + "links": [], + "examples": [], + "extra": + { } }, + "extra": + { } }, { "name": "afterGet", "labels": [], "nameParams": [], @@ -234,7 +270,7 @@ "Object" ], "doc": "The item to return to [`get()`](wix-data.html#get) instead of the retrieved item.\n 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()`](#onFailure) hook." }, "locations": - [ { "lineno": 110, + [ { "lineno": 131, "filename": "hooks.js" } ], "docs": { "summary": "A hook that is triggered after a `get()` operation.", @@ -327,7 +363,7 @@ "Object" ], "doc": "The item to return to [`insert()`](wix-data.html#insert) instead of the inserted item.\n Returning a rejected promise will not block the operation, but will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." }, "locations": - [ { "lineno": 142, + [ { "lineno": 163, "filename": "hooks.js" } ], "docs": { "summary": "A hook that is triggered after an `insert()` operation.", @@ -425,7 +461,7 @@ "Object" ], "doc": "The item to return to [`find`](wix-data.WixDataQuery.html#find) instead of the item retrieved from the database.\n 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()`](#onFailure) hook." }, "locations": - [ { "lineno": 179, + [ { "lineno": 200, "filename": "hooks.js" } ], "docs": { "summary": "A hook that is triggered after a `find` operation, for each of the items in the query results.", @@ -525,7 +561,7 @@ "Object" ], "doc": "The item to return to [`remove()`](wix-data.html#remove) instead of the deleted item.\n Returning a rejected promise will not block the operation, but will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." }, "locations": - [ { "lineno": 219, + [ { "lineno": 240, "filename": "hooks.js" } ], "docs": { "summary": "A hook that is triggered after a `remove()` operation.", @@ -621,7 +657,7 @@ "Object" ], "doc": "The item to return to [`update()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update) instead of the updated item.\n Returning a rejected promise will not block the operation, but will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." }, "locations": - [ { "lineno": 254, + [ { "lineno": 275, "filename": "hooks.js" } ], "docs": { "summary": "A hook that is triggered after an `update()` operation.", @@ -711,22 +747,24 @@ "type": "wix-data.WixDataAggregate", "doc": "The original `WixDataAggregate` object." }, { "name": "context", - "type": "wix-data.Hooks.UpdateHookContext", + "type": "wix-data.Hooks.HookContext", "doc": "Contextual information about the hook." } ], "ret": { "type": [ { "name": "Promise", "typeParams": - [ "wix-data.WixDataAggregate" ] }, - "wix-data.WixDataAggregate" ], + [ "WixDataAggregate" ] }, + "WixDataAggregate" ], "doc": "The aggregate object to run instead of the original object created by the `aggregate()` method.\n Returning a rejected promise blocks the operation, returns a rejected promise to the caller, and triggers the [`onFailure()`](#onFailure) hook." }, "locations": - [ { "lineno": 292, + [ { "lineno": 313, + "filename": "hooks.js" }, + { "lineno": 337, "filename": "hooks.js" } ], "docs": { "summary": "A hook triggered before an aggregation operation.", "description": - [ "The `beforeAggregate()` hook runs when the [`aggregate()`](https://dev.wix.com/docs/velo/api-reference/wix-data/aggregate) is called, and allows you to modify the [`WixDataAggregate`](https://dev.wix.com/docs/velo/api-reference/wix-data/wix-data-aggregate/introduction) object before the aggregation operation runs. ", + [ "The `beforeAggregate()` hook runs when the [`aggregate()`](https://dev.wix.com/docs/velo/api-reference/wix-data/aggregate) is called, and allows you to modify the [`WixDataAggregate`](https://dev.wix.com/docs/velo/api-reference/wix-data/wix-data-aggregate/introduction) object before the aggregation operation runs.", "", "", " Return a [WixDataAggregate](https://dev.wix.com/docs/velo/api-reference/wix-data/wix-data-aggregate/introduction) object or a Promise that resolves to a [WixDataAggregate](https://dev.wix.com/docs/velo/api-reference/wix-data/wix-data-aggregate/introduction) object. The returned object is the aggregation that runs on the collection instead of the original aggregation created by the [`aggregate()`](https://dev.wix.com/docs/velo/api-reference/wix-data/aggregate) method.", @@ -805,7 +843,7 @@ "wix-data.WixDataQuery" ], "doc": "The `query` to be used for the [`count()`](wix-data.WixDataQuery.html#count) operation instead of the original query.\n Returning a rejected promise will block the operation and will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." }, "locations": - [ { "lineno": 316, + [ { "lineno": 360, "filename": "hooks.js" } ], "docs": { "summary": "A hook that is triggered before a `count()` operation.", @@ -883,6 +921,43 @@ { } }, "extra": { } }, + { "name": "beforeDistinct", + "labels": + [ "new" ], + "nameParams": [], + "params": + [ { "name": "distinctQuery", + "type": "wix-data.WixDataDistinct", + "doc": "The original `WixDataDistinct` object." }, + { "name": "context", + "type": "wix-data.Hooks.HookContext", + "doc": "Contextual information about the hook." } ], + "ret": + { "type": + [ { "name": "Promise", + "typeParams": + [ "WixDataDistinct" ] }, + "WixDataDistinct" ], + "doc": "The distinct query object to run instead of the original object created by the `distinct()` method.\n Returning a rejected promise blocks the operation, returns a rejected promise to the caller, and triggers the [`onFailure()`](#onFailure) hook." }, + "locations": + [ { "lineno": 395, + "filename": "hooks.js" } ], + "docs": + { "summary": "A hook triggered before a distinct query operation.", + "description": + [ "The `beforeDistinct()` hook runs when the [`distinct()`](https://dev.wix.com/docs/velo/api-reference/wix-data/wix-data-query/distinct) is called. It allows you to modify the [`WixDataDistinct`](ADDLINK) object before the distinct query operation runs.", + "", + "Return a [`WixDataDistinct`](ADDLINK) object or a Promise that resolves to a [`WixDataDistinct`](ADDLINK) object. The returned object defines the distinct query operation that runs on the collection instead of the original operation created by the [`distinct()`](https://dev.wix.com/docs/velo/api-reference/wix-data/wix-data-query/distinct) method.", + "", + "If the returned value is of the wrong type, the value is ignored.", + "", + "A rejected Promise blocks the call to [`distinct()`](https://dev.wix.com/docs/velo/api-reference/wix-data/wix-data-query/distinct) and triggers the [`onFailure()`](#onFailure) hook, if it has been registered." ], + "links": [], + "examples": [], + "extra": + { } }, + "extra": + { } }, { "name": "beforeGet", "labels": [], "nameParams": [], @@ -901,7 +976,7 @@ "string" ], "doc": "The ID to be used for the [`get()`](wix-data.html#get) operation instead of the original `itemId` specified by the caller.\n Returning a rejected promise will block the operation and will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." }, "locations": - [ { "lineno": 351, + [ { "lineno": 418, "filename": "hooks.js" } ], "docs": { "summary": "A hook that is triggered before a `get()` operation.", @@ -997,7 +1072,7 @@ "Object" ], "doc": "The item to be inserted instead of the original item specified by the caller.\n Returning a rejected promise will block the operation and will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." }, "locations": - [ { "lineno": 386, + [ { "lineno": 453, "filename": "hooks.js" } ], "docs": { "summary": "A hook that is triggered before an `insert()` operation.", @@ -1130,7 +1205,7 @@ "wix-data.WixDataQuery" ], "doc": "The query to use instead of the original query specified by the caller.\n Returning a rejected promise will block the operation and will return a rejected promise to the operation caller as well as trigger the [`onFailure()`](#onFailure) hook." }, "locations": - [ { "lineno": 425, + [ { "lineno": 492, "filename": "hooks.js" } ], "docs": { "summary": "A hook that is triggered before a `find()` operation.", @@ -1232,7 +1307,7 @@ "string" ], "doc": "The ID to be used for the [`remove()`](wix-data.html#remove) instead of the original `itemId` specified by the caller.\n Returning a rejected promise will block the operation and will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." }, "locations": - [ { "lineno": 466, + [ { "lineno": 533, "filename": "hooks.js" } ], "docs": { "summary": "A hook that is called before a `remove()` operation.", @@ -1331,7 +1406,7 @@ "Object" ], "doc": "The item to be updated instead of the original item specified by the caller.\n Returning a rejected promise will block the operation and will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." }, "locations": - [ { "lineno": 504, + [ { "lineno": 571, "filename": "hooks.js" } ], "docs": { "summary": "A hook that is triggered before an `update()` operation.", @@ -1434,7 +1509,7 @@ [ "Object" ] }, "doc": "Fulfilled - Returning a fulfilled promise will result in a fulfilled data operation with the provided result.\nRejected - Returning a rejected promise will result in returning a rejected promise to the caller of the data operation." }, "locations": - [ { "lineno": 541, + [ { "lineno": 608, "filename": "hooks.js" } ], "docs": { "summary": "A hook that is triggered on any error or rejected Promise from any of the wix-data operations.", diff --git a/wix-data/wix-data/WixDataDistinct.service.json b/wix-data/wix-data/WixDataDistinct.service.json new file mode 100644 index 0000000000..76ddf28599 --- /dev/null +++ b/wix-data/wix-data/WixDataDistinct.service.json @@ -0,0 +1,409 @@ +{ "name": "WixDataDistinct", + "memberOf": "wix-data", + "mixes": + [ "wix-data.WixDataFilter" ], + "labels": + [ "new" ], + "location": + { "lineno": 1, + "filename": "distinct.js" }, + "docs": + { "summary": "Provides functionality for refining a distinct data query.", + "description": + [ "The `WixDataDistinct` methods allow you to run, sort, filter, and control the results of a distinct query.", + "", + "When you run a query with the [`distinct()`](https://dev.wix.com/docs/velo/api-reference/wix-data/wix-data-query/distinct) method, the query only returns distinct items. For example, the following code queries a collection for customers over the age of 20 and logs their last names in ascending order, without duplicates:", + "", + "", + " ```javascript", + " import wixData from 'wix-data';", + "", + " wixData.query(\"customers\")", + " .gt(\"age\", 20)", + " .distinct(\"lastName\")", + " .then((results) => {", + " console.log(results.items);", + " });", + " ```", + "", + " You can then further refine the distinct query by calling `WixDataDistinct` methods in the [`beforeDistinct()`](ADDLINK) hook." ], + "links": [], + "examples": [], + "extra": + { } }, + "properties": [], + "operations": + [ { "name": "ascending", + "labels": [], + "nameParams": [], + "params": + [ { "name": "propertyName", + "type": "string", + "doc": "The properties used in the sort.", + "spread": true } ], + "ret": + { "type": "wix-data.WixDataQuery", + "doc": "A `WixDataQuery` object representing the refined query." }, + "locations": + [ { "lineno": 10, + "filename": "sortMixin.js" } ], + "docs": + { "summary": "Adds a sort to a query or sort, sorting by the specified properties in ascending order.", + "description": + [ "The `ascending()` function refines a `WixDataQuery` or `WixDataSort` to sort in ascending order of", + " the specified properties. If you specify more than one property,", + " `ascending()` sorts the results in ascending order by each property in the", + " order they are listed.", + "", + " You can sort the following types:", + "", + " + Number: Sorts numerically.", + " + Date: Sorts by date and time.", + " + String: Sorts lexicographically, so `\"abc\"` comes after `\"XYZ\"`.", + " + Reference: Compares by the ID of the referenced item as a String.", + "", + "", + " If a property contains a number as a String, that value will be sorted", + " alphabetically and not numerically. Items that do not have a value for the", + " specified sort property are ranked lowest." ], + "links": [], + "examples": + [ { "title": "Add an ascending sort to a query", + "body": + [ "let newQuery = query.ascending(\"last_name\", \"first_name\");" ], + "extra": + { } }, + { "title": "Create a query, add an ascending sort, and run it", + "body": + [ "import wixData from 'wix-data';", + "", + "// ...", + "", + "wixData.query(\"myCollection\")", + " .ascending(\"last_name\", \"first_name\")", + " .find()", + " .then((results) => {", + " if(results.items.length > 0) {", + " let items = results.items;", + " let firstItem = items[0];", + " let totalCount = results.totalCount;", + " let pageSize = results.pageSize;", + " let currentPage = results.currentPage;", + " let totalPages = results.totalPages;", + " let hasNext = results.hasNext();", + " let hasPrev = results.hasPrev();", + " let length = results.length;", + " let query = results.query;", + " } else {", + " // handle case where no matching items found", + " }", + " })", + " .catch((error) => {", + " let errorMsg = error.message;", + " let code = error.code;", + " });" ], + "extra": + { } }, + { "title": "Create a query, add an ascending sort, and run it", + "body": + [ "import wixData from 'wix-data';", + "", + "// ...", + "", + "wixData.query(\"myCollection\")", + " .ascending(\"last_name\", \"first_name\")", + " .eq(\"status\", \"active\")", + " .limit(10)", + " .find()", + " .then((results) => {", + " if(results.items.length > 0) {", + " let items = results.items;", + " let firstItem = items[0];", + " let totalCount = results.totalCount;", + " let pageSize = results.pageSize;", + " let currentPage = results.currentPage;", + " let totalPages = results.totalPages;", + " let hasNext = results.hasNext();", + " let hasPrev = results.hasPrev();", + " let length = results.length;", + " let query = results.query;", + " } else {", + " // handle case where no matching items found", + " }", + " })", + " .catch((error) => {", + " let errorMsg = error.message;", + " let code = error.code;", + " });" ], + "extra": + { } } ], + "extra": + { } }, + "extra": + { } }, + { "name": "descending", + "labels": [], + "nameParams": [], + "params": + [ { "name": "propertyName", + "type": "string", + "doc": "The properties used in the sort.", + "spread": true } ], + "ret": + { "type": "wix-data.WixDataQuery", + "doc": "A `WixDataQuery` object representing the refined query." }, + "locations": + [ { "lineno": 41, + "filename": "sortMixin.js" } ], + "docs": + { "summary": "Adds a sort to a query or sort, sorting by the specified properties in descending order.", + "description": + [ "The `descending()` function refines a `WixDataQuery` or `WixDataSort` to sort in descending order of", + " the specified properties. If you specify more than one property,", + " `descending()` sorts the results in descending order by each property in the", + " order they are listed.", + "", + " You can sort the following types:", + "", + " + Number: Sorts numerically.", + " + Date: Sorts by date and time.", + " + String: Sorts lexicographically, so `\"abc\"` comes before `\"XYZ\"`.", + " + Reference: Compares by the ID of the referenced item as a String.", + "", + "", + " If a property contains a number as a String, that value will be sorted", + " alphabetically and not numerically. Items that do not have a value for the", + " specified sort property are ranked lowest." ], + "links": [], + "examples": + [ { "title": "Add an descending sort to a query", + "body": + [ "let newQuery = query.descending(\"last_name\", \"first_name\");" ], + "extra": + { } }, + { "title": "Create a query, add an descending sort, and run it", + "body": + [ "import wixData from 'wix-data';", + "", + "// ...", + "", + "wixData.query(\"myCollection\")", + " .descending(\"last_name\", \"first_name\")", + " .find()", + " .then((results) => {", + " if(results.items.length > 0) {", + " let items = results.items;", + " let firstItem = items[0];", + " let totalCount = results.totalCount;", + " let pageSize = results.pageSize;", + " let currentPage = results.currentPage;", + " let totalPages = results.totalPages;", + " let hasNext = results.hasNext();", + " let hasPrev = results.hasPrev();", + " let length = results.length;", + " let query = results.query;", + " } else {", + " // handle case where no matching items found", + " }", + " })", + " .catch((error) => {", + " let errorMsg = error.message;", + " let code = error.code;", + " });" ], + "extra": + { } }, + { "title": "Create a query, add an descending sort, and run it", + "body": + [ "import wixData from 'wix-data';", + "", + "// ...", + "", + "wixData.query(\"myCollection\")", + " .descending(\"last_name\", \"first_name\")", + " .eq(\"status\", \"active\")", + " .limit(10)", + " .find()", + " .then((results) => {", + " if(results.items.length > 0) {", + " let items = results.items;", + " let firstItem = items[0];", + " let totalCount = results.totalCount;", + " let pageSize = results.pageSize;", + " let currentPage = results.currentPage;", + " let totalPages = results.totalPages;", + " let hasNext = results.hasNext();", + " let hasPrev = results.hasPrev();", + " let length = results.length;", + " let query = results.query;", + " } else {", + " // handle case where no matching items found", + " }", + " })", + " .catch((error) => {", + " let errorMsg = error.message;", + " let code = error.code;", + " });" ], + "extra": + { } } ], + "extra": + { } }, + "extra": + { } }, + { "name": "filter", + "labels": [], + "nameParams": [], + "params": + [ { "name": "filter", + "type": "WixDataFilter", + "doc": "Filter to refine the distinct query." } ], + "ret": + { "type": + { "name": "Promise", + "typeParams": + [ "wix-data.WixDataDistinct" ] }, + "doc": "Fulfilled - The distinct query object.\nRejected - The errors that caused the rejection." }, + "locations": + [ { "lineno": 44, + "filename": "distinct.js" } ], + "docs": + { "summary": "Sets the filter used to refine the distinct query.", + "description": + [ "The `filter()` method defines the filter used to refine the distinct query. It returns a Promise that resolve to the [`WixDataDistinct`](ADDLINK) query object. The Promise is rejected if `filter()` is called with incorrect permissions or if any of the methods used to refine the query are invalid." ], + "links": [], + "examples": [], + "extra": + { } }, + "extra": + { } }, + { "name": "getFilter", + "labels": [], + "nameParams": [], + "params": [], + "ret": + { "type": + { "name": "Promise", + "typeParams": + [ "wix-data.WixDataFilter" ] }, + "doc": "Fulfilled - The filter used to refine the distinct query.\nRejected - The errors that caused the rejection." }, + "locations": + [ { "lineno": 29, + "filename": "distinct.js" } ], + "docs": + { "summary": "Returns the filter used to refine the distinct query.", + "description": + [ "The `getFilter()` method returns a Promise that resolves to the [`WixDataFilter()`](https://dev.wix.com/docs/sdk/backend-modules/data/items/wix-data-filter/introduction) that was used to refine the distinct query. The Promise is rejected if `getFilter()` is called with incorrect permissions or if any of the methods used to refine the query are invalid." ], + "links": [], + "examples": [], + "extra": + { } }, + "extra": + { } }, + { "name": "getPropertyName", + "labels": [], + "nameParams": [], + "params": [], + "ret": + { "type": + { "name": "Promise", + "typeParams": + [ "string" ] }, + "doc": "Fulfilled - The property used to define the distinct query.\nRejected - The errors that caused the rejection." }, + "locations": + [ { "lineno": 60, + "filename": "distinct.js" } ], + "docs": + { "summary": "Returns the name of the property used to define the distinct query.", + "description": + [ "The `getPropertyName()` method returns a Promise that resolve to the name of the property used to define the distinct query. The Promise is rejected if the method is called with incorrect permissions or if any of the methods used to refine the query are invalid." ], + "links": [], + "examples": [], + "extra": + { } }, + "extra": + { } }, + { "name": "limit", + "labels": [], + "nameParams": [], + "params": + [ { "name": "limit", + "type": "number", + "doc": "Number of items to return, which is also the [`pageSize`](https://dev.wix.com/docs/sdk/backend-modules/data/items/wix-data-result/page-size) of the results object." } ], + "ret": + { "type": "wix-data.WixDataDistinct", + "doc": "A [`WixDataDistinct`](ADDLINK) object representing the refined distinct query." }, + "locations": + [ { "lineno": 91, + "filename": "distinct.js" } ], + "docs": + { "summary": "Limits the number of items the distinct query returns.", + "description": + [ "The `limit()` method defines the number of results a distinct query returns in each page. Only one page of results is retrieved at a time. use the [`next()`](https://dev.wix.com/docs/sdk/backend-modules/data/items/wix-data-result/next) and [`prev()`](https://dev.wix.com/docs/sdk/backend-modules/data/items/wix-data-result/prev) methods to navigate the pages of a query result.", + "", + " By default, `limit` is set to `50`.", + "", + " The maximum value that `limit()` can accept is `1000`.", + "", + " > **Note** : For some [Wix app collections](https://dev.wix.com/docs/develop-websites/articles/databases/wix-data/collections/working-with-wix-app-collections-and-code), the maximum value `limit()` can accept is less than `1000`. For example, the maximum limit for the Wix `Stores/Product` collection is 100." ], + "links": [], + "examples": [], + "extra": + { } }, + "extra": + { } }, + { "name": "propertyName", + "labels": [], + "nameParams": [], + "params": + [ { "name": "newPropertyName", + "type": "string", + "doc": "Property by which to return distinct values, without duplicates." } ], + "ret": + { "type": + { "name": "Promise", + "typeParams": + [ "wix-data.WixDataDistinct" ] }, + "doc": "Fulfilled - The distinct query object.\nRejected - The errors that caused the rejection." }, + "locations": + [ { "lineno": 75, + "filename": "distinct.js" } ], + "docs": + { "summary": "Sets the property name by which to return distinct values.", + "description": + [ "The `propertyName()` method defines the property by which to return distinct values, without duplicates. It returns a Promise that resolves to the [`WixDataDistinct`](ADDLINK) query object. The Promise is rejected if `propertyName()` is called with incorrect permissions or if any of the methods used to refine the query are invalid." ], + "links": [], + "examples": [], + "extra": + { } }, + "extra": + { } }, + { "name": "skip", + "labels": [], + "nameParams": [], + "params": + [ { "name": "skip", + "type": "number", + "doc": "Number of items to skip in before returning the distinct query results." } ], + "ret": + { "type": "wix-data.WixDataDistinct", + "doc": "A `WixDataDistinct` object representing the refined query." }, + "locations": + [ { "lineno": 110, + "filename": "distinct.js" } ], + "docs": + { "summary": "Sets the number of items to skip before returning distinct query results.", + "description": + [ "The `skip()` method defines the number of query results to skip before returning the remaining results.", + "", + " For example, if you query a collection and 50 items match your query, but you set `skip` to 10, the results skip the first 10 items that match and return the 11th through 50th items.", + "", + " By default, `skip` is set to 0." ], + "links": [], + "examples": [], + "extra": + { } }, + "extra": + { } } ], + "callbacks": [], + "messages": [], + "extra": + { } } \ No newline at end of file From 3f46a4f19b5e8d925f3583cf82e792fef3f6f509 Mon Sep 17 00:00:00 2001 From: idanlib-wix Date: Mon, 14 Apr 2025 17:54:18 +0300 Subject: [PATCH 2/6] DocWorks for wix-data - 38 changes detected, but 16 issue detected changes: Service wix-data.Hooks operation afterDistinct.examples has 2 new examples Service wix-data.Hooks operation beforeDistinct.examples has 2 new examples Service wix-data.WixDataDistinct operation ascending param propertyName was removed Service wix-data.WixDataDistinct operation ascending has changed return type Service wix-data.WixDataDistinct operation ascending has changed return doc Service wix-data.WixDataDistinct operation ascending has changed summary Service wix-data.WixDataDistinct operation ascending has changed description Service wix-data.WixDataDistinct operation ascending.examples[0] has changed title Service wix-data.WixDataDistinct operation ascending.examples[0] has changed body Service wix-data.WixDataDistinct operation ascending.examples has 2 examples removed Service wix-data.WixDataDistinct operation descending param propertyName was removed Service wix-data.WixDataDistinct operation descending has changed return type Service wix-data.WixDataDistinct operation descending has changed return doc Service wix-data.WixDataDistinct operation descending has changed summary Service wix-data.WixDataDistinct operation descending has changed description Service wix-data.WixDataDistinct operation descending.examples[0] has changed title Service wix-data.WixDataDistinct operation descending.examples[0] has changed body Service wix-data.WixDataDistinct operation descending.examples has 2 examples removed Service wix-data.WixDataDistinct operation filter has changed return type Service wix-data.WixDataDistinct operation filter has changed return doc Service wix-data.WixDataDistinct operation filter has changed description Service wix-data.WixDataDistinct operation filter.examples has 1 new examples Service wix-data.WixDataDistinct operation getFilter has changed return type Service wix-data.WixDataDistinct operation getFilter has changed return doc Service wix-data.WixDataDistinct operat ... --- wix-data/wix-data.service.json | 12 +- wix-data/wix-data/Hooks.service.json | 37 +- .../wix-data/WixDataDistinct.service.json | 374 +++++++----------- 3 files changed, 181 insertions(+), 242 deletions(-) diff --git a/wix-data/wix-data.service.json b/wix-data/wix-data.service.json index 6f40ed8d54..3fc38b6a08 100644 --- a/wix-data/wix-data.service.json +++ b/wix-data/wix-data.service.json @@ -1,7 +1,6 @@ { "name": "wix-data", "mixes": [], - "labels": - [ "changed" ], + "labels": [], "location": { "lineno": 72, "filename": "data-api.js" }, @@ -1136,8 +1135,7 @@ "extra": { } }, { "name": "get", - "labels": - [ "changed" ], + "labels": [], "nameParams": [], "params": [ { "name": "collectionId", @@ -1678,8 +1676,7 @@ "extra": { } }, { "name": "query", - "labels": - [ "changed" ], + "labels": [], "nameParams": [], "params": [ { "name": "collectionId", @@ -1935,8 +1932,7 @@ "extra": { } }, { "name": "queryReferenced", - "labels": - [ "changed" ], + "labels": [], "nameParams": [], "params": [ { "name": "collectionId", diff --git a/wix-data/wix-data/Hooks.service.json b/wix-data/wix-data/Hooks.service.json index f2b9f6a568..edc2a376c4 100644 --- a/wix-data/wix-data/Hooks.service.json +++ b/wix-data/wix-data/Hooks.service.json @@ -44,8 +44,7 @@ "properties": [], "operations": [ { "name": "afterAggregate", - "labels": - [ "changed" ], + "labels": [], "nameParams": [], "params": [ { "name": "item", @@ -219,7 +218,7 @@ { } }, { "name": "afterDistinct", "labels": - [ "new" ], + [ "changed" ], "nameParams": [], "params": [ { "name": "item", @@ -247,7 +246,18 @@ "", "If returning a Promise, the object is used as the result regardless of whether the Promise is fulfilled or rejected. A rejected Promise also triggers the [`onFailure()`](#onFailure) hook, if it has been registered." ], "links": [], - "examples": [], + "examples": + [ { "title": "An `afterDistinct()` hook", + "body": + [ "// An `afterDistinct()` hook", + "//" ], + "extra": + { } }, + { "title": "Modify the item returned by `distinct()` using an `afterDistinct()` hook", + "body": + [ "// Modify the item returned by `distinct()` using an `afterDistinct()` hook." ], + "extra": + { } } ], "extra": { } }, "extra": @@ -739,8 +749,7 @@ "extra": { } }, { "name": "beforeAggregate", - "labels": - [ "changed" ], + "labels": [], "nameParams": [], "params": [ { "name": "aggregate", @@ -923,7 +932,7 @@ { } }, { "name": "beforeDistinct", "labels": - [ "new" ], + [ "changed" ], "nameParams": [], "params": [ { "name": "distinctQuery", @@ -953,7 +962,19 @@ "", "A rejected Promise blocks the call to [`distinct()`](https://dev.wix.com/docs/velo/api-reference/wix-data/wix-data-query/distinct) and triggers the [`onFailure()`](#onFailure) hook, if it has been registered." ], "links": [], - "examples": [], + "examples": + [ { "title": "A `beforeDistinct` hook", + "body": + [ "// A `beforeDistinct` hook", + "//" ], + "extra": + { } }, + { "title": "Refine the `WixDataDistinct` object", + "body": + [ "// Refine the `WixDataDistinct` object", + "//" ], + "extra": + { } } ], "extra": { } }, "extra": diff --git a/wix-data/wix-data/WixDataDistinct.service.json b/wix-data/wix-data/WixDataDistinct.service.json index 76ddf28599..8b0a28642f 100644 --- a/wix-data/wix-data/WixDataDistinct.service.json +++ b/wix-data/wix-data/WixDataDistinct.service.json @@ -3,7 +3,7 @@ "mixes": [ "wix-data.WixDataFilter" ], "labels": - [ "new" ], + [ "changed" ], "location": { "lineno": 1, "filename": "distinct.js" }, @@ -34,107 +34,28 @@ "properties": [], "operations": [ { "name": "ascending", - "labels": [], + "labels": + [ "changed" ], "nameParams": [], - "params": - [ { "name": "propertyName", - "type": "string", - "doc": "The properties used in the sort.", - "spread": true } ], + "params": [], "ret": - { "type": "wix-data.WixDataQuery", - "doc": "A `WixDataQuery` object representing the refined query." }, + { "type": "wix-data.WixDataDistinct", + "doc": "The distinct query object." }, "locations": - [ { "lineno": 10, + [ { "lineno": 92, + "filename": "distinct.js" }, + { "lineno": 10, "filename": "sortMixin.js" } ], "docs": - { "summary": "Adds a sort to a query or sort, sorting by the specified properties in ascending order.", + { "summary": "Sorts the results of the distinct query in ascending order based on the distinct property name.", "description": - [ "The `ascending()` function refines a `WixDataQuery` or `WixDataSort` to sort in ascending order of", - " the specified properties. If you specify more than one property,", - " `ascending()` sorts the results in ascending order by each property in the", - " order they are listed.", - "", - " You can sort the following types:", - "", - " + Number: Sorts numerically.", - " + Date: Sorts by date and time.", - " + String: Sorts lexicographically, so `\"abc\"` comes after `\"XYZ\"`.", - " + Reference: Compares by the ID of the referenced item as a String.", - "", - "", - " If a property contains a number as a String, that value will be sorted", - " alphabetically and not numerically. Items that do not have a value for the", - " specified sort property are ranked lowest." ], + [ "The `ascending()` method sorts the distinct query in ascending order based on the distinct property name." ], "links": [], "examples": - [ { "title": "Add an ascending sort to a query", + [ { "title": "Sort the results of the distinct query in ascending order", "body": - [ "let newQuery = query.ascending(\"last_name\", \"first_name\");" ], - "extra": - { } }, - { "title": "Create a query, add an ascending sort, and run it", - "body": - [ "import wixData from 'wix-data';", - "", - "// ...", - "", - "wixData.query(\"myCollection\")", - " .ascending(\"last_name\", \"first_name\")", - " .find()", - " .then((results) => {", - " if(results.items.length > 0) {", - " let items = results.items;", - " let firstItem = items[0];", - " let totalCount = results.totalCount;", - " let pageSize = results.pageSize;", - " let currentPage = results.currentPage;", - " let totalPages = results.totalPages;", - " let hasNext = results.hasNext();", - " let hasPrev = results.hasPrev();", - " let length = results.length;", - " let query = results.query;", - " } else {", - " // handle case where no matching items found", - " }", - " })", - " .catch((error) => {", - " let errorMsg = error.message;", - " let code = error.code;", - " });" ], - "extra": - { } }, - { "title": "Create a query, add an ascending sort, and run it", - "body": - [ "import wixData from 'wix-data';", - "", - "// ...", - "", - "wixData.query(\"myCollection\")", - " .ascending(\"last_name\", \"first_name\")", - " .eq(\"status\", \"active\")", - " .limit(10)", - " .find()", - " .then((results) => {", - " if(results.items.length > 0) {", - " let items = results.items;", - " let firstItem = items[0];", - " let totalCount = results.totalCount;", - " let pageSize = results.pageSize;", - " let currentPage = results.currentPage;", - " let totalPages = results.totalPages;", - " let hasNext = results.hasNext();", - " let hasPrev = results.hasPrev();", - " let length = results.length;", - " let query = results.query;", - " } else {", - " // handle case where no matching items found", - " }", - " })", - " .catch((error) => {", - " let errorMsg = error.message;", - " let code = error.code;", - " });" ], + [ "// Sort the results of the distinct query in ascending order", + "//" ], "extra": { } } ], "extra": @@ -142,107 +63,28 @@ "extra": { } }, { "name": "descending", - "labels": [], + "labels": + [ "changed" ], "nameParams": [], - "params": - [ { "name": "propertyName", - "type": "string", - "doc": "The properties used in the sort.", - "spread": true } ], + "params": [], "ret": - { "type": "wix-data.WixDataQuery", - "doc": "A `WixDataQuery` object representing the refined query." }, + { "type": "wix-data.WixDataDistinct", + "doc": "The distinct query object." }, "locations": - [ { "lineno": 41, + [ { "lineno": 116, + "filename": "distinct.js" }, + { "lineno": 41, "filename": "sortMixin.js" } ], "docs": - { "summary": "Adds a sort to a query or sort, sorting by the specified properties in descending order.", + { "summary": "Sorts the results of the distinct query in descending order based on the distinct property name.", "description": - [ "The `descending()` function refines a `WixDataQuery` or `WixDataSort` to sort in descending order of", - " the specified properties. If you specify more than one property,", - " `descending()` sorts the results in descending order by each property in the", - " order they are listed.", - "", - " You can sort the following types:", - "", - " + Number: Sorts numerically.", - " + Date: Sorts by date and time.", - " + String: Sorts lexicographically, so `\"abc\"` comes before `\"XYZ\"`.", - " + Reference: Compares by the ID of the referenced item as a String.", - "", - "", - " If a property contains a number as a String, that value will be sorted", - " alphabetically and not numerically. Items that do not have a value for the", - " specified sort property are ranked lowest." ], + [ "The `descending()` method sorts the distinct query in descending order based on the distinct property name." ], "links": [], "examples": - [ { "title": "Add an descending sort to a query", + [ { "title": "Sort the results of the distinct query in descending order", "body": - [ "let newQuery = query.descending(\"last_name\", \"first_name\");" ], - "extra": - { } }, - { "title": "Create a query, add an descending sort, and run it", - "body": - [ "import wixData from 'wix-data';", - "", - "// ...", - "", - "wixData.query(\"myCollection\")", - " .descending(\"last_name\", \"first_name\")", - " .find()", - " .then((results) => {", - " if(results.items.length > 0) {", - " let items = results.items;", - " let firstItem = items[0];", - " let totalCount = results.totalCount;", - " let pageSize = results.pageSize;", - " let currentPage = results.currentPage;", - " let totalPages = results.totalPages;", - " let hasNext = results.hasNext();", - " let hasPrev = results.hasPrev();", - " let length = results.length;", - " let query = results.query;", - " } else {", - " // handle case where no matching items found", - " }", - " })", - " .catch((error) => {", - " let errorMsg = error.message;", - " let code = error.code;", - " });" ], - "extra": - { } }, - { "title": "Create a query, add an descending sort, and run it", - "body": - [ "import wixData from 'wix-data';", - "", - "// ...", - "", - "wixData.query(\"myCollection\")", - " .descending(\"last_name\", \"first_name\")", - " .eq(\"status\", \"active\")", - " .limit(10)", - " .find()", - " .then((results) => {", - " if(results.items.length > 0) {", - " let items = results.items;", - " let firstItem = items[0];", - " let totalCount = results.totalCount;", - " let pageSize = results.pageSize;", - " let currentPage = results.currentPage;", - " let totalPages = results.totalPages;", - " let hasNext = results.hasNext();", - " let hasPrev = results.hasPrev();", - " let length = results.length;", - " let query = results.query;", - " } else {", - " // handle case where no matching items found", - " }", - " })", - " .catch((error) => {", - " let errorMsg = error.message;", - " let code = error.code;", - " });" ], + [ "// Sort the results of the distinct query in descending order", + "//" ], "extra": { } } ], "extra": @@ -250,79 +92,142 @@ "extra": { } }, { "name": "filter", - "labels": [], + "labels": + [ "changed" ], "nameParams": [], "params": [ { "name": "filter", "type": "WixDataFilter", "doc": "Filter to refine the distinct query." } ], "ret": - { "type": - { "name": "Promise", - "typeParams": - [ "wix-data.WixDataDistinct" ] }, - "doc": "Fulfilled - The distinct query object.\nRejected - The errors that caused the rejection." }, + { "type": "wix-data.WixDataDistinct", + "doc": "The distinct query object." }, "locations": - [ { "lineno": 44, + [ { "lineno": 41, "filename": "distinct.js" } ], "docs": { "summary": "Sets the filter used to refine the distinct query.", "description": - [ "The `filter()` method defines the filter used to refine the distinct query. It returns a Promise that resolve to the [`WixDataDistinct`](ADDLINK) query object. The Promise is rejected if `filter()` is called with incorrect permissions or if any of the methods used to refine the query are invalid." ], + [ "The `filter()` method defines the filter used to refine the distinct query." ], "links": [], - "examples": [], + "examples": + [ { "title": "Set the distinct query filter", + "body": + [ "// Set the distinct query filter" ], + "extra": + { } } ], "extra": { } }, "extra": { } }, { "name": "getFilter", - "labels": [], + "labels": + [ "changed" ], "nameParams": [], "params": [], "ret": - { "type": - { "name": "Promise", - "typeParams": - [ "wix-data.WixDataFilter" ] }, - "doc": "Fulfilled - The filter used to refine the distinct query.\nRejected - The errors that caused the rejection." }, + { "type": "wix-data.WixDataFilter", + "doc": "The filter used to refine the distinct query." }, "locations": [ { "lineno": 29, "filename": "distinct.js" } ], "docs": { "summary": "Returns the filter used to refine the distinct query.", "description": - [ "The `getFilter()` method returns a Promise that resolves to the [`WixDataFilter()`](https://dev.wix.com/docs/sdk/backend-modules/data/items/wix-data-filter/introduction) that was used to refine the distinct query. The Promise is rejected if `getFilter()` is called with incorrect permissions or if any of the methods used to refine the query are invalid." ], + [ "The `getFilter()` method returns a [`WixDataFilter()`](https://dev.wix.com/docs/sdk/backend-modules/data/items/wix-data-filter/introduction) that was used to refine the distinct query." ], "links": [], - "examples": [], + "examples": + [ { "title": "Get the distinct query filter", + "body": + [ "let filter = distinctQuery.getFilter();" ], + "extra": + { } } ], "extra": { } }, "extra": { } }, { "name": "getPropertyName", - "labels": [], + "labels": + [ "changed" ], "nameParams": [], "params": [], "ret": - { "type": - { "name": "Promise", - "typeParams": - [ "string" ] }, - "doc": "Fulfilled - The property used to define the distinct query.\nRejected - The errors that caused the rejection." }, + { "type": "string", + "doc": "The property used to define the distinct query." }, "locations": - [ { "lineno": 60, + [ { "lineno": 54, "filename": "distinct.js" } ], "docs": { "summary": "Returns the name of the property used to define the distinct query.", "description": - [ "The `getPropertyName()` method returns a Promise that resolve to the name of the property used to define the distinct query. The Promise is rejected if the method is called with incorrect permissions or if any of the methods used to refine the query are invalid." ], + [ "The `getPropertyName()` method returns the name of the property used to define the distinct query." ], + "links": [], + "examples": + [ { "title": "Get the distinct property", + "body": + [ "// GET PROPERTY NAME let filter = distinctQuery.getFilter();" ], + "extra": + { } } ], + "extra": + { } }, + "extra": + { } }, + { "name": "isAscending", + "labels": + [ "new" ], + "nameParams": [], + "params": [], + "ret": + { "type": "boolean", + "doc": "Whether the results of the distinct query are sorted in ascending order." }, + "locations": + [ { "lineno": 80, + "filename": "distinct.js" } ], + "docs": + { "summary": "Whether the results of the distinct query are sorted in ascending order.", + "description": + [ "The `isAscending()` method returns `true` if the results of the distinct query are sorted in ascending order based on the distinct property." ], + "links": [], + "examples": + [ { "title": "Check whether the results of the distinct property are sorted in ascending order", + "body": + [ "// Check whether the results of the distinct property are sorted in ascending order" ], + "extra": + { } } ], + "extra": + { } }, + "extra": + { } }, + { "name": "isDescending", + "labels": + [ "new" ], + "nameParams": [], + "params": [], + "ret": + { "type": "boolean", + "doc": "Whether the results of the distinct query are sorted in descending order." }, + "locations": + [ { "lineno": 104, + "filename": "distinct.js" } ], + "docs": + { "summary": "Whether the results of the distinct query are sorted in descending order.", + "description": + [ "The `isDescending()` method returns `true` if the results of the distinct query are sorted in ascending order based on the distinct property." ], "links": [], - "examples": [], + "examples": + [ { "title": "Check if the results of the distinct property are sorted in descending order", + "body": + [ "// Check if the results of the distinct property are sorted in descending order", + "//" ], + "extra": + { } } ], "extra": { } }, "extra": { } }, { "name": "limit", - "labels": [], + "labels": + [ "changed" ], "nameParams": [], "params": [ { "name": "limit", @@ -332,7 +237,7 @@ { "type": "wix-data.WixDataDistinct", "doc": "A [`WixDataDistinct`](ADDLINK) object representing the refined distinct query." }, "locations": - [ { "lineno": 91, + [ { "lineno": 128, "filename": "distinct.js" } ], "docs": { "summary": "Limits the number of items the distinct query returns.", @@ -345,39 +250,50 @@ "", " > **Note** : For some [Wix app collections](https://dev.wix.com/docs/develop-websites/articles/databases/wix-data/collections/working-with-wix-app-collections-and-code), the maximum value `limit()` can accept is less than `1000`. For example, the maximum limit for the Wix `Stores/Product` collection is 100." ], "links": [], - "examples": [], + "examples": + [ { "title": "Add a limit to a distinct query", + "body": + [ "// Add a limit to a distinct query", + "// let filter = distinctQuery.getFilter();" ], + "extra": + { } } ], "extra": { } }, "extra": { } }, { "name": "propertyName", - "labels": [], + "labels": + [ "changed" ], "nameParams": [], "params": [ { "name": "newPropertyName", "type": "string", "doc": "Property by which to return distinct values, without duplicates." } ], "ret": - { "type": - { "name": "Promise", - "typeParams": - [ "wix-data.WixDataDistinct" ] }, - "doc": "Fulfilled - The distinct query object.\nRejected - The errors that caused the rejection." }, + { "type": "wix-data.WixDataDistinct", + "doc": "The distinct query object." }, "locations": - [ { "lineno": 75, + [ { "lineno": 66, "filename": "distinct.js" } ], "docs": { "summary": "Sets the property name by which to return distinct values.", "description": - [ "The `propertyName()` method defines the property by which to return distinct values, without duplicates. It returns a Promise that resolves to the [`WixDataDistinct`](ADDLINK) query object. The Promise is rejected if `propertyName()` is called with incorrect permissions or if any of the methods used to refine the query are invalid." ], + [ "The `propertyName()` method defines the property by which to return distinct values, without duplicates." ], "links": [], - "examples": [], + "examples": + [ { "title": "Set the distinct property", + "body": + [ "// Set the distinct property", + "// let filter = distinctQuery.getFilter();" ], + "extra": + { } } ], "extra": { } }, "extra": { } }, { "name": "skip", - "labels": [], + "labels": + [ "changed" ], "nameParams": [], "params": [ { "name": "skip", @@ -387,7 +303,7 @@ { "type": "wix-data.WixDataDistinct", "doc": "A `WixDataDistinct` object representing the refined query." }, "locations": - [ { "lineno": 110, + [ { "lineno": 146, "filename": "distinct.js" } ], "docs": { "summary": "Sets the number of items to skip before returning distinct query results.", @@ -398,7 +314,13 @@ "", " By default, `skip` is set to 0." ], "links": [], - "examples": [], + "examples": + [ { "title": "Add a skip to a distinct query", + "body": + [ "// Add a skip to a distinct query", + "//" ], + "extra": + { } } ], "extra": { } }, "extra": From 96eed96ce12e5e20905d33612701ff439cbecd47 Mon Sep 17 00:00:00 2001 From: idanlib-wix Date: Mon, 21 Apr 2025 15:01:50 +0300 Subject: [PATCH 3/6] DocWorks for wix-data - no significant changes detected, but 16 issue detected issues: Operation filter has an unknown param type WixDataFilter (distinct.js (41)) Operation ascending is defined two or more times (distinct.js (92), sortMixin.js (10)) Operation descending is defined two or more times (distinct.js (116), sortMixin.js (41)) Operation eq has an unknown param type * (filterMixin.js (33)) Operation ne has an unknown param type * (filterMixin.js (59)) Operation hasSome has an unknown param type * (filterMixin.js (342)) Operation hasAll has an unknown param type * (filterMixin.js (378)) Operation beforeAggregate is defined two or more times (hooks.js (313, 337)) Operation beforeAggregate has an unknown return type WixDataAggregate (hooks.js (313)) Operation beforeAggregate has an unknown return type WixDataAggregate (hooks.js (313)) Operation beforeDistinct has an unknown return type WixDataDistinct (hooks.js (395)) Operation beforeDistinct has an unknown return type WixDataDistinct (hooks.js (395)) Operation onFailure has an unknown param type Error (hooks.js (608)) Operation truncate has an unknown return type null (data-api.js (451)) Message WixDataBulkRemoveResult has an unknown property type Error (data-api.js (485)) Message WixDataBulkResult has an unknown property type Error (data-api.js (877)) --- wix-data/wix-data/Hooks.service.json | 9 ++--- .../wix-data/WixDataDistinct.service.json | 33 +++++++------------ 2 files changed, 14 insertions(+), 28 deletions(-) diff --git a/wix-data/wix-data/Hooks.service.json b/wix-data/wix-data/Hooks.service.json index edc2a376c4..8708227a66 100644 --- a/wix-data/wix-data/Hooks.service.json +++ b/wix-data/wix-data/Hooks.service.json @@ -1,8 +1,7 @@ { "name": "Hooks", "memberOf": "wix-data", "mixes": [], - "labels": - [ "changed" ], + "labels": [], "location": { "lineno": 20, "filename": "hooks.js" }, @@ -217,8 +216,7 @@ "extra": { } }, { "name": "afterDistinct", - "labels": - [ "changed" ], + "labels": [], "nameParams": [], "params": [ { "name": "item", @@ -931,8 +929,7 @@ "extra": { } }, { "name": "beforeDistinct", - "labels": - [ "changed" ], + "labels": [], "nameParams": [], "params": [ { "name": "distinctQuery", diff --git a/wix-data/wix-data/WixDataDistinct.service.json b/wix-data/wix-data/WixDataDistinct.service.json index 8b0a28642f..9d54b672af 100644 --- a/wix-data/wix-data/WixDataDistinct.service.json +++ b/wix-data/wix-data/WixDataDistinct.service.json @@ -2,8 +2,7 @@ "memberOf": "wix-data", "mixes": [ "wix-data.WixDataFilter" ], - "labels": - [ "changed" ], + "labels": [], "location": { "lineno": 1, "filename": "distinct.js" }, @@ -34,8 +33,7 @@ "properties": [], "operations": [ { "name": "ascending", - "labels": - [ "changed" ], + "labels": [], "nameParams": [], "params": [], "ret": @@ -63,8 +61,7 @@ "extra": { } }, { "name": "descending", - "labels": - [ "changed" ], + "labels": [], "nameParams": [], "params": [], "ret": @@ -92,8 +89,7 @@ "extra": { } }, { "name": "filter", - "labels": - [ "changed" ], + "labels": [], "nameParams": [], "params": [ { "name": "filter", @@ -121,8 +117,7 @@ "extra": { } }, { "name": "getFilter", - "labels": - [ "changed" ], + "labels": [], "nameParams": [], "params": [], "ret": @@ -147,8 +142,7 @@ "extra": { } }, { "name": "getPropertyName", - "labels": - [ "changed" ], + "labels": [], "nameParams": [], "params": [], "ret": @@ -173,8 +167,7 @@ "extra": { } }, { "name": "isAscending", - "labels": - [ "new" ], + "labels": [], "nameParams": [], "params": [], "ret": @@ -199,8 +192,7 @@ "extra": { } }, { "name": "isDescending", - "labels": - [ "new" ], + "labels": [], "nameParams": [], "params": [], "ret": @@ -226,8 +218,7 @@ "extra": { } }, { "name": "limit", - "labels": - [ "changed" ], + "labels": [], "nameParams": [], "params": [ { "name": "limit", @@ -262,8 +253,7 @@ "extra": { } }, { "name": "propertyName", - "labels": - [ "changed" ], + "labels": [], "nameParams": [], "params": [ { "name": "newPropertyName", @@ -292,8 +282,7 @@ "extra": { } }, { "name": "skip", - "labels": - [ "changed" ], + "labels": [], "nameParams": [], "params": [ { "name": "skip", From 66f2ac1f8268a057db08cb3aee1abd3264b66e82 Mon Sep 17 00:00:00 2001 From: Sam Markowitz Date: Tue, 22 Apr 2025 07:59:05 +0300 Subject: [PATCH 4/6] testing --- wix-data/DataHooks.service.json | 3367 +++++++++++++++++-------------- 1 file changed, 1847 insertions(+), 1520 deletions(-) diff --git a/wix-data/DataHooks.service.json b/wix-data/DataHooks.service.json index 696308b951..e72e2f80b3 100644 --- a/wix-data/DataHooks.service.json +++ b/wix-data/DataHooks.service.json @@ -1,1523 +1,1850 @@ -{ "name": "DataHooks", +{ + "name": "DataHooks", "mixes": [], - "labels": - [ "removed" ], - "location": - { "lineno": 20, - "filename": "hooks-standalone.js" }, - "docs": - { "summary": "Hooks that can be added to wix-data operations.", - "description": - [ "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](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-blocks/about-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:", - "", - " ``` javascript", - " export function _() { }", - " ```", - " 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:", - " 1. Click the **Databases** button and hover over the relevant collection.", - " 1. Click the **Show More** icon.", - " 1. Select **Add/Remove Hooks**, and choose the hooks you want to add.", - " ![Adding a Hook](images/add_remove_hooks.png \"Add/Remove Hook\")" ], - "links": [], - "examples": [], - "extra": - { } }, + "labels": [], + "location": { + "lineno": 20, + "filename": "hooks-standalone.js" + }, + "docs": { + "summary": "Hooks that can be added to wix-data operations.", + "description": [ + "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](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-blocks/about-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:", + "", + " ``` javascript", + " export function _() { }", + " ```", + " 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:", + " 1. Click the **Databases** button and hover over the relevant collection.", + " 1. Click the **Show More** icon.", + " 1. Select **Add/Remove Hooks**, and choose the hooks you want to add.", + " ![Adding a Hook](images/add_remove_hooks.png \"Add/Remove Hook\")" + ], + "links": [], + "examples": [], + "extra": {} + }, "properties": [], - "operations": - [ { "name": "afterAggregate", - "labels": [], - "nameParams": [], - "params": - [ { "name": "item", - "type": "Object", - "doc": "The aggregation result item." }, - { "name": "context", - "type": "DataHooks.HookContext", - "doc": "Contextual information about the hook." } ], - "ret": - { "type": - [ { "name": "Promise", - "typeParams": - [ "Object" ] }, - "Object" ], - "doc": "The item to return to [`aggregate()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update) to replace the original aggregation result item.\n Returning a rejected promise returns a rejected promise to the caller and triggers the [`onFailure()`](#onFailure) hook without blocking the aggregation operation." }, - "locations": - [ { "lineno": 56, - "filename": "hooks-standalone.js" } ], - "docs": - { "summary": "A hook triggered after an aggregation operation.", - "description": - [ "The `afterAggregate()` hook allows you to modify the aggregation results before they are returned to the caller. The hook runs for each item in the `items` array within the [WixDataAggregateResult](https://dev.wix.com/docs/velo/api-reference/wix-data/wix-data-aggregate-result/introduction) object, after the aggregation operation finishes and before the [`aggregate()`](https://dev.wix.com/docs/velo/api-reference/wix-data/aggregate) method returns.", - "", - "Return an object or a Promise that resolves to an object. If the returned value is of the wrong type, it is ignored.", - "", - "If returning a Promise, the object is used as the result regardless of whether the Promise is fulfilled or rejected. A rejected Promise also triggers the [`onFailure()`](#onFailure) hook, if it has been registered." ], - "links": [], - "examples": - [ { "title": "An `afterAggregate()` hook", - "body": - [ "// In data.js", - "", - "export function myCollection_afterAggregate(item, context) {", - " let hookContext = context; // see below", - "", - " // Some modification to the aggregated item.", - "", - " return item;", - "}", - "", - "/*", - " * hookContext:", - " *", - " * {", - " * \"collectionName\": \"myCollection\",", - " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", - " * \"userRole\": \"siteOwner\"", - " * }", - " */" ], - "extra": - { } }, - { "title": "Change the item returned by `aggregate()` using an `afterAggregate()` hook", - "body": - [ "// In data.js", - "", - "export function myCollection_afterAggregate(item, context) {", - " let hookContext = context; // see below", - "", - " // Modify the value of an aggregated item's property:", - " item.populationMax += 1000;", - " ", - " return item;", - "}", - "", - "/*", - " * hookContext:", - " *", - " * {", - " * \"collectionName\": \"myCollection\",", - " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", - " * \"userRole\": \"siteOwner\"", - " * }", - " */" ], - "extra": - { } } ], - "extra": - { } }, - "extra": - { } }, - { "name": "afterCount", - "labels": [], - "nameParams": [], - "params": - [ { "name": "count", - "type": "number", - "doc": "The number of items the count operation has found." }, - { "name": "context", - "type": "DataHooks.HookContext", - "doc": "Contextual information about the hook." } ], - "ret": - { "type": - [ { "name": "Promise", - "typeParams": - [ "number" ] }, - "number" ], - "doc": "The count to return to [`count()`](wix-data.WixDataQuery.html#count) instead of the original count.\n Returning a rejected promise will not block the operation, but will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." }, - "locations": - [ { "lineno": 79, - "filename": "hooks-standalone.js" } ], - "docs": - { "summary": "A hook that is triggered after a `count()` operation.", - "description": - [ "The `afterCount()` hook runs when:", - "", - " + The [`count()`](wix-data.WixDataQuery.html#count) function is called.", - " + The collection is viewed in the CMS.", - "", - "", - " 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()`](wix-data.WixDataQuery.html#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()`](#onFailure) hook if it has", - " been registered." ], - "links": [], - "examples": - [ { "title": "An afterCount hook", - "body": - [ "// 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\"", - " * }", - " */" ], - "extra": - { } }, - { "title": "Change the number returned by `count()` using an afterCount hook", - "body": - [ "// In data.js", - "", - "export function myCollection_afterCount(count, context) {", - " let hookContext = context; // see below", - "", - " // return a value higher than the actual item count", - " count += 5;", - "", - " return count;", - "}", - "", - "/*", - " * hookContext:", - " *", - " * {", - " * \"collectionName\": \"myCollection\",", - " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", - " * \"userRole\": \"siteOwner\"", - " * }", - " */" ], - "extra": - { } } ], - "extra": - { } }, - "extra": - { } }, - { "name": "afterGet", - "labels": [], - "nameParams": [], - "params": - [ { "name": "item", - "type": "Object", - "doc": "The item that was retrieved from the collection." }, - { "name": "context", - "type": "DataHooks.HookContext", - "doc": "Contextual information about the hook." } ], - "ret": - { "type": - [ { "name": "Promise", - "typeParams": - [ "Object" ] }, - "Object" ], - "doc": "The item to return to [`get()`](wix-data.html#get) instead of the retrieved item.\n 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()`](#onFailure) hook." }, - "locations": - [ { "lineno": 110, - "filename": "hooks-standalone.js" } ], - "docs": - { "summary": "A hook that is triggered after a `get()` operation.", - "description": - [ "The `afterGet()` hook runs when the [`get()`](wix-data.html#get)", - " function is called.", - "", - " The hook does not run when the [`find`](wix-data.WixDataQuery.html#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()`](wix-data.html#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()`](#onFailure) hook if it has", - " been registered." ], - "links": [], - "examples": - [ { "title": "An afterGet hook", - "body": - [ "// 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\"", - " * }", - " */" ], - "extra": - { } }, - { "title": "Change the item returned by `get()` using an afterGet hook", - "body": - [ "// In data.js", - "", - "export function myCollection_afterGet(item, context) {", - " let hookContext = context; // see below", - "", - " // add a full_name property to the item being returned", - " item.full_name = item.first_name + \" \" + item.last_name;", - "", - " return item;", - "}", - "", - "/*", - " * hookContext:", - " *", - " * {", - " * \"collectionName\": \"myCollection\",", - " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", - " * \"userRole\": \"siteOwner\"", - " * }", - " */" ], - "extra": - { } } ], - "extra": - { } }, - "extra": - { } }, - { "name": "afterInsert", - "labels": [], - "nameParams": [], - "params": - [ { "name": "item", - "type": "Object", - "doc": "The item that was inserted." }, - { "name": "context", - "type": "DataHooks.HookContext", - "doc": "Contextual information about the hook." } ], - "ret": - { "type": - [ { "name": "Promise", - "typeParams": - [ "Object" ] }, - "Object" ], - "doc": "The item to return to [`insert()`](wix-data.html#insert) instead of the inserted item.\n Returning a rejected promise will not block the operation, but will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." }, - "locations": - [ { "lineno": 142, - "filename": "hooks-standalone.js" } ], - "docs": - { "summary": "A hook that is triggered after an `insert()` operation.", - "description": - [ "The `afterInsert()` hook runs when:", - "", - " + The [`insert()`](wix-data.html#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 CMS.", - " + An item is imported into the Sandbox or Live collection.", - "", - "", - " 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()`](wix-data.html#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()`](#onFailure) hook if it has", - " been registered.", - "", - " Because the `afterInsert` hook is called after the [`insert()`](wix-data.html#insert)", - " is executed, it cannot affect the item that is inserted into the collection.", - " It can only affect the item returned by [`insert()`](wix-data.html#insert)." ], - "links": [], - "examples": - [ { "title": "An afterInsert hook", - "body": - [ "// 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\"", - " * }", - " */" ], - "extra": - { } }, - { "title": "Change the item returned by `insert()` using an afterInsert hook", - "body": - [ "// In data.js", - "", - "export function myCollection_afterInsert(item, context) {", - " let hookContext = context; // see below", - "", - " //add a new property to the item being returned that aggregates the content from several fields into one", - " item.combinedSentence = `Customer: ${item.lastName}, ${item.firstName}: Purchases: ${item.purchases}, Item Returns: ${item.returns}`;", - "", - " return item;", - "}", - "", - "/*", - " * hookContext:", - " *", - " * {", - " * \"collectionName\": \"myCollection\",", - " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", - " * \"userRole\": \"siteOwner\"", - " * }", - " */" ], - "extra": - { } } ], - "extra": - { } }, - "extra": - { } }, - { "name": "afterQuery", - "labels": [], - "nameParams": [], - "params": - [ { "name": "item", - "type": "Object", - "doc": "One of the items of the query result. The hook is called for each item in the results." }, - { "name": "context", - "type": "DataHooks.HookContext", - "doc": "Contextual information about the hook." } ], - "ret": - { "type": - [ { "name": "Promise", - "typeParams": - [ "Object" ] }, - "Object" ], - "doc": "The item to return to [`find`](wix-data.WixDataQuery.html#find) instead of the item retrieved from the database.\n 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()`](#onFailure) hook." }, - "locations": - [ { "lineno": 179, - "filename": "hooks-standalone.js" } ], - "docs": - { "summary": "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`](wix-data.WixDataQuery.html#find) function is called.", - " + An action is performed on a dataset that retrieves items from the collection.", - " + The collection is viewed in the CMS.", - " + An item is exported from the collection.", - "", - "", - " 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`](wix-data.WixDataQuery.html#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()`](#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." ], - "links": [], - "examples": - [ { "title": "An afterQuery hook", - "body": - [ "// 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\"", - " * }", - " */" ], - "extra": - { } }, - { "title": "Change the item returned by `find()` using an afterQuery hook", - "body": - [ "// In data.js", - "", - "export function myCollection_afterQuery(item, context) {", - " let hookContext = context; // see below", - "", - " // add a full_name property to the item being returned", - " item.full_name = item.first_name + \" \" + item.last_name;", - "", - " return item;", - "}", - "", - "/*", - " * hookContext:", - " *", - " * {", - " * \"collectionName\": \"myCollection\",", - " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", - " * \"userRole\": \"siteOwner\"", - " * }", - " */" ], - "extra": - { } } ], - "extra": - { } }, - "extra": - { } }, - { "name": "afterRemove", - "labels": [], - "nameParams": [], - "params": - [ { "name": "item", - "type": "Object", - "doc": "The item that was removed." }, - { "name": "context", - "type": "DataHooks.HookContext", - "doc": "Contextual information about the hook." } ], - "ret": - { "type": - [ { "name": "Promise", - "typeParams": - [ "Object" ] }, - "Object" ], - "doc": "The item to return to [`remove()`](wix-data.html#remove) instead of the deleted item.\n Returning a rejected promise will not block the operation, but will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." }, - "locations": - [ { "lineno": 219, - "filename": "hooks-standalone.js" } ], - "docs": - { "summary": "A hook that is triggered after a `remove()` operation.", - "description": - [ "The `afterRemove()` hook runs when:", - "", - " + The [`remove()`](wix-data.html#remove) function is called.", - " + An action is performed on a dataset that removes an item from the collection.", - " + An item is deleted using the CMS.", - "", - "", - " 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()`](wix-data.html#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()`](#onFailure) hook if it has", - " been registered.", - "", - " Because the `afterRemove()` hook is called after the [`remove()`](wix-data.html#remove)", - " is executed, it cannot prevent the item from being removed from the collection.", - " It can only affect the item returned by [`remove()`](wix-data.html#remove)." ], - "links": [], - "examples": - [ { "title": "An afterRemove hook", - "body": - [ "// 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\"", - " * }", - " */" ], - "extra": - { } }, - { "title": "Change the item returned by `remove()` using an afterRemove hook", - "body": - [ "// In data.js", - "", - "export function myCollection_afterUpdate(item, context) {", - " let hookContext = context; // see below", - "", - " // add a full_name property to the item being returned", - " item.full_name = item.first_name + \" \" + item.last_name;", - "", - " return item;", - "}", - "", - "/*", - " * hookContext:", - " *", - " * {", - " * \"collectionName\": \"myCollection\",", - " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", - " * \"userRole\": \"siteOwner\"", - " * }", - " */" ], - "extra": - { } } ], - "extra": - { } }, - "extra": - { } }, - { "name": "afterUpdate", - "labels": [], - "nameParams": [], - "params": - [ { "name": "item", - "type": "Object", - "doc": "The updated item." }, - { "name": "context", - "type": "DataHooks.UpdateHookContext", - "doc": "Contextual information about the hook." } ], - "ret": - { "type": - [ { "name": "Promise", - "typeParams": - [ "Object" ] }, - "Object" ], - "doc": "The item to return to [`update()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update) instead of the updated item.\n Returning a rejected promise will not block the operation, but will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." }, - "locations": - [ { "lineno": 254, - "filename": "hooks-standalone.js" } ], - "docs": - { "summary": "A hook that is triggered after an `update()` operation.", - "description": - [ "The `afterUpdate()` hook runs when:", - "", - " + The [`update()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update) function is called.", - " + An action is performed on a dataset that updates an item from the collection.", - " + An item is updated using the CMS.", - "", - " **Note**: When [scheduling an item's visibility change](https://support.wix.com/en/article/cms-controlling-live-site-item-visibility-from-your-collection#scheduling-changes-to-item-visibility), 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()`](https://dev.wix.com/docs/velo/api-reference/wix-data/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()`](#onFailure) hook if it has", - " been registered.", - "", - " Because the `afterUpdate` hook is called after the [`update()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update)", - " is executed, it cannot affect the item that is being updated in the collection.", - " It can only affect the item returned by [`update()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update)." ], - "links": [], - "examples": - [ { "title": "An afterUpdate hook", - "body": - [ "// 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\"", - " * }", - " */" ], - "extra": - { } }, - { "title": "Change the item returned by `update()` using an afterUpdate hook", - "body": - [ "// In data.js", - "", - "export function myCollection_afterUpdate(item, context) {", - " let hookContext = context; // see below", - " ", - " // add a full_name property to the item being returned", - " item.full_name = item.first_name + \" \" + item.last_name;", - " ", - " return item;", - "}", - "", - "/*", - " * hookContext:", - " *", - " * {", - " * \"collectionName\": \"myCollection\",", - " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", - " * \"userRole\": \"siteOwner\"", - " * }", - " */" ], - "extra": - { } } ], - "extra": - { } }, - "extra": - { } }, - { "name": "beforeAggregate", - "labels": - [ "removed" ], - "nameParams": [], - "params": - [ { "name": "aggregate", - "type": "wix-data.WixDataAggregate", - "doc": "The original `WixDataAggregate` object." }, - { "name": "context", - "type": "DataHooks.UpdateHookContext", - "doc": "Contextual information about the hook." } ], - "ret": - { "type": - [ { "name": "Promise", - "typeParams": - [ "wix-data.WixDataAggregate" ] }, - "wix-data.WixDataAggregate" ], - "doc": "The aggregate object to run instead of the original object created by the `aggregate()` method.\n Returning a rejected promise blocks the operation, returns a rejected promise to the caller, and triggers the [`onFailure()`](#onFailure) hook." }, - "locations": - [ { "lineno": 292, - "filename": "hooks-standalone.js" } ], - "docs": - { "summary": "A hook triggered before an aggregation operation.", - "description": - [ "The `beforeAggregate()` hook runs when the [`aggregate()`](https://dev.wix.com/docs/velo/api-reference/wix-data/aggregate) is called, and allows you to modify the [`WixDataAggregate`](https://dev.wix.com/docs/velo/api-reference/wix-data/wix-data-aggregate/introduction) object before the aggregation operation runs. ", - "", - "", - " Return a [WixDataAggregate](https://dev.wix.com/docs/velo/api-reference/wix-data/wix-data-aggregate/introduction) object or a Promise that resolves to a [WixDataAggregate](https://dev.wix.com/docs/velo/api-reference/wix-data/wix-data-aggregate/introduction) object. The returned object is the aggregation that runs on the collection instead of the original aggregation created by the [`aggregate()`](https://dev.wix.com/docs/velo/api-reference/wix-data/aggregate) method.", - "", - " If the returned value is of the wrong type, the value is ignored.", - "", - " A rejected Promise blocks the call to [`aggregate()`](https://dev.wix.com/docs/velo/api-reference/wix-data/aggregate) and triggers the [`onFailure()`](#onFailure) hook, if it has been registered." ], - "links": [], - "examples": - [ { "title": "A `beforeAggregate` hook", - "body": - [ "// In data.js", - "", - "export function myCollection_beforeAggregate(aggregate, context) {", - " let hookContext = context; // see below", - "", - " // Some modification to the WixDataAggregate object.", - "", - " return aggregate;", - "}", - "", - "/*", - " * hookContext:", - " *", - " * {", - " * \"collectionName\": \"myCollection\",", - " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", - " * \"userRole\": \"siteOwner\"", - " * }", - " */" ], - "extra": - { } }, - { "title": "Change the `WixDataAggregate` object using a `beforeAggregate` hook", - "body": - [ "// In data.js", - "", - "export function myCollection_afterAggregate(aggregate, context) {", - " let hookContext = context; // see below", - "", - " // Add a filter to the aggregation object.", - " let newAggregate = aggregate.filter().le(\"population\", 2000000);", - "", - " return newAggregate;", - "}", - "", - "/*", - " * hookContext:", - " *", - " * {", - " * \"collectionName\": \"myCollection\",", - " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", - " * \"userRole\": \"siteOwner\"", - " * }", - " */" ], - "extra": - { } } ], - "extra": - { } }, - "extra": - { } }, - { "name": "beforeCount", - "labels": [], - "nameParams": [], - "params": - [ { "name": "query", - "type": "wix-data.WixDataQuery", - "doc": "The original query as defined by [`count()`](wix-data.WixDataQuery.html#count)." }, - { "name": "context", - "type": "DataHooks.HookContext", - "doc": "Contextual information about the hook." } ], - "ret": - { "type": - [ { "name": "Promise", - "typeParams": - [ "wix-data.WixDataQuery" ] }, - "wix-data.WixDataQuery" ], - "doc": "The `query` to be used for the [`count()`](wix-data.WixDataQuery.html#count) operation instead of the original query.\n Returning a rejected promise will block the operation and will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." }, - "locations": - [ { "lineno": 292, - "filename": "hooks-standalone.js" } ], - "docs": - { "summary": "A hook that is triggered before a `count()` operation.", - "description": - [ "The `beforeCount()` hook runs when:", - "", - " + The [`count()`](wix-data.WixDataQuery.html#count) function is called.", - " + The collection is viewed in the CMS.", - "", - "", - " 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()`](wix-data.WixDataQuery.html#count) operation.", - "", - " Often, you will modify the query that is received in the `query` parameter", - " by calling one or more [`WixDataQuery`](wix-data.WixDataQuery.html) functions.", - "", - " If the returned value is of the wrong type, the value is ignored.", - "", - " A rejected Promise blocks the call to [`count()`](wix-data.WixDataQuery.html#count)", - " and also calls the [`onFailure()`](#onFailure) hook if it has been registered.", - "", - " Because the `beforeCount()` hook is called before [`count()`](wix-data.WixDataQuery.html#count)", - " is executed, it can affect how items are counted or block the [`count()`](wix-data.WixDataQuery.html#count)." ], - "links": [], - "examples": - [ { "title": "A beforeCount hook", - "body": - [ "// 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\"", - " * }", - " */" ], - "extra": - { } }, - { "title": "Change the query used for the count, using a beforeCount hook", - "body": - [ "// 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\"", - " * }", - " */" ], - "extra": - { } } ], - "extra": - { } }, - "extra": - { } }, - { "name": "beforeGet", - "labels": [], - "nameParams": [], - "params": - [ { "name": "itemId", - "type": "string", - "doc": "The ID of the original item to be retrieved." }, - { "name": "context", - "type": "DataHooks.HookContext", - "doc": "Contextual information about the hook." } ], - "ret": - { "type": - [ { "name": "Promise", - "typeParams": - [ "string" ] }, - "string" ], - "doc": "The ID to be used for the [`get()`](wix-data.html#get) operation instead of the original `itemId` specified by the caller.\n Returning a rejected promise will block the operation and will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." }, - "locations": - [ { "lineno": 327, - "filename": "hooks-standalone.js" } ], - "docs": - { "summary": "A hook that is triggered before a `get()` operation.", - "description": - [ "The `beforeGet()` hook runs when the [`get()`](wix-data.html#get)", - " function is called.", - "", - " The hook does not run when the [`find`](wix-data.WixDataQuery.html#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()`](wix-data.html#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()`](wix-data.html#get)", - " and also calls the [`onFailure()`](#onFailure) hook if it has been registered.", - "", - " Because the `beforeGet()` hook is called before [`get()`](wix-data.html#get)", - " is executed, it can affect which item is retrieved", - " or block the [`get()`](wix-data.html#get)." ], - "links": [], - "examples": - [ { "title": "A beforeGet hook", - "body": - [ "// 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\"", - " * }", - " */" ], - "extra": - { } }, - { "title": "Change which item is retrieved using a beforeGet hook", - "body": - [ "// 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\"", - " * }", - " */" ], - "extra": - { } } ], - "extra": - { } }, - "extra": - { } }, - { "name": "beforeInsert", - "labels": [], - "nameParams": [], - "params": - [ { "name": "item", - "type": "Object", - "doc": "The original item to be inserted." }, - { "name": "context", - "type": "DataHooks.HookContext", - "doc": "Contextual information about the hook." } ], - "ret": - { "type": - [ { "name": "Promise", - "typeParams": - [ "Object" ] }, - "Object" ], - "doc": "The item to be inserted instead of the original item specified by the caller.\n Returning a rejected promise will block the operation and will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." }, - "locations": - [ { "lineno": 362, - "filename": "hooks-standalone.js" } ], - "docs": - { "summary": "A hook that is triggered before an `insert()` operation.", - "description": - [ "The `beforeInsert()` hook runs when:", - "", - " + The [`insert()`](wix-data.html#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 CMS.", - " + An item is imported into the Sandbox or Live collection.", - "", - "", - " 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()`](wix-data.html#insert) function.", - "", - " If the returned value is of the wrong type, the value is ignored.", - "", - " A rejected Promise blocks the call to [`insert()`](wix-data.html#insert)", - " and also calls the [`onFailure()`](#onFailure) hook if it has been registered.", - "", - " Because the `beforeInsert()` hook is called before [`insert()`](wix-data.html#insert)", - " is executed, it can affect the item that is inserted into the collection", - " or block the [`insert()`](wix-data.html#insert)." ], - "links": [], - "examples": - [ { "title": "A beforeInsert hook", - "body": - [ "// 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\"", - " * }", - " */" ], - "extra": - { } }, - { "title": "Change the item to insert using a beforeInsert hook", - "body": - [ "// 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\"", - " * }", - " */" ], - "extra": - { } }, - { "title": "Validate an email address field using a beforeInsert hook", - "body": - [ "// In data.js", - "", - "export function myCollection_beforeInsert(item, context) {", - " let hookContext = context; // see below", - "", - " //validate the email field and reject in case of failure", - " const emailRegex = /^\\w+([\\.-]?\\w+)*@\\w+([\\.-]?\\w+)*(\\.\\w{2,3})+$/;", - "", - " if (emailRegex.test(item.email)) {", - " return item;", - " } else {", - " return Promise.reject('Invalid email address.');", - " }", - "}", - "", - "/*", - " * hookContext:", - " *", - " * {", - " * \"collectionName\": \"myCollection\",", - " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", - " * \"userRole\": \"siteOwner\"", - " * }", - " */" ], - "extra": - { } } ], - "extra": - { } }, - "extra": - { } }, - { "name": "beforeQuery", - "labels": [], - "nameParams": [], - "params": - [ { "name": "query", - "type": "wix-data.WixDataQuery", - "doc": "The original query as specified by the caller." }, - { "name": "context", - "type": "DataHooks.HookContext", - "doc": "Contextual information about the hook." } ], - "ret": - { "type": - [ { "name": "Promise", - "typeParams": - [ "wix-data.WixDataQuery" ] }, - "wix-data.WixDataQuery" ], - "doc": "The query to use instead of the original query specified by the caller.\n Returning a rejected promise will block the operation and will return a rejected promise to the operation caller as well as trigger the [`onFailure()`](#onFailure) hook." }, - "locations": - [ { "lineno": 401, - "filename": "hooks-standalone.js" } ], - "docs": - { "summary": "A hook that is triggered before a `find()` operation.", - "description": - [ "The `beforeQuery()` hook runs when:", - "", - " + The [`find`](wix-data.WixDataQuery.html#find) function is called.", - " + An action is performed on a dataset that retrieves items from the collection.", - " + The collection is viewed in the CMS.", - " + An item is exported from the collection.", - "", - "", - " 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`](wix-data.WixDataQuery.html#find) operation.", - "", - " Often, you will modify the query that is received in the `query` parameter", - " by calling one or more [`WixDataQuery`](wix-data.WixDataQuery.html) functions.", - "", - " If the returned value is of the wrong type, the value is ignored.", - "", - " A rejected Promise blocks the call to [`find()`](wix-data.WixDataQuery.html#find)", - " and also calls the [`onFailure()`](#onFailure) hook if it has been registered.", - "", - " Because the `beforeQuery()` hook is called before [`find()`](wix-data.WixDataQuery.html#find)", - " is executed, it can affect the query that is used to retrieve items", - " or block the [`find()`](wix-data.WixDataQuery.html#find)." ], - "links": [], - "examples": - [ { "title": "A beforeQuery hook", - "body": - [ "// 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\"", - " * }", - " */" ], - "extra": - { } }, - { "title": "Change the query to be executed using the beforeQuery hook", - "body": - [ "// 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\"", - " * }", - " */" ], - "extra": - { } } ], - "extra": - { } }, - "extra": - { } }, - { "name": "beforeRemove", - "labels": [], - "nameParams": [], - "params": - [ { "name": "itemId", - "type": "string", - "doc": "The ID of the original item to be removed." }, - { "name": "context", - "type": "DataHooks.UpdateHookContext", - "doc": "Contextual information about the hook." } ], - "ret": - { "type": - [ { "name": "Promise", - "typeParams": - [ "string" ] }, - "string" ], - "doc": "The ID to be used for the [`remove()`](wix-data.html#remove) instead of the original `itemId` specified by the caller.\n Returning a rejected promise will block the operation and will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." }, - "locations": - [ { "lineno": 442, - "filename": "hooks-standalone.js" } ], - "docs": - { "summary": "A hook that is called before a `remove()` operation.", - "description": - [ "The `beforeRemove()` hook runs when:", - "", - " + The [`remove()`](wix-data.html#remove) function is called.", - " + An action is performed on a dataset that removes an item from the collection.", - " + An item is deleted using the CMS.", - "", - "", - " 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()`](wix-data.html#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()`](wix-data.html#remove)", - " and also calls the [`onFailure()`](#onFailure) hook if it has been registered.", - "", - " Because the `beforeRemove()` hook is called before [`remove()`](wix-data.html#remove)", - " is executed, it can affect the item that is removed from the collection", - " or block the [`remove()`](wix-data.html#remove)." ], - "links": [], - "examples": - [ { "title": "A beforeRemove hook", - "body": - [ "// 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\"", - " * }", - " */" ], - "extra": - { } }, - { "title": "Change the item to remove using a beforeRemove hook", - "body": - [ "// 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\"", - " * }", - " */" ], - "extra": - { } } ], - "extra": - { } }, - "extra": - { } }, - { "name": "beforeUpdate", - "labels": [], - "nameParams": [], - "params": - [ { "name": "item", - "type": "Object", - "doc": "The original item to be updated." }, - { "name": "context", - "type": "DataHooks.UpdateHookContext", - "doc": "Contextual information about the hook." } ], - "ret": - { "type": - [ { "name": "Promise", - "typeParams": - [ "Object" ] }, - "Object" ], - "doc": "The item to be updated instead of the original item specified by the caller.\n Returning a rejected promise will block the operation and will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." }, - "locations": - [ { "lineno": 480, - "filename": "hooks-standalone.js" } ], - "docs": - { "summary": "A hook that is triggered before an `update()` operation.", - "description": - [ "The `beforeUpdate()` hook runs when:", - "", - " + The [`update()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update) function is called.", - " + An action is performed on a dataset that updates an item from the collection.", - " + An item is updated using the CMS.", - "", - "", - " 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()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update) function.", - "", - " If the returned value is of the wrong type, the value is ignored.", - "", - " A rejected Promise blocks the call to [`update()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update)", - " and also calls the [`onFailure()`](#onFailure) hook if it has been registered.", - "", - " Because the `beforeUpdate()` hook is called before the [`update()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update)", - " is executed, it can affect the item that is updated in the collection", - " or block the [`update()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update)." ], - "links": [], - "examples": - [ { "title": "A beforeUpdate hook", - "body": - [ "// 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\"", - " * }", - " */" ], - "extra": - { } }, - { "title": "Change the item to update using a beforeUpdate hook", - "body": - [ "// 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\"", - " * }", - " */" ], - "extra": - { } } ], - "extra": - { } }, - "extra": - { } }, - { "name": "onFailure", - "labels": [], - "nameParams": [], - "params": - [ { "name": "error", - "type": "Error", - "doc": "The error that caused the failure." }, - { "name": "context", - "type": "DataHooks.HookContext", - "doc": "Contextual information about the hook." } ], - "ret": - { "type": - { "name": "Promise", - "typeParams": - [ "Object" ] }, - "doc": "Fulfilled - Returning a fulfilled promise will result in a fulfilled data operation with the provided result.\nRejected - Returning a rejected promise will result in returning a rejected promise to the caller of the data operation." }, - "locations": - [ { "lineno": 517, - "filename": "hooks-standalone.js" } ], - "docs": - { "summary": "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." ], - "links": [], - "examples": - [ { "title": "A hook triggered when a failure occurs", - "body": - [ "// 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", - " * }", - " */" ], - "extra": - { } } ], - "extra": - { } }, - "extra": - { } } ], + "operations": [ + { + "name": "afterAggregate", + "labels": [], + "nameParams": [], + "params": [ + { + "name": "item", + "type": "Object", + "doc": "The aggregation result item." + }, + { + "name": "context", + "type": "DataHooks.HookContext", + "doc": "Contextual information about the hook." + } + ], + "ret": { + "type": [ + { + "name": "Promise", + "typeParams": [ + "Object" + ] + }, + "Object" + ], + "doc": "The item to return to [`aggregate()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update) to replace the original aggregation result item.\n Returning a rejected promise returns a rejected promise to the caller and triggers the [`onFailure()`](#onFailure) hook without blocking the aggregation operation." + }, + "locations": [ + { + "lineno": 56, + "filename": "hooks-standalone.js" + } + ], + "docs": { + "summary": "A hook triggered after an aggregation operation.", + "description": [ + "The `afterAggregate()` hook allows you to modify the aggregation results before they are returned to the caller. The hook runs for each item in the `items` array within the [WixDataAggregateResult](https://dev.wix.com/docs/velo/api-reference/wix-data/wix-data-aggregate-result/introduction) object, after the aggregation operation finishes and before the [`aggregate()`](https://dev.wix.com/docs/velo/api-reference/wix-data/aggregate) method returns.", + "", + "Return an object or a Promise that resolves to an object. If the returned value is of the wrong type, it is ignored.", + "", + "If returning a Promise, the object is used as the result regardless of whether the Promise is fulfilled or rejected. A rejected Promise also triggers the [`onFailure()`](#onFailure) hook, if it has been registered." + ], + "links": [], + "examples": [ + { + "title": "An `afterAggregate()` hook", + "body": [ + "// In data.js", + "", + "export function myCollection_afterAggregate(item, context) {", + " let hookContext = context; // see below", + "", + " // Some modification to the aggregated item.", + "", + " return item;", + "}", + "", + "/*", + " * hookContext:", + " *", + " * {", + " * \"collectionName\": \"myCollection\",", + " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", + " * \"userRole\": \"siteOwner\"", + " * }", + " */" + ], + "extra": {} + }, + { + "title": "Change the item returned by `aggregate()` using an `afterAggregate()` hook", + "body": [ + "// In data.js", + "", + "export function myCollection_afterAggregate(item, context) {", + " let hookContext = context; // see below", + "", + " // Modify the value of an aggregated item's property:", + " item.populationMax += 1000;", + " ", + " return item;", + "}", + "", + "/*", + " * hookContext:", + " *", + " * {", + " * \"collectionName\": \"myCollection\",", + " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", + " * \"userRole\": \"siteOwner\"", + " * }", + " */" + ], + "extra": {} + } + ], + "extra": {} + }, + "extra": {} + }, + { + "name": "afterCount", + "labels": [], + "nameParams": [], + "params": [ + { + "name": "count", + "type": "number", + "doc": "The number of items the count operation has found." + }, + { + "name": "context", + "type": "DataHooks.HookContext", + "doc": "Contextual information about the hook." + } + ], + "ret": { + "type": [ + { + "name": "Promise", + "typeParams": [ + "number" + ] + }, + "number" + ], + "doc": "The count to return to [`count()`](wix-data.WixDataQuery.html#count) instead of the original count.\n Returning a rejected promise will not block the operation, but will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." + }, + "locations": [ + { + "lineno": 79, + "filename": "hooks-standalone.js" + } + ], + "docs": { + "summary": "A hook that is triggered after a `count()` operation.", + "description": [ + "The `afterCount()` hook runs when:", + "", + " + The [`count()`](wix-data.WixDataQuery.html#count) function is called.", + " + The collection is viewed in the CMS.", + "", + "", + " 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()`](wix-data.WixDataQuery.html#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()`](#onFailure) hook if it has", + " been registered." + ], + "links": [], + "examples": [ + { + "title": "An afterCount hook", + "body": [ + "// 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\"", + " * }", + " */" + ], + "extra": {} + }, + { + "title": "Change the number returned by `count()` using an afterCount hook", + "body": [ + "// In data.js", + "", + "export function myCollection_afterCount(count, context) {", + " let hookContext = context; // see below", + "", + " // return a value higher than the actual item count", + " count += 5;", + "", + " return count;", + "}", + "", + "/*", + " * hookContext:", + " *", + " * {", + " * \"collectionName\": \"myCollection\",", + " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", + " * \"userRole\": \"siteOwner\"", + " * }", + " */" + ], + "extra": {} + } + ], + "extra": {} + }, + "extra": {} + }, + { + "name": "afterGet", + "labels": [], + "nameParams": [], + "params": [ + { + "name": "item", + "type": "Object", + "doc": "The item that was retrieved from the collection." + }, + { + "name": "context", + "type": "DataHooks.HookContext", + "doc": "Contextual information about the hook." + } + ], + "ret": { + "type": [ + { + "name": "Promise", + "typeParams": [ + "Object" + ] + }, + "Object" + ], + "doc": "The item to return to [`get()`](wix-data.html#get) instead of the retrieved item.\n 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()`](#onFailure) hook." + }, + "locations": [ + { + "lineno": 110, + "filename": "hooks-standalone.js" + } + ], + "docs": { + "summary": "A hook that is triggered after a `get()` operation.", + "description": [ + "The `afterGet()` hook runs when the [`get()`](wix-data.html#get)", + " function is called.", + "", + " The hook does not run when the [`find`](wix-data.WixDataQuery.html#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()`](wix-data.html#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()`](#onFailure) hook if it has", + " been registered." + ], + "links": [], + "examples": [ + { + "title": "An afterGet hook", + "body": [ + "// 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\"", + " * }", + " */" + ], + "extra": {} + }, + { + "title": "Change the item returned by `get()` using an afterGet hook", + "body": [ + "// In data.js", + "", + "export function myCollection_afterGet(item, context) {", + " let hookContext = context; // see below", + "", + " // add a full_name property to the item being returned", + " item.full_name = item.first_name + \" \" + item.last_name;", + "", + " return item;", + "}", + "", + "/*", + " * hookContext:", + " *", + " * {", + " * \"collectionName\": \"myCollection\",", + " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", + " * \"userRole\": \"siteOwner\"", + " * }", + " */" + ], + "extra": {} + } + ], + "extra": {} + }, + "extra": {} + }, + { + "name": "afterInsert", + "labels": [], + "nameParams": [], + "params": [ + { + "name": "item", + "type": "Object", + "doc": "The item that was inserted." + }, + { + "name": "context", + "type": "DataHooks.HookContext", + "doc": "Contextual information about the hook." + } + ], + "ret": { + "type": [ + { + "name": "Promise", + "typeParams": [ + "Object" + ] + }, + "Object" + ], + "doc": "The item to return to [`insert()`](wix-data.html#insert) instead of the inserted item.\n Returning a rejected promise will not block the operation, but will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." + }, + "locations": [ + { + "lineno": 142, + "filename": "hooks-standalone.js" + } + ], + "docs": { + "summary": "A hook that is triggered after an `insert()` operation.", + "description": [ + "The `afterInsert()` hook runs when:", + "", + " + The [`insert()`](wix-data.html#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 CMS.", + " + An item is imported into the Sandbox or Live collection.", + "", + "", + " 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()`](wix-data.html#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()`](#onFailure) hook if it has", + " been registered.", + "", + " Because the `afterInsert` hook is called after the [`insert()`](wix-data.html#insert)", + " is executed, it cannot affect the item that is inserted into the collection.", + " It can only affect the item returned by [`insert()`](wix-data.html#insert)." + ], + "links": [], + "examples": [ + { + "title": "An afterInsert hook", + "body": [ + "// 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\"", + " * }", + " */" + ], + "extra": {} + }, + { + "title": "Change the item returned by `insert()` using an afterInsert hook", + "body": [ + "// In data.js", + "", + "export function myCollection_afterInsert(item, context) {", + " let hookContext = context; // see below", + "", + " //add a new property to the item being returned that aggregates the content from several fields into one", + " item.combinedSentence = `Customer: ${item.lastName}, ${item.firstName}: Purchases: ${item.purchases}, Item Returns: ${item.returns}`;", + "", + " return item;", + "}", + "", + "/*", + " * hookContext:", + " *", + " * {", + " * \"collectionName\": \"myCollection\",", + " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", + " * \"userRole\": \"siteOwner\"", + " * }", + " */" + ], + "extra": {} + } + ], + "extra": {} + }, + "extra": {} + }, + { + "name": "afterQuery", + "labels": [], + "nameParams": [], + "params": [ + { + "name": "item", + "type": "Object", + "doc": "One of the items of the query result. The hook is called for each item in the results." + }, + { + "name": "context", + "type": "DataHooks.HookContext", + "doc": "Contextual information about the hook." + } + ], + "ret": { + "type": [ + { + "name": "Promise", + "typeParams": [ + "Object" + ] + }, + "Object" + ], + "doc": "The item to return to [`find`](wix-data.WixDataQuery.html#find) instead of the item retrieved from the database.\n 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()`](#onFailure) hook." + }, + "locations": [ + { + "lineno": 179, + "filename": "hooks-standalone.js" + } + ], + "docs": { + "summary": "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`](wix-data.WixDataQuery.html#find) function is called.", + " + An action is performed on a dataset that retrieves items from the collection.", + " + The collection is viewed in the CMS.", + " + An item is exported from the collection.", + "", + "", + " 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`](wix-data.WixDataQuery.html#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()`](#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." + ], + "links": [], + "examples": [ + { + "title": "An afterQuery hook", + "body": [ + "// 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\"", + " * }", + " */" + ], + "extra": {} + }, + { + "title": "Change the item returned by `find()` using an afterQuery hook", + "body": [ + "// In data.js", + "", + "export function myCollection_afterQuery(item, context) {", + " let hookContext = context; // see below", + "", + " // add a full_name property to the item being returned", + " item.full_name = item.first_name + \" \" + item.last_name;", + "", + " return item;", + "}", + "", + "/*", + " * hookContext:", + " *", + " * {", + " * \"collectionName\": \"myCollection\",", + " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", + " * \"userRole\": \"siteOwner\"", + " * }", + " */" + ], + "extra": {} + } + ], + "extra": {} + }, + "extra": {} + }, + { + "name": "afterRemove", + "labels": [], + "nameParams": [], + "params": [ + { + "name": "item", + "type": "Object", + "doc": "The item that was removed." + }, + { + "name": "context", + "type": "DataHooks.HookContext", + "doc": "Contextual information about the hook." + } + ], + "ret": { + "type": [ + { + "name": "Promise", + "typeParams": [ + "Object" + ] + }, + "Object" + ], + "doc": "The item to return to [`remove()`](wix-data.html#remove) instead of the deleted item.\n Returning a rejected promise will not block the operation, but will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." + }, + "locations": [ + { + "lineno": 219, + "filename": "hooks-standalone.js" + } + ], + "docs": { + "summary": "A hook that is triggered after a `remove()` operation.", + "description": [ + "The `afterRemove()` hook runs when:", + "", + " + The [`remove()`](wix-data.html#remove) function is called.", + " + An action is performed on a dataset that removes an item from the collection.", + " + An item is deleted using the CMS.", + "", + "", + " 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()`](wix-data.html#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()`](#onFailure) hook if it has", + " been registered.", + "", + " Because the `afterRemove()` hook is called after the [`remove()`](wix-data.html#remove)", + " is executed, it cannot prevent the item from being removed from the collection.", + " It can only affect the item returned by [`remove()`](wix-data.html#remove)." + ], + "links": [], + "examples": [ + { + "title": "An afterRemove hook", + "body": [ + "// 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\"", + " * }", + " */" + ], + "extra": {} + }, + { + "title": "Change the item returned by `remove()` using an afterRemove hook", + "body": [ + "// In data.js", + "", + "export function myCollection_afterUpdate(item, context) {", + " let hookContext = context; // see below", + "", + " // add a full_name property to the item being returned", + " item.full_name = item.first_name + \" \" + item.last_name;", + "", + " return item;", + "}", + "", + "/*", + " * hookContext:", + " *", + " * {", + " * \"collectionName\": \"myCollection\",", + " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", + " * \"userRole\": \"siteOwner\"", + " * }", + " */" + ], + "extra": {} + } + ], + "extra": {} + }, + "extra": {} + }, + { + "name": "afterUpdate", + "labels": [], + "nameParams": [], + "params": [ + { + "name": "item", + "type": "Object", + "doc": "The updated item." + }, + { + "name": "context", + "type": "DataHooks.UpdateHookContext", + "doc": "Contextual information about the hook." + } + ], + "ret": { + "type": [ + { + "name": "Promise", + "typeParams": [ + "Object" + ] + }, + "Object" + ], + "doc": "The item to return to [`update()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update) instead of the updated item.\n Returning a rejected promise will not block the operation, but will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." + }, + "locations": [ + { + "lineno": 254, + "filename": "hooks-standalone.js" + } + ], + "docs": { + "summary": "A hook that is triggered after an `update()` operation.", + "description": [ + "The `afterUpdate()` hook runs when:", + "", + " + The [`update()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update) function is called.", + " + An action is performed on a dataset that updates an item from the collection.", + " + An item is updated using the CMS.", + "", + " **Note**: When [scheduling an item's visibility change](https://support.wix.com/en/article/cms-controlling-live-site-item-visibility-from-your-collection#scheduling-changes-to-item-visibility), 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()`](https://dev.wix.com/docs/velo/api-reference/wix-data/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()`](#onFailure) hook if it has", + " been registered.", + "", + " Because the `afterUpdate` hook is called after the [`update()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update)", + " is executed, it cannot affect the item that is being updated in the collection.", + " It can only affect the item returned by [`update()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update)." + ], + "links": [], + "examples": [ + { + "title": "An afterUpdate hook", + "body": [ + "// 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\"", + " * }", + " */" + ], + "extra": {} + }, + { + "title": "Change the item returned by `update()` using an afterUpdate hook", + "body": [ + "// In data.js", + "", + "export function myCollection_afterUpdate(item, context) {", + " let hookContext = context; // see below", + " ", + " // add a full_name property to the item being returned", + " item.full_name = item.first_name + \" \" + item.last_name;", + " ", + " return item;", + "}", + "", + "/*", + " * hookContext:", + " *", + " * {", + " * \"collectionName\": \"myCollection\",", + " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", + " * \"userRole\": \"siteOwner\"", + " * }", + " */" + ], + "extra": {} + } + ], + "extra": {} + }, + "extra": {} + }, + { + "name": "beforeAggregate", + "labels": [ + "removed" + ], + "nameParams": [], + "params": [ + { + "name": "aggregate", + "type": "wix-data.WixDataAggregate", + "doc": "The original `WixDataAggregate` object." + }, + { + "name": "context", + "type": "DataHooks.UpdateHookContext", + "doc": "Contextual information about the hook." + } + ], + "ret": { + "type": [ + { + "name": "Promise", + "typeParams": [ + "wix-data.WixDataAggregate" + ] + }, + "wix-data.WixDataAggregate" + ], + "doc": "The aggregate object to run instead of the original object created by the `aggregate()` method.\n Returning a rejected promise blocks the operation, returns a rejected promise to the caller, and triggers the [`onFailure()`](#onFailure) hook." + }, + "locations": [ + { + "lineno": 292, + "filename": "hooks-standalone.js" + } + ], + "docs": { + "summary": "A hook triggered before an aggregation operation.", + "description": [ + "The `beforeAggregate()` hook runs when the [`aggregate()`](https://dev.wix.com/docs/velo/api-reference/wix-data/aggregate) is called, and allows you to modify the [`WixDataAggregate`](https://dev.wix.com/docs/velo/api-reference/wix-data/wix-data-aggregate/introduction) object before the aggregation operation runs. ", + "", + "", + " Return a [WixDataAggregate](https://dev.wix.com/docs/velo/api-reference/wix-data/wix-data-aggregate/introduction) object or a Promise that resolves to a [WixDataAggregate](https://dev.wix.com/docs/velo/api-reference/wix-data/wix-data-aggregate/introduction) object. The returned object is the aggregation that runs on the collection instead of the original aggregation created by the [`aggregate()`](https://dev.wix.com/docs/velo/api-reference/wix-data/aggregate) method.", + "", + " If the returned value is of the wrong type, the value is ignored.", + "", + " A rejected Promise blocks the call to [`aggregate()`](https://dev.wix.com/docs/velo/api-reference/wix-data/aggregate) and triggers the [`onFailure()`](#onFailure) hook, if it has been registered." + ], + "links": [], + "examples": [ + { + "title": "A `beforeAggregate` hook", + "body": [ + "// In data.js", + "", + "export function myCollection_beforeAggregate(aggregate, context) {", + " let hookContext = context; // see below", + "", + " // Some modification to the WixDataAggregate object.", + "", + " return aggregate;", + "}", + "", + "/*", + " * hookContext:", + " *", + " * {", + " * \"collectionName\": \"myCollection\",", + " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", + " * \"userRole\": \"siteOwner\"", + " * }", + " */" + ], + "extra": {} + }, + { + "title": "Change the `WixDataAggregate` object using a `beforeAggregate` hook", + "body": [ + "// In data.js", + "", + "export function myCollection_afterAggregate(aggregate, context) {", + " let hookContext = context; // see below", + "", + " // Add a filter to the aggregation object.", + " let newAggregate = aggregate.filter().le(\"population\", 2000000);", + "", + " return newAggregate;", + "}", + "", + "/*", + " * hookContext:", + " *", + " * {", + " * \"collectionName\": \"myCollection\",", + " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", + " * \"userRole\": \"siteOwner\"", + " * }", + " */" + ], + "extra": {} + } + ], + "extra": {} + }, + "extra": {} + }, + { + "name": "beforeCount", + "labels": [], + "nameParams": [], + "params": [ + { + "name": "query", + "type": "wix-data.WixDataQuery", + "doc": "The original query as defined by [`count()`](wix-data.WixDataQuery.html#count)." + }, + { + "name": "context", + "type": "DataHooks.HookContext", + "doc": "Contextual information about the hook." + } + ], + "ret": { + "type": [ + { + "name": "Promise", + "typeParams": [ + "wix-data.WixDataQuery" + ] + }, + "wix-data.WixDataQuery" + ], + "doc": "The `query` to be used for the [`count()`](wix-data.WixDataQuery.html#count) operation instead of the original query.\n Returning a rejected promise will block the operation and will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." + }, + "locations": [ + { + "lineno": 292, + "filename": "hooks-standalone.js" + } + ], + "docs": { + "summary": "A hook that is triggered before a `count()` operation.", + "description": [ + "The `beforeCount()` hook runs when:", + "", + " + The [`count()`](wix-data.WixDataQuery.html#count) function is called.", + " + The collection is viewed in the CMS.", + "", + "", + " 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()`](wix-data.WixDataQuery.html#count) operation.", + "", + " Often, you will modify the query that is received in the `query` parameter", + " by calling one or more [`WixDataQuery`](wix-data.WixDataQuery.html) functions.", + "", + " If the returned value is of the wrong type, the value is ignored.", + "", + " A rejected Promise blocks the call to [`count()`](wix-data.WixDataQuery.html#count)", + " and also calls the [`onFailure()`](#onFailure) hook if it has been registered.", + "", + " Because the `beforeCount()` hook is called before [`count()`](wix-data.WixDataQuery.html#count)", + " is executed, it can affect how items are counted or block the [`count()`](wix-data.WixDataQuery.html#count)." + ], + "links": [], + "examples": [ + { + "title": "A beforeCount hook", + "body": [ + "// 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\"", + " * }", + " */" + ], + "extra": {} + }, + { + "title": "Change the query used for the count, using a beforeCount hook", + "body": [ + "// 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\"", + " * }", + " */" + ], + "extra": {} + } + ], + "extra": {} + }, + "extra": {} + }, + { + "name": "beforeGet", + "labels": [], + "nameParams": [], + "params": [ + { + "name": "itemId", + "type": "string", + "doc": "The ID of the original item to be retrieved." + }, + { + "name": "context", + "type": "DataHooks.HookContext", + "doc": "Contextual information about the hook." + } + ], + "ret": { + "type": [ + { + "name": "Promise", + "typeParams": [ + "string" + ] + }, + "string" + ], + "doc": "The ID to be used for the [`get()`](wix-data.html#get) operation instead of the original `itemId` specified by the caller.\n Returning a rejected promise will block the operation and will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." + }, + "locations": [ + { + "lineno": 327, + "filename": "hooks-standalone.js" + } + ], + "docs": { + "summary": "A hook that is triggered before a `get()` operation.", + "description": [ + "The `beforeGet()` hook runs when the [`get()`](wix-data.html#get)", + " function is called.", + "", + " The hook does not run when the [`find`](wix-data.WixDataQuery.html#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()`](wix-data.html#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()`](wix-data.html#get)", + " and also calls the [`onFailure()`](#onFailure) hook if it has been registered.", + "", + " Because the `beforeGet()` hook is called before [`get()`](wix-data.html#get)", + " is executed, it can affect which item is retrieved", + " or block the [`get()`](wix-data.html#get)." + ], + "links": [], + "examples": [ + { + "title": "A beforeGet hook", + "body": [ + "// 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\"", + " * }", + " */" + ], + "extra": {} + }, + { + "title": "Change which item is retrieved using a beforeGet hook", + "body": [ + "// 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\"", + " * }", + " */" + ], + "extra": {} + } + ], + "extra": {} + }, + "extra": {} + }, + { + "name": "beforeInsert", + "labels": [], + "nameParams": [], + "params": [ + { + "name": "item", + "type": "Object", + "doc": "The original item to be inserted." + }, + { + "name": "context", + "type": "DataHooks.HookContext", + "doc": "Contextual information about the hook." + } + ], + "ret": { + "type": [ + { + "name": "Promise", + "typeParams": [ + "Object" + ] + }, + "Object" + ], + "doc": "The item to be inserted instead of the original item specified by the caller.\n Returning a rejected promise will block the operation and will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." + }, + "locations": [ + { + "lineno": 362, + "filename": "hooks-standalone.js" + } + ], + "docs": { + "summary": "A hook that is triggered before an `insert()` operation.", + "description": [ + "The `beforeInsert()` hook runs when:", + "", + " + The [`insert()`](wix-data.html#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 CMS.", + " + An item is imported into the Sandbox or Live collection.", + "", + "", + " 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()`](wix-data.html#insert) function.", + "", + " If the returned value is of the wrong type, the value is ignored.", + "", + " A rejected Promise blocks the call to [`insert()`](wix-data.html#insert)", + " and also calls the [`onFailure()`](#onFailure) hook if it has been registered.", + "", + " Because the `beforeInsert()` hook is called before [`insert()`](wix-data.html#insert)", + " is executed, it can affect the item that is inserted into the collection", + " or block the [`insert()`](wix-data.html#insert)." + ], + "links": [], + "examples": [ + { + "title": "A beforeInsert hook", + "body": [ + "// 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\"", + " * }", + " */" + ], + "extra": {} + }, + { + "title": "Change the item to insert using a beforeInsert hook", + "body": [ + "// 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\"", + " * }", + " */" + ], + "extra": {} + }, + { + "title": "Validate an email address field using a beforeInsert hook", + "body": [ + "// In data.js", + "", + "export function myCollection_beforeInsert(item, context) {", + " let hookContext = context; // see below", + "", + " //validate the email field and reject in case of failure", + " const emailRegex = /^\\w+([\\.-]?\\w+)*@\\w+([\\.-]?\\w+)*(\\.\\w{2,3})+$/;", + "", + " if (emailRegex.test(item.email)) {", + " return item;", + " } else {", + " return Promise.reject('Invalid email address.');", + " }", + "}", + "", + "/*", + " * hookContext:", + " *", + " * {", + " * \"collectionName\": \"myCollection\",", + " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", + " * \"userRole\": \"siteOwner\"", + " * }", + " */" + ], + "extra": {} + } + ], + "extra": {} + }, + "extra": {} + }, + { + "name": "beforeQuery", + "labels": [], + "nameParams": [], + "params": [ + { + "name": "query", + "type": "wix-data.WixDataQuery", + "doc": "The original query as specified by the caller." + }, + { + "name": "context", + "type": "DataHooks.HookContext", + "doc": "Contextual information about the hook." + } + ], + "ret": { + "type": [ + { + "name": "Promise", + "typeParams": [ + "wix-data.WixDataQuery" + ] + }, + "wix-data.WixDataQuery" + ], + "doc": "The query to use instead of the original query specified by the caller.\n Returning a rejected promise will block the operation and will return a rejected promise to the operation caller as well as trigger the [`onFailure()`](#onFailure) hook." + }, + "locations": [ + { + "lineno": 401, + "filename": "hooks-standalone.js" + } + ], + "docs": { + "summary": "A hook that is triggered before a `find()` operation.", + "description": [ + "The `beforeQuery()` hook runs when:", + "", + " + The [`find`](wix-data.WixDataQuery.html#find) function is called.", + " + An action is performed on a dataset that retrieves items from the collection.", + " + The collection is viewed in the CMS.", + " + An item is exported from the collection.", + "", + "", + " 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`](wix-data.WixDataQuery.html#find) operation.", + "", + " Often, you will modify the query that is received in the `query` parameter", + " by calling one or more [`WixDataQuery`](wix-data.WixDataQuery.html) functions.", + "", + " If the returned value is of the wrong type, the value is ignored.", + "", + " A rejected Promise blocks the call to [`find()`](wix-data.WixDataQuery.html#find)", + " and also calls the [`onFailure()`](#onFailure) hook if it has been registered.", + "", + " Because the `beforeQuery()` hook is called before [`find()`](wix-data.WixDataQuery.html#find)", + " is executed, it can affect the query that is used to retrieve items", + " or block the [`find()`](wix-data.WixDataQuery.html#find)." + ], + "links": [], + "examples": [ + { + "title": "A beforeQuery hook", + "body": [ + "// 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\"", + " * }", + " */" + ], + "extra": {} + }, + { + "title": "Change the query to be executed using the beforeQuery hook", + "body": [ + "// 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\"", + " * }", + " */" + ], + "extra": {} + } + ], + "extra": {} + }, + "extra": {} + }, + { + "name": "beforeRemove", + "labels": [], + "nameParams": [], + "params": [ + { + "name": "itemId", + "type": "string", + "doc": "The ID of the original item to be removed." + }, + { + "name": "context", + "type": "DataHooks.UpdateHookContext", + "doc": "Contextual information about the hook." + } + ], + "ret": { + "type": [ + { + "name": "Promise", + "typeParams": [ + "string" + ] + }, + "string" + ], + "doc": "The ID to be used for the [`remove()`](wix-data.html#remove) instead of the original `itemId` specified by the caller.\n Returning a rejected promise will block the operation and will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." + }, + "locations": [ + { + "lineno": 442, + "filename": "hooks-standalone.js" + } + ], + "docs": { + "summary": "A hook that is called before a `remove()` operation.", + "description": [ + "The `beforeRemove()` hook runs when:", + "", + " + The [`remove()`](wix-data.html#remove) function is called.", + " + An action is performed on a dataset that removes an item from the collection.", + " + An item is deleted using the CMS.", + "", + "", + " 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()`](wix-data.html#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()`](wix-data.html#remove)", + " and also calls the [`onFailure()`](#onFailure) hook if it has been registered.", + "", + " Because the `beforeRemove()` hook is called before [`remove()`](wix-data.html#remove)", + " is executed, it can affect the item that is removed from the collection", + " or block the [`remove()`](wix-data.html#remove)." + ], + "links": [], + "examples": [ + { + "title": "A beforeRemove hook", + "body": [ + "// 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\"", + " * }", + " */" + ], + "extra": {} + }, + { + "title": "Change the item to remove using a beforeRemove hook", + "body": [ + "// 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\"", + " * }", + " */" + ], + "extra": {} + } + ], + "extra": {} + }, + "extra": {} + }, + { + "name": "beforeUpdate", + "labels": [], + "nameParams": [], + "params": [ + { + "name": "item", + "type": "Object", + "doc": "The original item to be updated." + }, + { + "name": "context", + "type": "DataHooks.UpdateHookContext", + "doc": "Contextual information about the hook." + } + ], + "ret": { + "type": [ + { + "name": "Promise", + "typeParams": [ + "Object" + ] + }, + "Object" + ], + "doc": "The item to be updated instead of the original item specified by the caller.\n Returning a rejected promise will block the operation and will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." + }, + "locations": [ + { + "lineno": 480, + "filename": "hooks-standalone.js" + } + ], + "docs": { + "summary": "A hook that is triggered before an `update()` operation.", + "description": [ + "The `beforeUpdate()` hook runs when:", + "", + " + The [`update()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update) function is called.", + " + An action is performed on a dataset that updates an item from the collection.", + " + An item is updated using the CMS.", + "", + "", + " 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()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update) function.", + "", + " If the returned value is of the wrong type, the value is ignored.", + "", + " A rejected Promise blocks the call to [`update()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update)", + " and also calls the [`onFailure()`](#onFailure) hook if it has been registered.", + "", + " Because the `beforeUpdate()` hook is called before the [`update()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update)", + " is executed, it can affect the item that is updated in the collection", + " or block the [`update()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update)." + ], + "links": [], + "examples": [ + { + "title": "A beforeUpdate hook", + "body": [ + "// 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\"", + " * }", + " */" + ], + "extra": {} + }, + { + "title": "Change the item to update using a beforeUpdate hook", + "body": [ + "// 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\"", + " * }", + " */" + ], + "extra": {} + } + ], + "extra": {} + }, + "extra": {} + }, + { + "name": "onFailure", + "labels": [], + "nameParams": [], + "params": [ + { + "name": "error", + "type": "Error", + "doc": "The error that caused the failure." + }, + { + "name": "context", + "type": "DataHooks.HookContext", + "doc": "Contextual information about the hook." + } + ], + "ret": { + "type": { + "name": "Promise", + "typeParams": [ + "Object" + ] + }, + "doc": "Fulfilled - Returning a fulfilled promise will result in a fulfilled data operation with the provided result.\nRejected - Returning a rejected promise will result in returning a rejected promise to the caller of the data operation." + }, + "locations": [ + { + "lineno": 517, + "filename": "hooks-standalone.js" + } + ], + "docs": { + "summary": "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." + ], + "links": [], + "examples": [ + { + "title": "A hook triggered when a failure occurs", + "body": [ + "// 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", + " * }", + " */" + ], + "extra": {} + } + ], + "extra": {} + }, + "extra": {} + } + ], "callbacks": [], - "messages": - [ { "name": "HookContext", - "locations": - [ { "lineno": 1, - "filename": "hooks-standalone.js" } ], - "docs": - { "summary": "An object that contains contextual information about the hook being called.", - "links": [], - "examples": [], - "extra": - { } }, - "members": - [ { "name": "collectionName", - "type": "string", - "doc": "The ID of the collection the hook affects." }, - { "name": "userId", - "type": "string", - "doc": "The current site user ID. If no user is logged in to the site it may be null." }, - { "name": "userRole", - "type": "string", - "doc": "The permissions role of the current user. Possibilities are: `anonymous`, `siteMember`, and `siteOwner`." } ], - "extra": - { }, - "labels": [] }, - { "name": "UpdateHookContext", - "locations": - [ { "lineno": 10, - "filename": "hooks-standalone.js" } ], - "docs": - { "summary": "An object that contains contextual information when calling the `beforeUpdate()`, `beforeRemove()`, or `afterUpdate()` hooks.", - "links": [], - "examples": [], - "extra": - { } }, - "members": - [ { "name": "collectionName", - "type": "string", - "doc": "The ID of the collection the hook affects." }, - { "name": "userId", - "type": "string", - "doc": "The current site user ID. If no user is logged in to the site it may be null." }, - { "name": "userRole", - "type": "string", - "doc": "The permissions role of the current user. Possibilities are: `anonymous`, `siteMember`, and `siteOwner`." }, - { "name": "currentItem", - "type": "Object", - "doc": "The item stored in the database collection before an update or delete operation." } ], - "extra": - { }, - "labels": [] } ], - "extra": - { } } \ No newline at end of file + "messages": [ + { + "name": "HookContext", + "locations": [ + { + "lineno": 1, + "filename": "hooks-standalone.js" + } + ], + "docs": { + "summary": "An object that contains contextual information about the hook being called.", + "links": [], + "examples": [], + "extra": {} + }, + "members": [ + { + "name": "collectionName", + "type": "string", + "doc": "The ID of the collection the hook affects." + }, + { + "name": "userId", + "type": "string", + "doc": "The current site user ID. If no user is logged in to the site it may be null." + }, + { + "name": "userRole", + "type": "string", + "doc": "The permissions role of the current user. Possibilities are: `anonymous`, `siteMember`, and `siteOwner`." + } + ], + "extra": {}, + "labels": [] + }, + { + "name": "UpdateHookContext", + "locations": [ + { + "lineno": 10, + "filename": "hooks-standalone.js" + } + ], + "docs": { + "summary": "An object that contains contextual information when calling the `beforeUpdate()`, `beforeRemove()`, or `afterUpdate()` hooks.", + "links": [], + "examples": [], + "extra": {} + }, + "members": [ + { + "name": "collectionName", + "type": "string", + "doc": "The ID of the collection the hook affects." + }, + { + "name": "userId", + "type": "string", + "doc": "The current site user ID. If no user is logged in to the site it may be null." + }, + { + "name": "userRole", + "type": "string", + "doc": "The permissions role of the current user. Possibilities are: `anonymous`, `siteMember`, and `siteOwner`." + }, + { + "name": "currentItem", + "type": "Object", + "doc": "The item stored in the database collection before an update or delete operation." + } + ], + "extra": {}, + "labels": [] + } + ], + "extra": {} +} \ No newline at end of file From 5cba5d7b1106f71774725ee1c9de8bf8d87995fa Mon Sep 17 00:00:00 2001 From: Sam Markowitz Date: Tue, 22 Apr 2025 08:06:08 +0300 Subject: [PATCH 5/6] remove file --- wix-data/DataHooks.service.json | 1850 ------------------------------- 1 file changed, 1850 deletions(-) delete mode 100644 wix-data/DataHooks.service.json diff --git a/wix-data/DataHooks.service.json b/wix-data/DataHooks.service.json deleted file mode 100644 index e72e2f80b3..0000000000 --- a/wix-data/DataHooks.service.json +++ /dev/null @@ -1,1850 +0,0 @@ -{ - "name": "DataHooks", - "mixes": [], - "labels": [], - "location": { - "lineno": 20, - "filename": "hooks-standalone.js" - }, - "docs": { - "summary": "Hooks that can be added to wix-data operations.", - "description": [ - "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](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-blocks/about-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:", - "", - " ``` javascript", - " export function _() { }", - " ```", - " 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:", - " 1. Click the **Databases** button and hover over the relevant collection.", - " 1. Click the **Show More** icon.", - " 1. Select **Add/Remove Hooks**, and choose the hooks you want to add.", - " ![Adding a Hook](images/add_remove_hooks.png \"Add/Remove Hook\")" - ], - "links": [], - "examples": [], - "extra": {} - }, - "properties": [], - "operations": [ - { - "name": "afterAggregate", - "labels": [], - "nameParams": [], - "params": [ - { - "name": "item", - "type": "Object", - "doc": "The aggregation result item." - }, - { - "name": "context", - "type": "DataHooks.HookContext", - "doc": "Contextual information about the hook." - } - ], - "ret": { - "type": [ - { - "name": "Promise", - "typeParams": [ - "Object" - ] - }, - "Object" - ], - "doc": "The item to return to [`aggregate()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update) to replace the original aggregation result item.\n Returning a rejected promise returns a rejected promise to the caller and triggers the [`onFailure()`](#onFailure) hook without blocking the aggregation operation." - }, - "locations": [ - { - "lineno": 56, - "filename": "hooks-standalone.js" - } - ], - "docs": { - "summary": "A hook triggered after an aggregation operation.", - "description": [ - "The `afterAggregate()` hook allows you to modify the aggregation results before they are returned to the caller. The hook runs for each item in the `items` array within the [WixDataAggregateResult](https://dev.wix.com/docs/velo/api-reference/wix-data/wix-data-aggregate-result/introduction) object, after the aggregation operation finishes and before the [`aggregate()`](https://dev.wix.com/docs/velo/api-reference/wix-data/aggregate) method returns.", - "", - "Return an object or a Promise that resolves to an object. If the returned value is of the wrong type, it is ignored.", - "", - "If returning a Promise, the object is used as the result regardless of whether the Promise is fulfilled or rejected. A rejected Promise also triggers the [`onFailure()`](#onFailure) hook, if it has been registered." - ], - "links": [], - "examples": [ - { - "title": "An `afterAggregate()` hook", - "body": [ - "// In data.js", - "", - "export function myCollection_afterAggregate(item, context) {", - " let hookContext = context; // see below", - "", - " // Some modification to the aggregated item.", - "", - " return item;", - "}", - "", - "/*", - " * hookContext:", - " *", - " * {", - " * \"collectionName\": \"myCollection\",", - " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", - " * \"userRole\": \"siteOwner\"", - " * }", - " */" - ], - "extra": {} - }, - { - "title": "Change the item returned by `aggregate()` using an `afterAggregate()` hook", - "body": [ - "// In data.js", - "", - "export function myCollection_afterAggregate(item, context) {", - " let hookContext = context; // see below", - "", - " // Modify the value of an aggregated item's property:", - " item.populationMax += 1000;", - " ", - " return item;", - "}", - "", - "/*", - " * hookContext:", - " *", - " * {", - " * \"collectionName\": \"myCollection\",", - " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", - " * \"userRole\": \"siteOwner\"", - " * }", - " */" - ], - "extra": {} - } - ], - "extra": {} - }, - "extra": {} - }, - { - "name": "afterCount", - "labels": [], - "nameParams": [], - "params": [ - { - "name": "count", - "type": "number", - "doc": "The number of items the count operation has found." - }, - { - "name": "context", - "type": "DataHooks.HookContext", - "doc": "Contextual information about the hook." - } - ], - "ret": { - "type": [ - { - "name": "Promise", - "typeParams": [ - "number" - ] - }, - "number" - ], - "doc": "The count to return to [`count()`](wix-data.WixDataQuery.html#count) instead of the original count.\n Returning a rejected promise will not block the operation, but will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." - }, - "locations": [ - { - "lineno": 79, - "filename": "hooks-standalone.js" - } - ], - "docs": { - "summary": "A hook that is triggered after a `count()` operation.", - "description": [ - "The `afterCount()` hook runs when:", - "", - " + The [`count()`](wix-data.WixDataQuery.html#count) function is called.", - " + The collection is viewed in the CMS.", - "", - "", - " 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()`](wix-data.WixDataQuery.html#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()`](#onFailure) hook if it has", - " been registered." - ], - "links": [], - "examples": [ - { - "title": "An afterCount hook", - "body": [ - "// 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\"", - " * }", - " */" - ], - "extra": {} - }, - { - "title": "Change the number returned by `count()` using an afterCount hook", - "body": [ - "// In data.js", - "", - "export function myCollection_afterCount(count, context) {", - " let hookContext = context; // see below", - "", - " // return a value higher than the actual item count", - " count += 5;", - "", - " return count;", - "}", - "", - "/*", - " * hookContext:", - " *", - " * {", - " * \"collectionName\": \"myCollection\",", - " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", - " * \"userRole\": \"siteOwner\"", - " * }", - " */" - ], - "extra": {} - } - ], - "extra": {} - }, - "extra": {} - }, - { - "name": "afterGet", - "labels": [], - "nameParams": [], - "params": [ - { - "name": "item", - "type": "Object", - "doc": "The item that was retrieved from the collection." - }, - { - "name": "context", - "type": "DataHooks.HookContext", - "doc": "Contextual information about the hook." - } - ], - "ret": { - "type": [ - { - "name": "Promise", - "typeParams": [ - "Object" - ] - }, - "Object" - ], - "doc": "The item to return to [`get()`](wix-data.html#get) instead of the retrieved item.\n 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()`](#onFailure) hook." - }, - "locations": [ - { - "lineno": 110, - "filename": "hooks-standalone.js" - } - ], - "docs": { - "summary": "A hook that is triggered after a `get()` operation.", - "description": [ - "The `afterGet()` hook runs when the [`get()`](wix-data.html#get)", - " function is called.", - "", - " The hook does not run when the [`find`](wix-data.WixDataQuery.html#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()`](wix-data.html#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()`](#onFailure) hook if it has", - " been registered." - ], - "links": [], - "examples": [ - { - "title": "An afterGet hook", - "body": [ - "// 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\"", - " * }", - " */" - ], - "extra": {} - }, - { - "title": "Change the item returned by `get()` using an afterGet hook", - "body": [ - "// In data.js", - "", - "export function myCollection_afterGet(item, context) {", - " let hookContext = context; // see below", - "", - " // add a full_name property to the item being returned", - " item.full_name = item.first_name + \" \" + item.last_name;", - "", - " return item;", - "}", - "", - "/*", - " * hookContext:", - " *", - " * {", - " * \"collectionName\": \"myCollection\",", - " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", - " * \"userRole\": \"siteOwner\"", - " * }", - " */" - ], - "extra": {} - } - ], - "extra": {} - }, - "extra": {} - }, - { - "name": "afterInsert", - "labels": [], - "nameParams": [], - "params": [ - { - "name": "item", - "type": "Object", - "doc": "The item that was inserted." - }, - { - "name": "context", - "type": "DataHooks.HookContext", - "doc": "Contextual information about the hook." - } - ], - "ret": { - "type": [ - { - "name": "Promise", - "typeParams": [ - "Object" - ] - }, - "Object" - ], - "doc": "The item to return to [`insert()`](wix-data.html#insert) instead of the inserted item.\n Returning a rejected promise will not block the operation, but will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." - }, - "locations": [ - { - "lineno": 142, - "filename": "hooks-standalone.js" - } - ], - "docs": { - "summary": "A hook that is triggered after an `insert()` operation.", - "description": [ - "The `afterInsert()` hook runs when:", - "", - " + The [`insert()`](wix-data.html#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 CMS.", - " + An item is imported into the Sandbox or Live collection.", - "", - "", - " 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()`](wix-data.html#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()`](#onFailure) hook if it has", - " been registered.", - "", - " Because the `afterInsert` hook is called after the [`insert()`](wix-data.html#insert)", - " is executed, it cannot affect the item that is inserted into the collection.", - " It can only affect the item returned by [`insert()`](wix-data.html#insert)." - ], - "links": [], - "examples": [ - { - "title": "An afterInsert hook", - "body": [ - "// 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\"", - " * }", - " */" - ], - "extra": {} - }, - { - "title": "Change the item returned by `insert()` using an afterInsert hook", - "body": [ - "// In data.js", - "", - "export function myCollection_afterInsert(item, context) {", - " let hookContext = context; // see below", - "", - " //add a new property to the item being returned that aggregates the content from several fields into one", - " item.combinedSentence = `Customer: ${item.lastName}, ${item.firstName}: Purchases: ${item.purchases}, Item Returns: ${item.returns}`;", - "", - " return item;", - "}", - "", - "/*", - " * hookContext:", - " *", - " * {", - " * \"collectionName\": \"myCollection\",", - " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", - " * \"userRole\": \"siteOwner\"", - " * }", - " */" - ], - "extra": {} - } - ], - "extra": {} - }, - "extra": {} - }, - { - "name": "afterQuery", - "labels": [], - "nameParams": [], - "params": [ - { - "name": "item", - "type": "Object", - "doc": "One of the items of the query result. The hook is called for each item in the results." - }, - { - "name": "context", - "type": "DataHooks.HookContext", - "doc": "Contextual information about the hook." - } - ], - "ret": { - "type": [ - { - "name": "Promise", - "typeParams": [ - "Object" - ] - }, - "Object" - ], - "doc": "The item to return to [`find`](wix-data.WixDataQuery.html#find) instead of the item retrieved from the database.\n 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()`](#onFailure) hook." - }, - "locations": [ - { - "lineno": 179, - "filename": "hooks-standalone.js" - } - ], - "docs": { - "summary": "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`](wix-data.WixDataQuery.html#find) function is called.", - " + An action is performed on a dataset that retrieves items from the collection.", - " + The collection is viewed in the CMS.", - " + An item is exported from the collection.", - "", - "", - " 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`](wix-data.WixDataQuery.html#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()`](#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." - ], - "links": [], - "examples": [ - { - "title": "An afterQuery hook", - "body": [ - "// 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\"", - " * }", - " */" - ], - "extra": {} - }, - { - "title": "Change the item returned by `find()` using an afterQuery hook", - "body": [ - "// In data.js", - "", - "export function myCollection_afterQuery(item, context) {", - " let hookContext = context; // see below", - "", - " // add a full_name property to the item being returned", - " item.full_name = item.first_name + \" \" + item.last_name;", - "", - " return item;", - "}", - "", - "/*", - " * hookContext:", - " *", - " * {", - " * \"collectionName\": \"myCollection\",", - " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", - " * \"userRole\": \"siteOwner\"", - " * }", - " */" - ], - "extra": {} - } - ], - "extra": {} - }, - "extra": {} - }, - { - "name": "afterRemove", - "labels": [], - "nameParams": [], - "params": [ - { - "name": "item", - "type": "Object", - "doc": "The item that was removed." - }, - { - "name": "context", - "type": "DataHooks.HookContext", - "doc": "Contextual information about the hook." - } - ], - "ret": { - "type": [ - { - "name": "Promise", - "typeParams": [ - "Object" - ] - }, - "Object" - ], - "doc": "The item to return to [`remove()`](wix-data.html#remove) instead of the deleted item.\n Returning a rejected promise will not block the operation, but will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." - }, - "locations": [ - { - "lineno": 219, - "filename": "hooks-standalone.js" - } - ], - "docs": { - "summary": "A hook that is triggered after a `remove()` operation.", - "description": [ - "The `afterRemove()` hook runs when:", - "", - " + The [`remove()`](wix-data.html#remove) function is called.", - " + An action is performed on a dataset that removes an item from the collection.", - " + An item is deleted using the CMS.", - "", - "", - " 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()`](wix-data.html#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()`](#onFailure) hook if it has", - " been registered.", - "", - " Because the `afterRemove()` hook is called after the [`remove()`](wix-data.html#remove)", - " is executed, it cannot prevent the item from being removed from the collection.", - " It can only affect the item returned by [`remove()`](wix-data.html#remove)." - ], - "links": [], - "examples": [ - { - "title": "An afterRemove hook", - "body": [ - "// 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\"", - " * }", - " */" - ], - "extra": {} - }, - { - "title": "Change the item returned by `remove()` using an afterRemove hook", - "body": [ - "// In data.js", - "", - "export function myCollection_afterUpdate(item, context) {", - " let hookContext = context; // see below", - "", - " // add a full_name property to the item being returned", - " item.full_name = item.first_name + \" \" + item.last_name;", - "", - " return item;", - "}", - "", - "/*", - " * hookContext:", - " *", - " * {", - " * \"collectionName\": \"myCollection\",", - " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", - " * \"userRole\": \"siteOwner\"", - " * }", - " */" - ], - "extra": {} - } - ], - "extra": {} - }, - "extra": {} - }, - { - "name": "afterUpdate", - "labels": [], - "nameParams": [], - "params": [ - { - "name": "item", - "type": "Object", - "doc": "The updated item." - }, - { - "name": "context", - "type": "DataHooks.UpdateHookContext", - "doc": "Contextual information about the hook." - } - ], - "ret": { - "type": [ - { - "name": "Promise", - "typeParams": [ - "Object" - ] - }, - "Object" - ], - "doc": "The item to return to [`update()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update) instead of the updated item.\n Returning a rejected promise will not block the operation, but will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." - }, - "locations": [ - { - "lineno": 254, - "filename": "hooks-standalone.js" - } - ], - "docs": { - "summary": "A hook that is triggered after an `update()` operation.", - "description": [ - "The `afterUpdate()` hook runs when:", - "", - " + The [`update()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update) function is called.", - " + An action is performed on a dataset that updates an item from the collection.", - " + An item is updated using the CMS.", - "", - " **Note**: When [scheduling an item's visibility change](https://support.wix.com/en/article/cms-controlling-live-site-item-visibility-from-your-collection#scheduling-changes-to-item-visibility), 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()`](https://dev.wix.com/docs/velo/api-reference/wix-data/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()`](#onFailure) hook if it has", - " been registered.", - "", - " Because the `afterUpdate` hook is called after the [`update()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update)", - " is executed, it cannot affect the item that is being updated in the collection.", - " It can only affect the item returned by [`update()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update)." - ], - "links": [], - "examples": [ - { - "title": "An afterUpdate hook", - "body": [ - "// 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\"", - " * }", - " */" - ], - "extra": {} - }, - { - "title": "Change the item returned by `update()` using an afterUpdate hook", - "body": [ - "// In data.js", - "", - "export function myCollection_afterUpdate(item, context) {", - " let hookContext = context; // see below", - " ", - " // add a full_name property to the item being returned", - " item.full_name = item.first_name + \" \" + item.last_name;", - " ", - " return item;", - "}", - "", - "/*", - " * hookContext:", - " *", - " * {", - " * \"collectionName\": \"myCollection\",", - " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", - " * \"userRole\": \"siteOwner\"", - " * }", - " */" - ], - "extra": {} - } - ], - "extra": {} - }, - "extra": {} - }, - { - "name": "beforeAggregate", - "labels": [ - "removed" - ], - "nameParams": [], - "params": [ - { - "name": "aggregate", - "type": "wix-data.WixDataAggregate", - "doc": "The original `WixDataAggregate` object." - }, - { - "name": "context", - "type": "DataHooks.UpdateHookContext", - "doc": "Contextual information about the hook." - } - ], - "ret": { - "type": [ - { - "name": "Promise", - "typeParams": [ - "wix-data.WixDataAggregate" - ] - }, - "wix-data.WixDataAggregate" - ], - "doc": "The aggregate object to run instead of the original object created by the `aggregate()` method.\n Returning a rejected promise blocks the operation, returns a rejected promise to the caller, and triggers the [`onFailure()`](#onFailure) hook." - }, - "locations": [ - { - "lineno": 292, - "filename": "hooks-standalone.js" - } - ], - "docs": { - "summary": "A hook triggered before an aggregation operation.", - "description": [ - "The `beforeAggregate()` hook runs when the [`aggregate()`](https://dev.wix.com/docs/velo/api-reference/wix-data/aggregate) is called, and allows you to modify the [`WixDataAggregate`](https://dev.wix.com/docs/velo/api-reference/wix-data/wix-data-aggregate/introduction) object before the aggregation operation runs. ", - "", - "", - " Return a [WixDataAggregate](https://dev.wix.com/docs/velo/api-reference/wix-data/wix-data-aggregate/introduction) object or a Promise that resolves to a [WixDataAggregate](https://dev.wix.com/docs/velo/api-reference/wix-data/wix-data-aggregate/introduction) object. The returned object is the aggregation that runs on the collection instead of the original aggregation created by the [`aggregate()`](https://dev.wix.com/docs/velo/api-reference/wix-data/aggregate) method.", - "", - " If the returned value is of the wrong type, the value is ignored.", - "", - " A rejected Promise blocks the call to [`aggregate()`](https://dev.wix.com/docs/velo/api-reference/wix-data/aggregate) and triggers the [`onFailure()`](#onFailure) hook, if it has been registered." - ], - "links": [], - "examples": [ - { - "title": "A `beforeAggregate` hook", - "body": [ - "// In data.js", - "", - "export function myCollection_beforeAggregate(aggregate, context) {", - " let hookContext = context; // see below", - "", - " // Some modification to the WixDataAggregate object.", - "", - " return aggregate;", - "}", - "", - "/*", - " * hookContext:", - " *", - " * {", - " * \"collectionName\": \"myCollection\",", - " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", - " * \"userRole\": \"siteOwner\"", - " * }", - " */" - ], - "extra": {} - }, - { - "title": "Change the `WixDataAggregate` object using a `beforeAggregate` hook", - "body": [ - "// In data.js", - "", - "export function myCollection_afterAggregate(aggregate, context) {", - " let hookContext = context; // see below", - "", - " // Add a filter to the aggregation object.", - " let newAggregate = aggregate.filter().le(\"population\", 2000000);", - "", - " return newAggregate;", - "}", - "", - "/*", - " * hookContext:", - " *", - " * {", - " * \"collectionName\": \"myCollection\",", - " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", - " * \"userRole\": \"siteOwner\"", - " * }", - " */" - ], - "extra": {} - } - ], - "extra": {} - }, - "extra": {} - }, - { - "name": "beforeCount", - "labels": [], - "nameParams": [], - "params": [ - { - "name": "query", - "type": "wix-data.WixDataQuery", - "doc": "The original query as defined by [`count()`](wix-data.WixDataQuery.html#count)." - }, - { - "name": "context", - "type": "DataHooks.HookContext", - "doc": "Contextual information about the hook." - } - ], - "ret": { - "type": [ - { - "name": "Promise", - "typeParams": [ - "wix-data.WixDataQuery" - ] - }, - "wix-data.WixDataQuery" - ], - "doc": "The `query` to be used for the [`count()`](wix-data.WixDataQuery.html#count) operation instead of the original query.\n Returning a rejected promise will block the operation and will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." - }, - "locations": [ - { - "lineno": 292, - "filename": "hooks-standalone.js" - } - ], - "docs": { - "summary": "A hook that is triggered before a `count()` operation.", - "description": [ - "The `beforeCount()` hook runs when:", - "", - " + The [`count()`](wix-data.WixDataQuery.html#count) function is called.", - " + The collection is viewed in the CMS.", - "", - "", - " 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()`](wix-data.WixDataQuery.html#count) operation.", - "", - " Often, you will modify the query that is received in the `query` parameter", - " by calling one or more [`WixDataQuery`](wix-data.WixDataQuery.html) functions.", - "", - " If the returned value is of the wrong type, the value is ignored.", - "", - " A rejected Promise blocks the call to [`count()`](wix-data.WixDataQuery.html#count)", - " and also calls the [`onFailure()`](#onFailure) hook if it has been registered.", - "", - " Because the `beforeCount()` hook is called before [`count()`](wix-data.WixDataQuery.html#count)", - " is executed, it can affect how items are counted or block the [`count()`](wix-data.WixDataQuery.html#count)." - ], - "links": [], - "examples": [ - { - "title": "A beforeCount hook", - "body": [ - "// 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\"", - " * }", - " */" - ], - "extra": {} - }, - { - "title": "Change the query used for the count, using a beforeCount hook", - "body": [ - "// 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\"", - " * }", - " */" - ], - "extra": {} - } - ], - "extra": {} - }, - "extra": {} - }, - { - "name": "beforeGet", - "labels": [], - "nameParams": [], - "params": [ - { - "name": "itemId", - "type": "string", - "doc": "The ID of the original item to be retrieved." - }, - { - "name": "context", - "type": "DataHooks.HookContext", - "doc": "Contextual information about the hook." - } - ], - "ret": { - "type": [ - { - "name": "Promise", - "typeParams": [ - "string" - ] - }, - "string" - ], - "doc": "The ID to be used for the [`get()`](wix-data.html#get) operation instead of the original `itemId` specified by the caller.\n Returning a rejected promise will block the operation and will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." - }, - "locations": [ - { - "lineno": 327, - "filename": "hooks-standalone.js" - } - ], - "docs": { - "summary": "A hook that is triggered before a `get()` operation.", - "description": [ - "The `beforeGet()` hook runs when the [`get()`](wix-data.html#get)", - " function is called.", - "", - " The hook does not run when the [`find`](wix-data.WixDataQuery.html#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()`](wix-data.html#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()`](wix-data.html#get)", - " and also calls the [`onFailure()`](#onFailure) hook if it has been registered.", - "", - " Because the `beforeGet()` hook is called before [`get()`](wix-data.html#get)", - " is executed, it can affect which item is retrieved", - " or block the [`get()`](wix-data.html#get)." - ], - "links": [], - "examples": [ - { - "title": "A beforeGet hook", - "body": [ - "// 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\"", - " * }", - " */" - ], - "extra": {} - }, - { - "title": "Change which item is retrieved using a beforeGet hook", - "body": [ - "// 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\"", - " * }", - " */" - ], - "extra": {} - } - ], - "extra": {} - }, - "extra": {} - }, - { - "name": "beforeInsert", - "labels": [], - "nameParams": [], - "params": [ - { - "name": "item", - "type": "Object", - "doc": "The original item to be inserted." - }, - { - "name": "context", - "type": "DataHooks.HookContext", - "doc": "Contextual information about the hook." - } - ], - "ret": { - "type": [ - { - "name": "Promise", - "typeParams": [ - "Object" - ] - }, - "Object" - ], - "doc": "The item to be inserted instead of the original item specified by the caller.\n Returning a rejected promise will block the operation and will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." - }, - "locations": [ - { - "lineno": 362, - "filename": "hooks-standalone.js" - } - ], - "docs": { - "summary": "A hook that is triggered before an `insert()` operation.", - "description": [ - "The `beforeInsert()` hook runs when:", - "", - " + The [`insert()`](wix-data.html#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 CMS.", - " + An item is imported into the Sandbox or Live collection.", - "", - "", - " 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()`](wix-data.html#insert) function.", - "", - " If the returned value is of the wrong type, the value is ignored.", - "", - " A rejected Promise blocks the call to [`insert()`](wix-data.html#insert)", - " and also calls the [`onFailure()`](#onFailure) hook if it has been registered.", - "", - " Because the `beforeInsert()` hook is called before [`insert()`](wix-data.html#insert)", - " is executed, it can affect the item that is inserted into the collection", - " or block the [`insert()`](wix-data.html#insert)." - ], - "links": [], - "examples": [ - { - "title": "A beforeInsert hook", - "body": [ - "// 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\"", - " * }", - " */" - ], - "extra": {} - }, - { - "title": "Change the item to insert using a beforeInsert hook", - "body": [ - "// 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\"", - " * }", - " */" - ], - "extra": {} - }, - { - "title": "Validate an email address field using a beforeInsert hook", - "body": [ - "// In data.js", - "", - "export function myCollection_beforeInsert(item, context) {", - " let hookContext = context; // see below", - "", - " //validate the email field and reject in case of failure", - " const emailRegex = /^\\w+([\\.-]?\\w+)*@\\w+([\\.-]?\\w+)*(\\.\\w{2,3})+$/;", - "", - " if (emailRegex.test(item.email)) {", - " return item;", - " } else {", - " return Promise.reject('Invalid email address.');", - " }", - "}", - "", - "/*", - " * hookContext:", - " *", - " * {", - " * \"collectionName\": \"myCollection\",", - " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", - " * \"userRole\": \"siteOwner\"", - " * }", - " */" - ], - "extra": {} - } - ], - "extra": {} - }, - "extra": {} - }, - { - "name": "beforeQuery", - "labels": [], - "nameParams": [], - "params": [ - { - "name": "query", - "type": "wix-data.WixDataQuery", - "doc": "The original query as specified by the caller." - }, - { - "name": "context", - "type": "DataHooks.HookContext", - "doc": "Contextual information about the hook." - } - ], - "ret": { - "type": [ - { - "name": "Promise", - "typeParams": [ - "wix-data.WixDataQuery" - ] - }, - "wix-data.WixDataQuery" - ], - "doc": "The query to use instead of the original query specified by the caller.\n Returning a rejected promise will block the operation and will return a rejected promise to the operation caller as well as trigger the [`onFailure()`](#onFailure) hook." - }, - "locations": [ - { - "lineno": 401, - "filename": "hooks-standalone.js" - } - ], - "docs": { - "summary": "A hook that is triggered before a `find()` operation.", - "description": [ - "The `beforeQuery()` hook runs when:", - "", - " + The [`find`](wix-data.WixDataQuery.html#find) function is called.", - " + An action is performed on a dataset that retrieves items from the collection.", - " + The collection is viewed in the CMS.", - " + An item is exported from the collection.", - "", - "", - " 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`](wix-data.WixDataQuery.html#find) operation.", - "", - " Often, you will modify the query that is received in the `query` parameter", - " by calling one or more [`WixDataQuery`](wix-data.WixDataQuery.html) functions.", - "", - " If the returned value is of the wrong type, the value is ignored.", - "", - " A rejected Promise blocks the call to [`find()`](wix-data.WixDataQuery.html#find)", - " and also calls the [`onFailure()`](#onFailure) hook if it has been registered.", - "", - " Because the `beforeQuery()` hook is called before [`find()`](wix-data.WixDataQuery.html#find)", - " is executed, it can affect the query that is used to retrieve items", - " or block the [`find()`](wix-data.WixDataQuery.html#find)." - ], - "links": [], - "examples": [ - { - "title": "A beforeQuery hook", - "body": [ - "// 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\"", - " * }", - " */" - ], - "extra": {} - }, - { - "title": "Change the query to be executed using the beforeQuery hook", - "body": [ - "// 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\"", - " * }", - " */" - ], - "extra": {} - } - ], - "extra": {} - }, - "extra": {} - }, - { - "name": "beforeRemove", - "labels": [], - "nameParams": [], - "params": [ - { - "name": "itemId", - "type": "string", - "doc": "The ID of the original item to be removed." - }, - { - "name": "context", - "type": "DataHooks.UpdateHookContext", - "doc": "Contextual information about the hook." - } - ], - "ret": { - "type": [ - { - "name": "Promise", - "typeParams": [ - "string" - ] - }, - "string" - ], - "doc": "The ID to be used for the [`remove()`](wix-data.html#remove) instead of the original `itemId` specified by the caller.\n Returning a rejected promise will block the operation and will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." - }, - "locations": [ - { - "lineno": 442, - "filename": "hooks-standalone.js" - } - ], - "docs": { - "summary": "A hook that is called before a `remove()` operation.", - "description": [ - "The `beforeRemove()` hook runs when:", - "", - " + The [`remove()`](wix-data.html#remove) function is called.", - " + An action is performed on a dataset that removes an item from the collection.", - " + An item is deleted using the CMS.", - "", - "", - " 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()`](wix-data.html#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()`](wix-data.html#remove)", - " and also calls the [`onFailure()`](#onFailure) hook if it has been registered.", - "", - " Because the `beforeRemove()` hook is called before [`remove()`](wix-data.html#remove)", - " is executed, it can affect the item that is removed from the collection", - " or block the [`remove()`](wix-data.html#remove)." - ], - "links": [], - "examples": [ - { - "title": "A beforeRemove hook", - "body": [ - "// 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\"", - " * }", - " */" - ], - "extra": {} - }, - { - "title": "Change the item to remove using a beforeRemove hook", - "body": [ - "// 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\"", - " * }", - " */" - ], - "extra": {} - } - ], - "extra": {} - }, - "extra": {} - }, - { - "name": "beforeUpdate", - "labels": [], - "nameParams": [], - "params": [ - { - "name": "item", - "type": "Object", - "doc": "The original item to be updated." - }, - { - "name": "context", - "type": "DataHooks.UpdateHookContext", - "doc": "Contextual information about the hook." - } - ], - "ret": { - "type": [ - { - "name": "Promise", - "typeParams": [ - "Object" - ] - }, - "Object" - ], - "doc": "The item to be updated instead of the original item specified by the caller.\n Returning a rejected promise will block the operation and will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." - }, - "locations": [ - { - "lineno": 480, - "filename": "hooks-standalone.js" - } - ], - "docs": { - "summary": "A hook that is triggered before an `update()` operation.", - "description": [ - "The `beforeUpdate()` hook runs when:", - "", - " + The [`update()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update) function is called.", - " + An action is performed on a dataset that updates an item from the collection.", - " + An item is updated using the CMS.", - "", - "", - " 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()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update) function.", - "", - " If the returned value is of the wrong type, the value is ignored.", - "", - " A rejected Promise blocks the call to [`update()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update)", - " and also calls the [`onFailure()`](#onFailure) hook if it has been registered.", - "", - " Because the `beforeUpdate()` hook is called before the [`update()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update)", - " is executed, it can affect the item that is updated in the collection", - " or block the [`update()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update)." - ], - "links": [], - "examples": [ - { - "title": "A beforeUpdate hook", - "body": [ - "// 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\"", - " * }", - " */" - ], - "extra": {} - }, - { - "title": "Change the item to update using a beforeUpdate hook", - "body": [ - "// 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\"", - " * }", - " */" - ], - "extra": {} - } - ], - "extra": {} - }, - "extra": {} - }, - { - "name": "onFailure", - "labels": [], - "nameParams": [], - "params": [ - { - "name": "error", - "type": "Error", - "doc": "The error that caused the failure." - }, - { - "name": "context", - "type": "DataHooks.HookContext", - "doc": "Contextual information about the hook." - } - ], - "ret": { - "type": { - "name": "Promise", - "typeParams": [ - "Object" - ] - }, - "doc": "Fulfilled - Returning a fulfilled promise will result in a fulfilled data operation with the provided result.\nRejected - Returning a rejected promise will result in returning a rejected promise to the caller of the data operation." - }, - "locations": [ - { - "lineno": 517, - "filename": "hooks-standalone.js" - } - ], - "docs": { - "summary": "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." - ], - "links": [], - "examples": [ - { - "title": "A hook triggered when a failure occurs", - "body": [ - "// 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", - " * }", - " */" - ], - "extra": {} - } - ], - "extra": {} - }, - "extra": {} - } - ], - "callbacks": [], - "messages": [ - { - "name": "HookContext", - "locations": [ - { - "lineno": 1, - "filename": "hooks-standalone.js" - } - ], - "docs": { - "summary": "An object that contains contextual information about the hook being called.", - "links": [], - "examples": [], - "extra": {} - }, - "members": [ - { - "name": "collectionName", - "type": "string", - "doc": "The ID of the collection the hook affects." - }, - { - "name": "userId", - "type": "string", - "doc": "The current site user ID. If no user is logged in to the site it may be null." - }, - { - "name": "userRole", - "type": "string", - "doc": "The permissions role of the current user. Possibilities are: `anonymous`, `siteMember`, and `siteOwner`." - } - ], - "extra": {}, - "labels": [] - }, - { - "name": "UpdateHookContext", - "locations": [ - { - "lineno": 10, - "filename": "hooks-standalone.js" - } - ], - "docs": { - "summary": "An object that contains contextual information when calling the `beforeUpdate()`, `beforeRemove()`, or `afterUpdate()` hooks.", - "links": [], - "examples": [], - "extra": {} - }, - "members": [ - { - "name": "collectionName", - "type": "string", - "doc": "The ID of the collection the hook affects." - }, - { - "name": "userId", - "type": "string", - "doc": "The current site user ID. If no user is logged in to the site it may be null." - }, - { - "name": "userRole", - "type": "string", - "doc": "The permissions role of the current user. Possibilities are: `anonymous`, `siteMember`, and `siteOwner`." - }, - { - "name": "currentItem", - "type": "Object", - "doc": "The item stored in the database collection before an update or delete operation." - } - ], - "extra": {}, - "labels": [] - } - ], - "extra": {} -} \ No newline at end of file From 4b0533141e9270d0237e1c911cc92a4f9ea03181 Mon Sep 17 00:00:00 2001 From: Sam Markowitz Date: Tue, 22 Apr 2025 08:08:45 +0300 Subject: [PATCH 6/6] revert to master --- wix-data/DataHooks.service.json | 1522 +++++++++++++++++++++++++++++++ 1 file changed, 1522 insertions(+) create mode 100644 wix-data/DataHooks.service.json diff --git a/wix-data/DataHooks.service.json b/wix-data/DataHooks.service.json new file mode 100644 index 0000000000..66417a6874 --- /dev/null +++ b/wix-data/DataHooks.service.json @@ -0,0 +1,1522 @@ +{ "name": "DataHooks", + "mixes": [], + "labels": [], + "location": + { "lineno": 20, + "filename": "hooks-standalone.js" }, + "docs": + { "summary": "Hooks that can be added to wix-data operations.", + "description": + [ "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](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-blocks/about-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:", + "", + " ``` javascript", + " export function _() { }", + " ```", + " 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:", + " 1. Click the **Databases** button and hover over the relevant collection.", + " 1. Click the **Show More** icon.", + " 1. Select **Add/Remove Hooks**, and choose the hooks you want to add.", + " ![Adding a Hook](images/add_remove_hooks.png \"Add/Remove Hook\")" ], + "links": [], + "examples": [], + "extra": + { } }, + "properties": [], + "operations": + [ { "name": "afterAggregate", + "labels": [], + "nameParams": [], + "params": + [ { "name": "item", + "type": "Object", + "doc": "The aggregation result item." }, + { "name": "context", + "type": "DataHooks.HookContext", + "doc": "Contextual information about the hook." } ], + "ret": + { "type": + [ { "name": "Promise", + "typeParams": + [ "Object" ] }, + "Object" ], + "doc": "The item to return to [`aggregate()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update) to replace the original aggregation result item.\n Returning a rejected promise returns a rejected promise to the caller and triggers the [`onFailure()`](#onFailure) hook without blocking the aggregation operation." }, + "locations": + [ { "lineno": 56, + "filename": "hooks-standalone.js" } ], + "docs": + { "summary": "A hook triggered after an aggregation operation.", + "description": + [ "The `afterAggregate()` hook allows you to modify the aggregation results before they are returned to the caller. The hook runs for each item in the `items` array within the [WixDataAggregateResult](https://dev.wix.com/docs/velo/api-reference/wix-data/wix-data-aggregate-result/introduction) object, after the aggregation operation finishes and before the [`aggregate()`](https://dev.wix.com/docs/velo/api-reference/wix-data/aggregate) method returns.", + "", + "Return an object or a Promise that resolves to an object. If the returned value is of the wrong type, it is ignored.", + "", + "If returning a Promise, the object is used as the result regardless of whether the Promise is fulfilled or rejected. A rejected Promise also triggers the [`onFailure()`](#onFailure) hook, if it has been registered." ], + "links": [], + "examples": + [ { "title": "An `afterAggregate()` hook", + "body": + [ "// In data.js", + "", + "export function myCollection_afterAggregate(item, context) {", + " let hookContext = context; // see below", + "", + " // Some modification to the aggregated item.", + "", + " return item;", + "}", + "", + "/*", + " * hookContext:", + " *", + " * {", + " * \"collectionName\": \"myCollection\",", + " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", + " * \"userRole\": \"siteOwner\"", + " * }", + " */" ], + "extra": + { } }, + { "title": "Change the item returned by `aggregate()` using an `afterAggregate()` hook", + "body": + [ "// In data.js", + "", + "export function myCollection_afterAggregate(item, context) {", + " let hookContext = context; // see below", + "", + " // Modify the value of an aggregated item's property:", + " item.populationMax += 1000;", + " ", + " return item;", + "}", + "", + "/*", + " * hookContext:", + " *", + " * {", + " * \"collectionName\": \"myCollection\",", + " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", + " * \"userRole\": \"siteOwner\"", + " * }", + " */" ], + "extra": + { } } ], + "extra": + { } }, + "extra": + { } }, + { "name": "afterCount", + "labels": [], + "nameParams": [], + "params": + [ { "name": "count", + "type": "number", + "doc": "The number of items the count operation has found." }, + { "name": "context", + "type": "DataHooks.HookContext", + "doc": "Contextual information about the hook." } ], + "ret": + { "type": + [ { "name": "Promise", + "typeParams": + [ "number" ] }, + "number" ], + "doc": "The count to return to [`count()`](wix-data.WixDataQuery.html#count) instead of the original count.\n Returning a rejected promise will not block the operation, but will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." }, + "locations": + [ { "lineno": 79, + "filename": "hooks-standalone.js" } ], + "docs": + { "summary": "A hook that is triggered after a `count()` operation.", + "description": + [ "The `afterCount()` hook runs when:", + "", + " + The [`count()`](wix-data.WixDataQuery.html#count) function is called.", + " + The collection is viewed in the CMS.", + "", + "", + " 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()`](wix-data.WixDataQuery.html#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()`](#onFailure) hook if it has", + " been registered." ], + "links": [], + "examples": + [ { "title": "An afterCount hook", + "body": + [ "// 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\"", + " * }", + " */" ], + "extra": + { } }, + { "title": "Change the number returned by `count()` using an afterCount hook", + "body": + [ "// In data.js", + "", + "export function myCollection_afterCount(count, context) {", + " let hookContext = context; // see below", + "", + " // return a value higher than the actual item count", + " count += 5;", + "", + " return count;", + "}", + "", + "/*", + " * hookContext:", + " *", + " * {", + " * \"collectionName\": \"myCollection\",", + " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", + " * \"userRole\": \"siteOwner\"", + " * }", + " */" ], + "extra": + { } } ], + "extra": + { } }, + "extra": + { } }, + { "name": "afterGet", + "labels": [], + "nameParams": [], + "params": + [ { "name": "item", + "type": "Object", + "doc": "The item that was retrieved from the collection." }, + { "name": "context", + "type": "DataHooks.HookContext", + "doc": "Contextual information about the hook." } ], + "ret": + { "type": + [ { "name": "Promise", + "typeParams": + [ "Object" ] }, + "Object" ], + "doc": "The item to return to [`get()`](wix-data.html#get) instead of the retrieved item.\n 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()`](#onFailure) hook." }, + "locations": + [ { "lineno": 110, + "filename": "hooks-standalone.js" } ], + "docs": + { "summary": "A hook that is triggered after a `get()` operation.", + "description": + [ "The `afterGet()` hook runs when the [`get()`](wix-data.html#get)", + " function is called.", + "", + " The hook does not run when the [`find`](wix-data.WixDataQuery.html#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()`](wix-data.html#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()`](#onFailure) hook if it has", + " been registered." ], + "links": [], + "examples": + [ { "title": "An afterGet hook", + "body": + [ "// 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\"", + " * }", + " */" ], + "extra": + { } }, + { "title": "Change the item returned by `get()` using an afterGet hook", + "body": + [ "// In data.js", + "", + "export function myCollection_afterGet(item, context) {", + " let hookContext = context; // see below", + "", + " // add a full_name property to the item being returned", + " item.full_name = item.first_name + \" \" + item.last_name;", + "", + " return item;", + "}", + "", + "/*", + " * hookContext:", + " *", + " * {", + " * \"collectionName\": \"myCollection\",", + " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", + " * \"userRole\": \"siteOwner\"", + " * }", + " */" ], + "extra": + { } } ], + "extra": + { } }, + "extra": + { } }, + { "name": "afterInsert", + "labels": [], + "nameParams": [], + "params": + [ { "name": "item", + "type": "Object", + "doc": "The item that was inserted." }, + { "name": "context", + "type": "DataHooks.HookContext", + "doc": "Contextual information about the hook." } ], + "ret": + { "type": + [ { "name": "Promise", + "typeParams": + [ "Object" ] }, + "Object" ], + "doc": "The item to return to [`insert()`](wix-data.html#insert) instead of the inserted item.\n Returning a rejected promise will not block the operation, but will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." }, + "locations": + [ { "lineno": 142, + "filename": "hooks-standalone.js" } ], + "docs": + { "summary": "A hook that is triggered after an `insert()` operation.", + "description": + [ "The `afterInsert()` hook runs when:", + "", + " + The [`insert()`](wix-data.html#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 CMS.", + " + An item is imported into the Sandbox or Live collection.", + "", + "", + " 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()`](wix-data.html#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()`](#onFailure) hook if it has", + " been registered.", + "", + " Because the `afterInsert` hook is called after the [`insert()`](wix-data.html#insert)", + " is executed, it cannot affect the item that is inserted into the collection.", + " It can only affect the item returned by [`insert()`](wix-data.html#insert)." ], + "links": [], + "examples": + [ { "title": "An afterInsert hook", + "body": + [ "// 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\"", + " * }", + " */" ], + "extra": + { } }, + { "title": "Change the item returned by `insert()` using an afterInsert hook", + "body": + [ "// In data.js", + "", + "export function myCollection_afterInsert(item, context) {", + " let hookContext = context; // see below", + "", + " //add a new property to the item being returned that aggregates the content from several fields into one", + " item.combinedSentence = `Customer: ${item.lastName}, ${item.firstName}: Purchases: ${item.purchases}, Item Returns: ${item.returns}`;", + "", + " return item;", + "}", + "", + "/*", + " * hookContext:", + " *", + " * {", + " * \"collectionName\": \"myCollection\",", + " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", + " * \"userRole\": \"siteOwner\"", + " * }", + " */" ], + "extra": + { } } ], + "extra": + { } }, + "extra": + { } }, + { "name": "afterQuery", + "labels": [], + "nameParams": [], + "params": + [ { "name": "item", + "type": "Object", + "doc": "One of the items of the query result. The hook is called for each item in the results." }, + { "name": "context", + "type": "DataHooks.HookContext", + "doc": "Contextual information about the hook." } ], + "ret": + { "type": + [ { "name": "Promise", + "typeParams": + [ "Object" ] }, + "Object" ], + "doc": "The item to return to [`find`](wix-data.WixDataQuery.html#find) instead of the item retrieved from the database.\n 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()`](#onFailure) hook." }, + "locations": + [ { "lineno": 179, + "filename": "hooks-standalone.js" } ], + "docs": + { "summary": "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`](wix-data.WixDataQuery.html#find) function is called.", + " + An action is performed on a dataset that retrieves items from the collection.", + " + The collection is viewed in the CMS.", + " + An item is exported from the collection.", + "", + "", + " 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`](wix-data.WixDataQuery.html#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()`](#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." ], + "links": [], + "examples": + [ { "title": "An afterQuery hook", + "body": + [ "// 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\"", + " * }", + " */" ], + "extra": + { } }, + { "title": "Change the item returned by `find()` using an afterQuery hook", + "body": + [ "// In data.js", + "", + "export function myCollection_afterQuery(item, context) {", + " let hookContext = context; // see below", + "", + " // add a full_name property to the item being returned", + " item.full_name = item.first_name + \" \" + item.last_name;", + "", + " return item;", + "}", + "", + "/*", + " * hookContext:", + " *", + " * {", + " * \"collectionName\": \"myCollection\",", + " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", + " * \"userRole\": \"siteOwner\"", + " * }", + " */" ], + "extra": + { } } ], + "extra": + { } }, + "extra": + { } }, + { "name": "afterRemove", + "labels": [], + "nameParams": [], + "params": + [ { "name": "item", + "type": "Object", + "doc": "The item that was removed." }, + { "name": "context", + "type": "DataHooks.HookContext", + "doc": "Contextual information about the hook." } ], + "ret": + { "type": + [ { "name": "Promise", + "typeParams": + [ "Object" ] }, + "Object" ], + "doc": "The item to return to [`remove()`](wix-data.html#remove) instead of the deleted item.\n Returning a rejected promise will not block the operation, but will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." }, + "locations": + [ { "lineno": 219, + "filename": "hooks-standalone.js" } ], + "docs": + { "summary": "A hook that is triggered after a `remove()` operation.", + "description": + [ "The `afterRemove()` hook runs when:", + "", + " + The [`remove()`](wix-data.html#remove) function is called.", + " + An action is performed on a dataset that removes an item from the collection.", + " + An item is deleted using the CMS.", + "", + "", + " 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()`](wix-data.html#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()`](#onFailure) hook if it has", + " been registered.", + "", + " Because the `afterRemove()` hook is called after the [`remove()`](wix-data.html#remove)", + " is executed, it cannot prevent the item from being removed from the collection.", + " It can only affect the item returned by [`remove()`](wix-data.html#remove)." ], + "links": [], + "examples": + [ { "title": "An afterRemove hook", + "body": + [ "// 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\"", + " * }", + " */" ], + "extra": + { } }, + { "title": "Change the item returned by `remove()` using an afterRemove hook", + "body": + [ "// In data.js", + "", + "export function myCollection_afterUpdate(item, context) {", + " let hookContext = context; // see below", + "", + " // add a full_name property to the item being returned", + " item.full_name = item.first_name + \" \" + item.last_name;", + "", + " return item;", + "}", + "", + "/*", + " * hookContext:", + " *", + " * {", + " * \"collectionName\": \"myCollection\",", + " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", + " * \"userRole\": \"siteOwner\"", + " * }", + " */" ], + "extra": + { } } ], + "extra": + { } }, + "extra": + { } }, + { "name": "afterUpdate", + "labels": [], + "nameParams": [], + "params": + [ { "name": "item", + "type": "Object", + "doc": "The updated item." }, + { "name": "context", + "type": "DataHooks.UpdateHookContext", + "doc": "Contextual information about the hook." } ], + "ret": + { "type": + [ { "name": "Promise", + "typeParams": + [ "Object" ] }, + "Object" ], + "doc": "The item to return to [`update()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update) instead of the updated item.\n Returning a rejected promise will not block the operation, but will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." }, + "locations": + [ { "lineno": 254, + "filename": "hooks-standalone.js" } ], + "docs": + { "summary": "A hook that is triggered after an `update()` operation.", + "description": + [ "The `afterUpdate()` hook runs when:", + "", + " + The [`update()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update) function is called.", + " + An action is performed on a dataset that updates an item from the collection.", + " + An item is updated using the CMS.", + "", + " **Note**: When [scheduling an item's visibility change](https://support.wix.com/en/article/cms-controlling-live-site-item-visibility-from-your-collection#scheduling-changes-to-item-visibility), 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()`](https://dev.wix.com/docs/velo/api-reference/wix-data/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()`](#onFailure) hook if it has", + " been registered.", + "", + " Because the `afterUpdate` hook is called after the [`update()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update)", + " is executed, it cannot affect the item that is being updated in the collection.", + " It can only affect the item returned by [`update()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update)." ], + "links": [], + "examples": + [ { "title": "An afterUpdate hook", + "body": + [ "// 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\"", + " * }", + " */" ], + "extra": + { } }, + { "title": "Change the item returned by `update()` using an afterUpdate hook", + "body": + [ "// In data.js", + "", + "export function myCollection_afterUpdate(item, context) {", + " let hookContext = context; // see below", + " ", + " // add a full_name property to the item being returned", + " item.full_name = item.first_name + \" \" + item.last_name;", + " ", + " return item;", + "}", + "", + "/*", + " * hookContext:", + " *", + " * {", + " * \"collectionName\": \"myCollection\",", + " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", + " * \"userRole\": \"siteOwner\"", + " * }", + " */" ], + "extra": + { } } ], + "extra": + { } }, + "extra": + { } }, + { "name": "beforeAggregate", + "labels": + [ "removed" ], + "nameParams": [], + "params": + [ { "name": "aggregate", + "type": "wix-data.WixDataAggregate", + "doc": "The original `WixDataAggregate` object." }, + { "name": "context", + "type": "DataHooks.UpdateHookContext", + "doc": "Contextual information about the hook." } ], + "ret": + { "type": + [ { "name": "Promise", + "typeParams": + [ "wix-data.WixDataAggregate" ] }, + "wix-data.WixDataAggregate" ], + "doc": "The aggregate object to run instead of the original object created by the `aggregate()` method.\n Returning a rejected promise blocks the operation, returns a rejected promise to the caller, and triggers the [`onFailure()`](#onFailure) hook." }, + "locations": + [ { "lineno": 292, + "filename": "hooks-standalone.js" } ], + "docs": + { "summary": "A hook triggered before an aggregation operation.", + "description": + [ "The `beforeAggregate()` hook runs when the [`aggregate()`](https://dev.wix.com/docs/velo/api-reference/wix-data/aggregate) is called, and allows you to modify the [`WixDataAggregate`](https://dev.wix.com/docs/velo/api-reference/wix-data/wix-data-aggregate/introduction) object before the aggregation operation runs. ", + "", + "", + " Return a [WixDataAggregate](https://dev.wix.com/docs/velo/api-reference/wix-data/wix-data-aggregate/introduction) object or a Promise that resolves to a [WixDataAggregate](https://dev.wix.com/docs/velo/api-reference/wix-data/wix-data-aggregate/introduction) object. The returned object is the aggregation that runs on the collection instead of the original aggregation created by the [`aggregate()`](https://dev.wix.com/docs/velo/api-reference/wix-data/aggregate) method.", + "", + " If the returned value is of the wrong type, the value is ignored.", + "", + " A rejected Promise blocks the call to [`aggregate()`](https://dev.wix.com/docs/velo/api-reference/wix-data/aggregate) and triggers the [`onFailure()`](#onFailure) hook, if it has been registered." ], + "links": [], + "examples": + [ { "title": "A `beforeAggregate` hook", + "body": + [ "// In data.js", + "", + "export function myCollection_beforeAggregate(aggregate, context) {", + " let hookContext = context; // see below", + "", + " // Some modification to the WixDataAggregate object.", + "", + " return aggregate;", + "}", + "", + "/*", + " * hookContext:", + " *", + " * {", + " * \"collectionName\": \"myCollection\",", + " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", + " * \"userRole\": \"siteOwner\"", + " * }", + " */" ], + "extra": + { } }, + { "title": "Change the `WixDataAggregate` object using a `beforeAggregate` hook", + "body": + [ "// In data.js", + "", + "export function myCollection_afterAggregate(aggregate, context) {", + " let hookContext = context; // see below", + "", + " // Add a filter to the aggregation object.", + " let newAggregate = aggregate.filter().le(\"population\", 2000000);", + "", + " return newAggregate;", + "}", + "", + "/*", + " * hookContext:", + " *", + " * {", + " * \"collectionName\": \"myCollection\",", + " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", + " * \"userRole\": \"siteOwner\"", + " * }", + " */" ], + "extra": + { } } ], + "extra": + { } }, + "extra": + { } }, + { "name": "beforeCount", + "labels": [], + "nameParams": [], + "params": + [ { "name": "query", + "type": "wix-data.WixDataQuery", + "doc": "The original query as defined by [`count()`](wix-data.WixDataQuery.html#count)." }, + { "name": "context", + "type": "DataHooks.HookContext", + "doc": "Contextual information about the hook." } ], + "ret": + { "type": + [ { "name": "Promise", + "typeParams": + [ "wix-data.WixDataQuery" ] }, + "wix-data.WixDataQuery" ], + "doc": "The `query` to be used for the [`count()`](wix-data.WixDataQuery.html#count) operation instead of the original query.\n Returning a rejected promise will block the operation and will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." }, + "locations": + [ { "lineno": 292, + "filename": "hooks-standalone.js" } ], + "docs": + { "summary": "A hook that is triggered before a `count()` operation.", + "description": + [ "The `beforeCount()` hook runs when:", + "", + " + The [`count()`](wix-data.WixDataQuery.html#count) function is called.", + " + The collection is viewed in the CMS.", + "", + "", + " 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()`](wix-data.WixDataQuery.html#count) operation.", + "", + " Often, you will modify the query that is received in the `query` parameter", + " by calling one or more [`WixDataQuery`](wix-data.WixDataQuery.html) functions.", + "", + " If the returned value is of the wrong type, the value is ignored.", + "", + " A rejected Promise blocks the call to [`count()`](wix-data.WixDataQuery.html#count)", + " and also calls the [`onFailure()`](#onFailure) hook if it has been registered.", + "", + " Because the `beforeCount()` hook is called before [`count()`](wix-data.WixDataQuery.html#count)", + " is executed, it can affect how items are counted or block the [`count()`](wix-data.WixDataQuery.html#count)." ], + "links": [], + "examples": + [ { "title": "A beforeCount hook", + "body": + [ "// 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\"", + " * }", + " */" ], + "extra": + { } }, + { "title": "Change the query used for the count, using a beforeCount hook", + "body": + [ "// 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\"", + " * }", + " */" ], + "extra": + { } } ], + "extra": + { } }, + "extra": + { } }, + { "name": "beforeGet", + "labels": [], + "nameParams": [], + "params": + [ { "name": "itemId", + "type": "string", + "doc": "The ID of the original item to be retrieved." }, + { "name": "context", + "type": "DataHooks.HookContext", + "doc": "Contextual information about the hook." } ], + "ret": + { "type": + [ { "name": "Promise", + "typeParams": + [ "string" ] }, + "string" ], + "doc": "The ID to be used for the [`get()`](wix-data.html#get) operation instead of the original `itemId` specified by the caller.\n Returning a rejected promise will block the operation and will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." }, + "locations": + [ { "lineno": 327, + "filename": "hooks-standalone.js" } ], + "docs": + { "summary": "A hook that is triggered before a `get()` operation.", + "description": + [ "The `beforeGet()` hook runs when the [`get()`](wix-data.html#get)", + " function is called.", + "", + " The hook does not run when the [`find`](wix-data.WixDataQuery.html#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()`](wix-data.html#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()`](wix-data.html#get)", + " and also calls the [`onFailure()`](#onFailure) hook if it has been registered.", + "", + " Because the `beforeGet()` hook is called before [`get()`](wix-data.html#get)", + " is executed, it can affect which item is retrieved", + " or block the [`get()`](wix-data.html#get)." ], + "links": [], + "examples": + [ { "title": "A beforeGet hook", + "body": + [ "// 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\"", + " * }", + " */" ], + "extra": + { } }, + { "title": "Change which item is retrieved using a beforeGet hook", + "body": + [ "// 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\"", + " * }", + " */" ], + "extra": + { } } ], + "extra": + { } }, + "extra": + { } }, + { "name": "beforeInsert", + "labels": [], + "nameParams": [], + "params": + [ { "name": "item", + "type": "Object", + "doc": "The original item to be inserted." }, + { "name": "context", + "type": "DataHooks.HookContext", + "doc": "Contextual information about the hook." } ], + "ret": + { "type": + [ { "name": "Promise", + "typeParams": + [ "Object" ] }, + "Object" ], + "doc": "The item to be inserted instead of the original item specified by the caller.\n Returning a rejected promise will block the operation and will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." }, + "locations": + [ { "lineno": 362, + "filename": "hooks-standalone.js" } ], + "docs": + { "summary": "A hook that is triggered before an `insert()` operation.", + "description": + [ "The `beforeInsert()` hook runs when:", + "", + " + The [`insert()`](wix-data.html#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 CMS.", + " + An item is imported into the Sandbox or Live collection.", + "", + "", + " 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()`](wix-data.html#insert) function.", + "", + " If the returned value is of the wrong type, the value is ignored.", + "", + " A rejected Promise blocks the call to [`insert()`](wix-data.html#insert)", + " and also calls the [`onFailure()`](#onFailure) hook if it has been registered.", + "", + " Because the `beforeInsert()` hook is called before [`insert()`](wix-data.html#insert)", + " is executed, it can affect the item that is inserted into the collection", + " or block the [`insert()`](wix-data.html#insert)." ], + "links": [], + "examples": + [ { "title": "A beforeInsert hook", + "body": + [ "// 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\"", + " * }", + " */" ], + "extra": + { } }, + { "title": "Change the item to insert using a beforeInsert hook", + "body": + [ "// 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\"", + " * }", + " */" ], + "extra": + { } }, + { "title": "Validate an email address field using a beforeInsert hook", + "body": + [ "// In data.js", + "", + "export function myCollection_beforeInsert(item, context) {", + " let hookContext = context; // see below", + "", + " //validate the email field and reject in case of failure", + " const emailRegex = /^\\w+([\\.-]?\\w+)*@\\w+([\\.-]?\\w+)*(\\.\\w{2,3})+$/;", + "", + " if (emailRegex.test(item.email)) {", + " return item;", + " } else {", + " return Promise.reject('Invalid email address.');", + " }", + "}", + "", + "/*", + " * hookContext:", + " *", + " * {", + " * \"collectionName\": \"myCollection\",", + " * \"userId\": \"f45jf8d2-grkj-2opd-4ovk-9rfj4wo5tvj3\",", + " * \"userRole\": \"siteOwner\"", + " * }", + " */" ], + "extra": + { } } ], + "extra": + { } }, + "extra": + { } }, + { "name": "beforeQuery", + "labels": [], + "nameParams": [], + "params": + [ { "name": "query", + "type": "wix-data.WixDataQuery", + "doc": "The original query as specified by the caller." }, + { "name": "context", + "type": "DataHooks.HookContext", + "doc": "Contextual information about the hook." } ], + "ret": + { "type": + [ { "name": "Promise", + "typeParams": + [ "wix-data.WixDataQuery" ] }, + "wix-data.WixDataQuery" ], + "doc": "The query to use instead of the original query specified by the caller.\n Returning a rejected promise will block the operation and will return a rejected promise to the operation caller as well as trigger the [`onFailure()`](#onFailure) hook." }, + "locations": + [ { "lineno": 401, + "filename": "hooks-standalone.js" } ], + "docs": + { "summary": "A hook that is triggered before a `find()` operation.", + "description": + [ "The `beforeQuery()` hook runs when:", + "", + " + The [`find`](wix-data.WixDataQuery.html#find) function is called.", + " + An action is performed on a dataset that retrieves items from the collection.", + " + The collection is viewed in the CMS.", + " + An item is exported from the collection.", + "", + "", + " 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`](wix-data.WixDataQuery.html#find) operation.", + "", + " Often, you will modify the query that is received in the `query` parameter", + " by calling one or more [`WixDataQuery`](wix-data.WixDataQuery.html) functions.", + "", + " If the returned value is of the wrong type, the value is ignored.", + "", + " A rejected Promise blocks the call to [`find()`](wix-data.WixDataQuery.html#find)", + " and also calls the [`onFailure()`](#onFailure) hook if it has been registered.", + "", + " Because the `beforeQuery()` hook is called before [`find()`](wix-data.WixDataQuery.html#find)", + " is executed, it can affect the query that is used to retrieve items", + " or block the [`find()`](wix-data.WixDataQuery.html#find)." ], + "links": [], + "examples": + [ { "title": "A beforeQuery hook", + "body": + [ "// 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\"", + " * }", + " */" ], + "extra": + { } }, + { "title": "Change the query to be executed using the beforeQuery hook", + "body": + [ "// 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\"", + " * }", + " */" ], + "extra": + { } } ], + "extra": + { } }, + "extra": + { } }, + { "name": "beforeRemove", + "labels": [], + "nameParams": [], + "params": + [ { "name": "itemId", + "type": "string", + "doc": "The ID of the original item to be removed." }, + { "name": "context", + "type": "DataHooks.UpdateHookContext", + "doc": "Contextual information about the hook." } ], + "ret": + { "type": + [ { "name": "Promise", + "typeParams": + [ "string" ] }, + "string" ], + "doc": "The ID to be used for the [`remove()`](wix-data.html#remove) instead of the original `itemId` specified by the caller.\n Returning a rejected promise will block the operation and will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." }, + "locations": + [ { "lineno": 442, + "filename": "hooks-standalone.js" } ], + "docs": + { "summary": "A hook that is called before a `remove()` operation.", + "description": + [ "The `beforeRemove()` hook runs when:", + "", + " + The [`remove()`](wix-data.html#remove) function is called.", + " + An action is performed on a dataset that removes an item from the collection.", + " + An item is deleted using the CMS.", + "", + "", + " 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()`](wix-data.html#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()`](wix-data.html#remove)", + " and also calls the [`onFailure()`](#onFailure) hook if it has been registered.", + "", + " Because the `beforeRemove()` hook is called before [`remove()`](wix-data.html#remove)", + " is executed, it can affect the item that is removed from the collection", + " or block the [`remove()`](wix-data.html#remove)." ], + "links": [], + "examples": + [ { "title": "A beforeRemove hook", + "body": + [ "// 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\"", + " * }", + " */" ], + "extra": + { } }, + { "title": "Change the item to remove using a beforeRemove hook", + "body": + [ "// 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\"", + " * }", + " */" ], + "extra": + { } } ], + "extra": + { } }, + "extra": + { } }, + { "name": "beforeUpdate", + "labels": [], + "nameParams": [], + "params": + [ { "name": "item", + "type": "Object", + "doc": "The original item to be updated." }, + { "name": "context", + "type": "DataHooks.UpdateHookContext", + "doc": "Contextual information about the hook." } ], + "ret": + { "type": + [ { "name": "Promise", + "typeParams": + [ "Object" ] }, + "Object" ], + "doc": "The item to be updated instead of the original item specified by the caller.\n Returning a rejected promise will block the operation and will return a rejected promise to the caller as well as trigger the [`onFailure()`](#onFailure) hook." }, + "locations": + [ { "lineno": 480, + "filename": "hooks-standalone.js" } ], + "docs": + { "summary": "A hook that is triggered before an `update()` operation.", + "description": + [ "The `beforeUpdate()` hook runs when:", + "", + " + The [`update()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update) function is called.", + " + An action is performed on a dataset that updates an item from the collection.", + " + An item is updated using the CMS.", + "", + "", + " 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()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update) function.", + "", + " If the returned value is of the wrong type, the value is ignored.", + "", + " A rejected Promise blocks the call to [`update()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update)", + " and also calls the [`onFailure()`](#onFailure) hook if it has been registered.", + "", + " Because the `beforeUpdate()` hook is called before the [`update()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update)", + " is executed, it can affect the item that is updated in the collection", + " or block the [`update()`](https://dev.wix.com/docs/velo/api-reference/wix-data/update)." ], + "links": [], + "examples": + [ { "title": "A beforeUpdate hook", + "body": + [ "// 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\"", + " * }", + " */" ], + "extra": + { } }, + { "title": "Change the item to update using a beforeUpdate hook", + "body": + [ "// 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\"", + " * }", + " */" ], + "extra": + { } } ], + "extra": + { } }, + "extra": + { } }, + { "name": "onFailure", + "labels": [], + "nameParams": [], + "params": + [ { "name": "error", + "type": "Error", + "doc": "The error that caused the failure." }, + { "name": "context", + "type": "DataHooks.HookContext", + "doc": "Contextual information about the hook." } ], + "ret": + { "type": + { "name": "Promise", + "typeParams": + [ "Object" ] }, + "doc": "Fulfilled - Returning a fulfilled promise will result in a fulfilled data operation with the provided result.\nRejected - Returning a rejected promise will result in returning a rejected promise to the caller of the data operation." }, + "locations": + [ { "lineno": 517, + "filename": "hooks-standalone.js" } ], + "docs": + { "summary": "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." ], + "links": [], + "examples": + [ { "title": "A hook triggered when a failure occurs", + "body": + [ "// 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", + " * }", + " */" ], + "extra": + { } } ], + "extra": + { } }, + "extra": + { } } ], + "callbacks": [], + "messages": + [ { "name": "HookContext", + "locations": + [ { "lineno": 1, + "filename": "hooks-standalone.js" } ], + "docs": + { "summary": "An object that contains contextual information about the hook being called.", + "links": [], + "examples": [], + "extra": + { } }, + "members": + [ { "name": "collectionName", + "type": "string", + "doc": "The ID of the collection the hook affects." }, + { "name": "userId", + "type": "string", + "doc": "The current site user ID. If no user is logged in to the site it may be null." }, + { "name": "userRole", + "type": "string", + "doc": "The permissions role of the current user. Possibilities are: `anonymous`, `siteMember`, and `siteOwner`." } ], + "extra": + { }, + "labels": [] }, + { "name": "UpdateHookContext", + "locations": + [ { "lineno": 10, + "filename": "hooks-standalone.js" } ], + "docs": + { "summary": "An object that contains contextual information when calling the `beforeUpdate()`, `beforeRemove()`, or `afterUpdate()` hooks.", + "links": [], + "examples": [], + "extra": + { } }, + "members": + [ { "name": "collectionName", + "type": "string", + "doc": "The ID of the collection the hook affects." }, + { "name": "userId", + "type": "string", + "doc": "The current site user ID. If no user is logged in to the site it may be null." }, + { "name": "userRole", + "type": "string", + "doc": "The permissions role of the current user. Possibilities are: `anonymous`, `siteMember`, and `siteOwner`." }, + { "name": "currentItem", + "type": "Object", + "doc": "The item stored in the database collection before an update or delete operation." } ], + "extra": + { }, + "labels": [] } ], + "extra": + { } } \ No newline at end of file