$w( )


Selects and returns elements from a page.

The $w() function selects single or multiple elements by ID or type.

To select by ID, pass a selector string with the hash symbol (#) followed by the ID of the item you want to select (e.g. "#myElement"). The function returns the selected element object.

To select by type, pass a selector string with the name of the type without the preceding # (e.g. "Button"). The function returns an array of the selected element objects. An array is returned even if one or no elements are selected.

To select using multiple selectors, pass a selector string with multiple selectors separated by commas. The selectors in the comma-separated string can be ID selectors, type selectors, or a mixture of the two. The function returns an array of the selected element objects. An array is returned even if one or no elements are selected. If two or more selectors select the same element, it's still returned only once in the array.

Note: Most elements accessible for selection by $w have basic API properties and functions, like id, type, show(), hide(), and others. Use Velo's autocomplete in the code panel to see which API functions and properties are available for each element.

Method Declaration
Copy
Method Parameters
selectorstringRequired

A selector or multiple comma-separated selectors.

Returns
Return Type:Element | Array<Element>
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

at( )


Gets a selector function for a specific context.

The at() function returns a scoped selector where the scope is based on the context property. Usually, you will use at() in a event handler that handles events fired on an element contained in a repeater to get a selector with repeated item scope. The returned function selects the elements from the same repeater item where the event was fired.

Method Declaration
Copy
Method Parameters
contextEventContextRequired

An event context.

Returns
Return Type:$w
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

onReady( )


Sets the function that runs when all the page elements have finished loading.

Use the onReady() function for code you want to run before the user starts interacting with your page.

The onReady() function in the masterpage.js file is called before the onReady() function in the code for the page being viewed.

The following code should be placed inside the onReady() event handler:

  • Initialization of element properties: Example: Setting a text element's initial text value.
  • Function calls on elements to set their initial state: Example: Disabling a button.
  • Dynamic event handlers that you want bound when the page loads: Example: Setting an event handler to be called when the pointer enters an element.
  • For SEO, return all content you want search bots to see. Search bots can see the results of any function that runs in onReady() and whose promise is resolved before the onReady() promise is resolved. For asynchronous functions, ensure the function's promise resolves first by returning it in onReady(). Example: Return data queries in onReady() if the queried content is populating page elements.

The following code should not be placed inside the onReady() event handler:

  • Static event handlers that are wired using the Properties panel in the Editor are not placed inside the onReady() event handler.
  • return statements containing synchronous functions, especially if there is no impact on rendering (such as a query) and no need for SEO. Avoiding these return statements can improve performance.

Preventing double "side effects"

The onReady() event handler may be called twice during the page rendering process, once server-side and once client-side.

Because onReady() code may be run twice, you need to be aware that if your onReady() code causes a side effect, such as inserting an item into a collection, that side effect might happen twice. To avoid a side effect from happening twice, use wix-window-frontend.rendering.env to determine where your code is being executed.

Method Declaration
Copy
Method Parameters
initFunctionfunctionRequired

initFunction(): Promise<void> | void The name of the function to run when the page has finished loading.

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

add( )


Adds a new blank item.

The add() function saves the current item and then adds a new blank item. When the editing of the new item is complete, you will need to call another function that will save the new item.

The index of the new item is one after the index of the current item, or zero if there is no current item.

Note that since the add() function begins by saving the current item, if the current item cannot be saved for any reason, such as it does not pass validation, calling the function will cause an error.

Calling add() on a read-only dataset causes an error.

Notes:

A dataset needs to load its data before you call its add() function. Usually a dataset finishes loading a short time after the page it is on finishes loading. So if you call add() inside the page’s onReady() event handler, the dataset might not be ready yet.

To call add() as soon as possible after a page loads, use the dataset's onReady() function inside the page’s onReady() event handler to ensure that both the page and the dataset have finished loading.

This function replaces the deprecated new() function. The deprecated function will continue to work, but will not receive updates.

Method Declaration
Copy
Request
This method does not take any parameters
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

getCurrentItem( )


Returns the current item.

The getCurrentItem() function returns an object whose key:value pairs are the field IDs and field values of the current item, including all hidden fields. Fields that do not have a value are omitted from the returned object.

When called on a write-only or read & write dataset, getCurrentItem() returns the unsaved state of the current item.

Returns null or undefined if the dataset:

  • Is filtered to not match any items in the collection.
  • Is empty.
  • Has not loaded yet.

Note:

A dataset needs to load its data before you call its getCurrentItem() function. Usually a dataset finishes loading a short time after the page it is on finishes loading. So if you call getCurrentItem() inside the page’s onReady() event handler, the dataset might not be ready yet.

To call getCurrentItem() as soon as possible after a page loads, use the dataset's onReady() function inside the page’s onReady() event handler to ensure that both the page and the dataset have finished loading.

If the current item is changed from a non-dataset source, such as by selecting a row in a table connected to a dataset or clicking a button set to advance to the next item in a dataset, the dataset's current item is not updated immediately. Therefore, to get the dataset's new current item, call getCurrentItem() in the dataset's onCurrentIndexChanged() event handler. Do not use the events of the non-dataset source, such as onRowSelect or onClick, to call getCurrentItem() because they will fire before the dataset's current item is updated.

Method Declaration
Copy
Request
This method does not take any parameters
Returns
Return Type:
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

getCurrentItemIndex( )


Returns the current item's index.

The getCurrentItemIndex() function returns the index of current item within the items of the dataset. The indices of the items in a dataset are zero-based. For example, if the third item is the current item, then getCurrentItemIndex() returns 2.

Calling getCurrentItemIndex() on a write-only dataset causes an error.

Returns null if one of the following is true if the dataset:

  • Is filtered to not match any items in the collection.
  • Is empty.
  • Has not loaded yet.

Note:

A dataset needs to load its data before you call its getCurrentItemIndex() function. Usually a dataset finishes loading a short time after the page it is on finishes loading. So if you call getCurrentItemIndex() inside the page’s onReady() event handler, the dataset might not be ready yet.

To call getCurrentItemIndex() as soon as possible after a page loads, use the dataset's onReady() function inside the page’s onReady() event handler to ensure that both the page and the dataset have finished loading.

If the current item is changed from a non-dataset source, such as by selecting a row in a table connected to a dataset or clicking a button set to advance to the next item in a dataset, the dataset's current item is not updated immediately. Therefore, to get the dataset's new current item index, call getCurrentItemIndex() in the dataset's onCurrentIndexChanged() event handler. Do not use the events of the non-dataset source, such as onRowSelect or onClick, to call getCurrentItemIndex() because they will fire before the dataset's current item is updated.

Method Declaration
Copy
Request
This method does not take any parameters
Returns
Return Type:number
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

getCurrentPageIndex( )


Gets the index of the dataset's current page.

The getCurrentPageIndex() function returns the index of current dataset page. The indices of the dataset's pages start at 1.

Note:

A dataset needs to load its data before you call its getCurrentPageIndex() function. Usually a dataset finishes loading a short time after the page it is on finishes loading. So if you call getCurrentPageIndex() inside the page’s onReady() event handler, the dataset might not be ready yet.

To call getCurrentPageIndex() as soon as possible after a page loads, use the dataset's onReady() function inside the page’s onReady() event handler to ensure that both the page and the dataset have finished loading.

Method Declaration
Copy
Request
This method does not take any parameters
Returns
Return Type:number
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

getItems( )


Returns the selected items.

The getItems() function returns a Promise that is resolved to a GetItemsResult object when the items have been retrieved.

Calling getItems() on a write-only dataset causes an error.

Note:

A dataset needs to load its data before you call its getItems() function. Usually a dataset finishes loading a short time after the page it is on finishes loading. So if you call getItems() inside the page’s onReady() event handler, the dataset might not be ready yet.

To call getItems() as soon as possible after a page loads, use the dataset's onReady() function inside the page’s onReady() event handler to ensure that both the page and the dataset have finished loading.

Method Declaration
Copy
Method Parameters
fromIndexnumberRequired

The index of the first item to return.


numberOfItemsnumberRequired

The number of items to return.

Returns
Return Type:Promise<GetItemsResult>
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

getPageSize( )


Gets the dataset's page size.

Gets the current page size set in the Editor or using the setPageSize function.

Method Declaration
Copy
Request
This method does not take any parameters
Returns
Return Type:number
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

getTotalCount( )


Returns the number of items in the dataset that match its filter criteria.

Calling getTotalCount() on a write-only dataset causes an error.

Note:

A dataset needs to load its data before you call its getTotalCount() function. Usually a dataset finishes loading a short time after the page it is on finishes loading. So if you call getTotalCount() inside the page’s onReady() event handler, the dataset might not be ready yet.

To call getTotalCount() as soon as possible after a page loads, use the dataset's onReady() function inside the page’s onReady() event handler to ensure that both the page and the dataset have finished loading.

Method Declaration
Copy
Request
This method does not take any parameters
Returns
Return Type:number
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

getTotalPageCount( )


Gets the number of pages in the dataset.

The number of pages in a dataset is the number of total items divided by the page size. If there are any left over items, one more page is added.

For example, if you have 20 items and your page size is 6, you have 4 pages. The first 3 pages have 6 items each and the last page has 2 items.

Note:

A dataset needs to load its data before you call its getTotalPageCount() function. Usually a dataset finishes loading a short time after the page it is on finishes loading. So if you call getTotalPageCount() inside the page’s onReady() event handler, the dataset might not be ready yet.

To call getTotalPageCount() as soon as possible after a page loads, use the dataset's onReady() function inside the page’s onReady() event handler to ensure that both the page and the dataset have finished loading.

Method Declaration
Copy
Request
This method does not take any parameters
Returns
Return Type:number
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

hasNext( )


Indicates if there is a next item.

Returns true if the current item is not the last item in the dataset.

Returns false if the current item is the last item in the dataset.

Calling hasNext() on a write-only dataset causes an error.

Note:

A dataset needs to load its data before you call its hasNext() function. Usually a dataset finishes loading a short time after the page it is on finishes loading. So if you call hasNext() inside the page’s onReady() event handler, the dataset might not be ready yet.

To call hasNext() as soon as possible after a page loads, use the dataset's onReady() function inside the page’s onReady() event handler to ensure that both the page and the dataset have finished loading.

Method Declaration
Copy
Request
This method does not take any parameters
Returns
Return Type:boolean
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

hasNextPage( )


Indicates if there is a next page of data.

Returns true if the current page is not the last page in the dataset.

Returns false if the current page is the last page in the dataset.

Calling hasNextPage() on a write-only dataset causes an error.

Note:

A dataset needs to load its data before you call its hasNextPage() function. Usually a dataset finishes loading a short time after the page it is on finishes loading. So if you call hasNextPage() inside the page’s onReady() event handler, the dataset might not be ready yet.

To call hasNextPage() as soon as possible after a page loads, use the dataset's onReady() function inside the page’s onReady() event handler to ensure that both the page and the dataset have finished loading.

Method Declaration
Copy
Request
This method does not take any parameters
Returns
Return Type:boolean
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

hasPrevious( )


Indicates if there is a previous item.

Returns true if the current item is not the first item in the dataset.

Returns false if the current item is the first item in the dataset.

Calling hasPrevious() on a write-only dataset causes an error.

Note:

A dataset needs to load its data before you call its hasPrevious() function. Usually a dataset finishes loading a short time after the page it is on finishes loading. So if you call hasPrevious() inside the page’s onReady() event handler, the dataset might not be ready yet.

To call hasPrevious() as soon as possible after a page loads, use the dataset's onReady() function inside the page’s onReady() event handler to ensure that both the page and the dataset have finished loading.

Method Declaration
Copy
Request
This method does not take any parameters
Returns
Return Type:boolean
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

hasPreviousPage( )


Indicates if there is a previous page of data.

Returns true if the current page is not the first page in the dataset.

Returns false if the current page is the first page in the dataset.

Calling hasPreviousPage() on a write-only dataset causes an error.

Note:

A dataset needs to load its data before you call its hasPreviousPage() function. Usually a dataset finishes loading a short time after the page it is on finishes loading. So if you call hasPreviousPage() inside the page’s onReady() event handler, the dataset might not be ready yet.

To call hasPreviousPage() as soon as possible after a page loads, use the dataset's onReady() function inside the page’s onReady() event handler to ensure that both the page and the dataset have finished loading.

Method Declaration
Copy
Request
This method does not take any parameters
Returns
Return Type:boolean
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

loadMore( )


Loads the next page of data in addition to the current data.

The loadMore() function returns a Promise that is resolved when:

  • The dataset loads the next page of data.
  • Any connected elements have been updated with the new data.

Loading more data into a dataset adds more items to any connected repeaters. Elements that have their own settings for how many items are shown at once, such as tables and galleries, are not affected.

Loading more data into a dataset does not:

  • Remove any of the items that were previously shown in any connected elements
  • Change the dataset's page size.
  • Change the dataset's current item.

Note:

A dataset needs to load its data before you call its loadMore() function. Usually a dataset finishes loading a short time after the page it is on finishes loading. So if you call loadMore() inside the page’s onReady() event handler, the dataset might not be ready yet.

To call loadMore() as soon as possible after a page loads, use the dataset's onReady() function inside the page’s onReady() event handler to ensure that both the page and the dataset have finished loading.

Method Declaration
Copy
Request
This method does not take any parameters
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

loadPage( )


Loads the specified page.

The loadPage() function returns a Promise that is resolved to an array of the specified page's items when:

  • The current item is saved in the collection (if necessary).
  • The specified page of data is loaded.
  • Any connected elements have been updated with the new data.
  • The current item is updated to the first item in the loaded page.

The indices of the dataset's pages start at 1.

Notes:

  • A dataset needs to load its data before you call its loadPage() function.

    Usually a dataset finishes loading a short time after the page it is on finishes loading. So if you call loadPage() inside the page’s onReady() event handler, the dataset might not be ready yet.

    To call loadPage() as soon as possible after a page loads, use the dataset's onReady() function inside the page’s onReady() event handler to ensure that both the page and the dataset have finished loading.

  • When using a read-write dataset and linked input elements, calling any of the following functions will save any changes made in the linked input elements.

Method Declaration
Copy
Method Parameters
pageIndexnumberRequired

The index of the page to load.

Returns
Return Type:Promise<Array<object>>
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

new( )


Deprecated. This function will continue to work, but a newer version is available. Use the add() function instead.

Creates a new blank item.

The new() function saves the current item and then creates a new blank item. When the editing of the new item is complete, you will need to call another function that will save the new item.

The index of the new item is one after the index of the current item, or zero if there is no current item.

Note that since the new() function begins by saving the current item, if the current item cannot be saved for any reason, such as it does not pass validation, calling the function will cause an error.

Calling new() on a read-only dataset causes an error.

Note:

A dataset needs to load its data before you call its new() function. Usually a dataset finishes loading a short time after the page it is on finishes loading. So if you call new() inside the page’s onReady() event handler, the dataset might not be ready yet.

To call new() as soon as possible after a page loads, use the dataset's onReady() function inside the page’s onReady() event handler to ensure that both the page and the dataset have finished loading.

Method Declaration
Copy
Request
This method does not take any parameters
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

next( )


Saves the current item and moves to the next item.

The next() function returns a Promise that is resolved to the next item when:

  • The current item is saved in the collection (if necessary).
  • Any connected page elements have been updated with the new current item’s values.

Calling next() on a write-only dataset causes the Promise to reject.

If the dataset is read-write, the current item is saved even if there is no next item.

Notes:

  • A dataset needs to load its data before you call its next() function.

    Usually a dataset finishes loading a short time after the page it is on finishes loading. So if you call next() inside the page’s onReady() event handler, the dataset might not be ready yet.

    To call next() as soon as possible after a page loads, use the dataset's onReady() function inside the page’s onReady() event handler to ensure that both the page and the dataset have finished loading.

  • When using a read-write dataset and linked input elements, calling any of the following functions will save any changes made in the linked input elements.

Method Declaration
Copy
Request
This method does not take any parameters
Returns
Return Type:Promise<object>
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

nextPage( )


Moves to the next page of data.

The nextPage() function returns a Promise that is resolved to an array of the next page's items when:

  • The current item is saved in the collection (if necessary).
  • The next page of data is loaded.
  • Any connected elements have been updated with the new data.
  • The current item is updated to the first item in the next page.

Going to the next page of data replaces the current items in any connected elements with the new items that correspond to the next page of data. Elements that have their own settings for how many items are shown at once, such as tables and galleries, are not affected.

Calling nextPage() on a write-only dataset causes an error.

Notes:

  • A dataset needs to load its data before you call its nextPage() function.

    Usually a dataset finishes loading a short time after the page it is on finishes loading. So if you call nextPage() inside the page’s onReady() event handler, the dataset might not be ready yet.

    To call nextPage() as soon as possible after a page loads, use the dataset's onReady() function inside the page’s onReady() event handler to ensure that both the page and the dataset have finished loading.

  • When using a read-write dataset and linked input elements, calling any of the following functions will save any changes made in the linked input elements.

Method Declaration
Copy
Request
This method does not take any parameters
Returns
Return Type:Promise<Array<object>>
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

onAfterSave( )


Adds an event handler that runs just after a save.

The onAfterSave() function allows you to optionally perform actions right after a save() operation. When you call save(), the callback is run after the save has successfully completed.

Calling onAfterSave() on a read-only dataset causes an error.

Method Declaration
Copy
Method Parameters
handlerfunctionRequired

handler(itemBeforeSave: object, itemAfterSave: object): void The after save event handler.

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

onBeforeSave( )


Adds an event handler that runs just before a save.

The onBeforeSave() function allows you to optionally perform actions right before a save() operation. When you call save(), the callback is run before the save operation. Any validity checks on the data are run after the callback runs. If the callback function returns false, returns a rejected Promise, or throws an error, the save operation is canceled.

Notes:

  • Calling onBeforeSave() on a read-only dataset causes an error.
  • onBeforeSave() runs before any input element validations.
Method Declaration
Copy
Method Parameters
handlerfunctionRequired

handler(): Promise<boolean> | boolean The before save event handler.

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

onCurrentIndexChanged( )


Adds an event handler that runs when the current index changes.

The onCurrentIndexChanged() function allows you to optionally perform actions right after the current index changes.

Calling onCurrentIndexChanged() on a write-only dataset causes an error.

Method Declaration
Copy
Method Parameters
handlerfunctionRequired

handler(index: number): void The current index change event handler.

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

onError( )


Adds an event handler that runs when an error occurs.

The onError() function allows you to perform actions after a dataset operation causes an error such as a field failing validation.

The value of the handler's operation property is the name of the function that caused the error.

For example, the operation property could be any of the following:

  • "new"
  • "next"
  • "save"
  • "previous"
Method Declaration
Copy
Method Parameters
handlerfunctionRequired

handler(operation: string, error: DatasetError): void The error handler.

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

onItemValuesChanged( )


Adds an event handler that runs when a value of the current item changes.

The onItemValuesChanged() function allows you to optionally perform actions right after the current item's values change. The item's value changes when a user changes the value in one of the item's connected page elements or you change the value programmatically.

Calling onItemValuesChanged() on a read-only dataset causes an error.

Method Declaration
Copy
Method Parameters
handlerfunctionRequired

handler(itemBeforeChange: object, updatedItem: object): void The current value changed event handler.

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

onReady( )


Adds an event handler that runs when the dataset is ready.

The onReady() function allows you to optionally perform actions right after the dataset has loaded its data from the collection and updated all connected page elements with their corresponding values.

Notes:

  • The dataset onReady event only fires after the page onReady event fires.
  • The onReady() function has the same functionality as the onReadyAsync() function. They differ in that onReady() is callback-based, whereas onReadyAsync() is promise-based.
Method Declaration
Copy
Method Parameters
handlerfunctionRequired

handler(): void The ready handler.

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

onReadyAsync( )


The onReadyAsync() function returns a Promise that resolves when a dataset is ready.

Similar to the onReady() function, the onReadyAsync() function allows you to optionally perform actions once a dataset is ready. A dataset is ready after it has loaded its data from the collection and updated all connected page elements with their corresponding values. onReadyAsync() differs from onReady() in that onReadyAsync() is promise-based, whereas onReady() is based on callback functions.

Method Declaration
Copy
Request
This method does not take any parameters
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

previous( )


Saves the current item and moves to the previous item.

The previous() function returns a Promise that is resolved to the previous item when:

  • The current item is saved in the collection (if necessary).
  • Any connected page elements have been updated with the new current item’s values.

Calling previous() on a write-only dataset causes the Promise to reject.

If the dataset is read-write, the current item is saved even if there is no previous item.

Notes:

  • A dataset needs to load its data before you call its previous() function.

    Usually a dataset finishes loading a short time after the page it is on finishes loading. So if you call previous() inside the page’s onReady() event handler, the dataset might not be ready yet.

    To call previous() as soon as possible after a page loads, use the dataset's onReady() function inside the page’s onReady() event handler to ensure that both the page and the dataset have finished loading.

  • When using a read-write dataset and linked input elements, calling any of the following functions will save any changes made in the linked input elements.

Method Declaration
Copy
Request
This method does not take any parameters
Returns
Return Type:Promise<object>
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

previousPage( )


Moves to the previous page of data.

The previousPage() function returns a Promise that is resolved to an array of the previous page's items when:

  • The current item is saved in the collection (if necessary).
  • The previous page of data is loaded.
  • Any connected elements have been updated with the new data.
  • The current item is updated to the first item in the previous page.

Going to the previous page of data replaces the current items in any connected elements with the new items that correspond to the previous page of data. Elements that have their own settings for how many items are shown at once, such as tables and galleries, are not affected.

Calling previousPage() on a write-only dataset causes an error.

Notes:

  • A dataset needs to load its data before you call its previousPage() function.

    Usually a dataset finishes loading a short time after the page it is on finishes loading. So if you call previousPage() inside the page’s onReady() event handler, the dataset might not be ready yet.

    To call previousPage() as soon as possible after a page loads, use the dataset's onReady() function inside the page’s onReady() event handler to ensure that both the page and the dataset have finished loading.

  • When using a read-write dataset and linked input elements, calling any of the following functions will save any changes made in the linked input elements.

Method Declaration
Copy
Request
This method does not take any parameters
Returns
Return Type:Promise<Array<object>>
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

refresh( )


Refetches the contents of the dataset from the collection.

The refresh() function returns a Promise that is resolved when:

  • The dataset's contents are refetched from the collection, discarding current edits.
  • Any connected page elements have been updated with the values from the collection (read & write mode) or blank values (write-only mode).

Refreshing the dataset sets the current item back to the first item in the dataset regardless of what the current item was before refreshing.

Note:

A dataset needs to load its data before you call its refresh() function. Usually a dataset finishes loading a short time after the page it is on finishes loading. So if you call refresh() inside the page’s onReady() event handler, the dataset might not be ready yet.

To call refresh() as soon as possible after a page loads, use the dataset's onReady() function inside the page’s onReady() event handler to ensure that both the page and the dataset have finished loading.

Method Declaration
Copy
Request
This method does not take any parameters
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

remove( )


Removes the current item.

The remove() function returns a Promise that is resolved when:

  • The current item is deleted in the collection.
  • Any connected page elements have been updated with the next item’s values if there is a next item, or the previous item's values if the removed item was the last item.

Calling remove() on a write-only or read-only dataset causes an error.

Note:

A dataset needs to load its data before you call its remove() function. Usually a dataset finishes loading a short time after the page it is on finishes loading. So if you call remove() inside the page’s onReady() event handler, the dataset might not be ready yet.

To call remove() as soon as possible after a page loads, use the dataset's onReady() function inside the page’s onReady() event handler to ensure that both the page and the dataset have finished loading.

Method Declaration
Copy
Request
This method does not take any parameters
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

revert( )


Reverts the current item to its saved value.

The revert() function returns a Promise that is resolved when:

  • The current item is reverted to its saved state in the collection.
  • Any connected page elements have been updated with the current item’s old values (read & write mode) or blank values (write-only mode).

Calling revert() on a read-only dataset causes the Promise to reject.

Note:

A dataset needs to load its data before you call its revert() function. Usually a dataset finishes loading a short time after the page it is on finishes loading. So if you call revert() inside the page’s onReady() event handler, the dataset might not be ready yet.

To call revert() as soon as possible after a page loads, use the dataset's onReady() function inside the page’s onReady() event handler to ensure that both the page and the dataset have finished loading.

Method Declaration
Copy
Request
This method does not take any parameters
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

save( )


Saves the current item.

The save() function returns a Promise that is resolved to the saved item when:

  • The current item is saved in the collection.
  • Any connected page elements have been updated with the current item’s new values (read & write mode) or a new blank item (write-only mode).

Calling save() on a read-only dataset causes the Promise to reject.

Notes:

  • A dataset needs to load its data before you call its save() function.

    Usually a dataset finishes loading a short time after the page it is on finishes loading. So if you call save() inside the page’s onReady() event handler, the dataset might not be ready yet.

    To call save() as soon as possible after a page loads, use the dataset's onReady() event handler to ensure that both the page and the dataset have finished loading.

  • When using a read-write dataset and linked input elements, calling any of the following functions will save any changes made in the linked input elements.

Method Declaration
Copy
Request
This method does not take any parameters
Returns
Return Type:Promise<object>
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

setCurrentItemIndex( )


Sets the current item by index.

The setCurrentItemIndex() function returns a Promise that is resolved when:

  • The current item has been saved in the collection (if necessary).
  • The current item has been updated to be the item with the given index.
  • Any connected page elements have been updated with the new current item’s values.

Calling setCurrentItemIndex() on a write-only dataset causes the Promise to reject.

Notes:

  • A dataset needs to load its data before you call its setCurrentItemIndex() function.

    Usually a dataset finishes loading a short time after the page it is on finishes loading. So if you call setCurrentItemIndex() inside the page’s onReady() event handler, the dataset might not be ready yet.

    To call setCurrentItemIndex() as soon as possible after a page loads, use the dataset's onReady() function inside the page’s onReady() event handler to ensure that both the page and the dataset have finished loading.

  • When using a read-write dataset and linked input elements, calling any of the following functions will save any changes made in the linked input elements.

  • setCurrentItemIndex() saves the current item even if the requested item is same as the current item.
Method Declaration
Copy
Method Parameters
indexnumberRequired

The index of the item to set as the current item.

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

setFieldValue( )


Updates the value of a field in the current item.

The setFieldValue function sets the value of a field in the current item. Setting a field value fires an onItemValuesChanged event when the page elements connected to the field have been updated with the new value.

Setting the value of a field in a dataset item does not immediately set that value in the collection that the dataset is connected to. You still need to call the dataset save() function or any other function that performs a save to have the new value reflecting in the collection.

Calling setFieldValue() on a read-only dataset causes an error.

Note:

A dataset needs to load its data before you call its setFieldValue() function. Usually a dataset finishes loading a short time after the page it is on finishes loading. So if you call setFieldValue() inside the page’s onReady() event handler, the dataset might not be ready yet.

To call setFieldValue() as soon as possible after a page loads, use the dataset's onReady() function inside the page’s onReady() event handler to ensure that both the page and the dataset have finished loading.

Method Declaration
Copy
Method Parameters
fieldKeystringRequired

The field ID of the field to update.


valueanyRequired

The new value.

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

setFieldValues( )


Updates the values of a set of fields in the current item.

The setFieldValues function sets the value of a set of fields in the current item. Setting the field values fires one onItemValuesChanged event when the page elements connected to the fields have been updated with the new values.

Calling setFieldValues() on a read-only dataset causes an error.

Note:

A dataset needs to load its data before you call its setFieldValues() function. Usually a dataset finishes loading a short time after the page it is on finishes loading. So if you call setFieldValues() inside the page’s onReady() event handler, the dataset might not be ready yet.

To call setFieldValues() as soon as possible after a page loads, use the dataset's onReady() function inside the page’s onReady() event handler to ensure that both the page and the dataset have finished loading.

Method Declaration
Copy
Method Parameters
fieldValuesFieldValuesRequired

A map of field IDs to new values.

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

setFilter( )


Sets the dataset filter.

The setFilter() function filters out items that don't match the filter criteria.

The WixDataFilter object is created by calling the filter() function on wixData and chaining one or more of the following Wix Data filter functions.

Setting a dataset's filter overrides existing filters that were previously set using the setFilter() function or using the Dataset Settings panel in the Editor.

To clear a dataset's current filter, call setFilter() and pass it an empty filter. You create an empty filter by calling the filter() function without chaining any of the additional filter functions mentioned above.

Calling setFilter() on a write-only dataset causes an error.

You will need to import wix-data in order to create a WixDataFilter object.

Notes:

Method Declaration
Copy
Method Parameters
filterWixDataFilterRequired

A wix-data filter object.

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

setPageSize( )


Sets the dataset's page size.

The setPageSize() function returns a Promise that is resolved when:

  • The current item is saved in the collection (if necessary).
  • The dataset's page size is reset.
  • The dataset is refreshed, and any connected elements have been updated.

Because setting the page size refreshes the dataset, the dataset's current item is reset to the first item in the dataset.

Calling setPageSize() on a write-only dataset causes an error.

Note: When using a read-write dataset and linked input elements, calling any of the following functions will save any changes made in the linked input elements.

Method Declaration
Copy
Method Parameters
pageSizenumberRequired

The new page size.

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

setSort( )


Sets the dataset sort order.

The setSort function sorts the items in the dataset.

The WixDataSort object is created by calling the sort() function on wixData and chaining one or more of the following WixDataSort sort functions.

Setting a dataset's sort overrides existing sorts that were previously set using the setSort() function or using the Dataset Settings panel in the Editor.

To clear a dataset's current sort, call setSort() and pass it an empty sort. You create an empty sort by calling the sort() function without chaining any of the additional sort functions mentioned above.

Calling setSort() on a write-only dataset causes an error.

You will need to import wix-data to create a WixDataSort object.

Note: When using a read-write dataset and linked input elements, calling any of the following functions will save any changes made in the linked input elements.

Method Declaration
Copy
Method Parameters
sortWixDataSortRequired

A wix-data sort object.

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?