CorvidReference

DynamicDataset

A dataset connects page elements on a dynamic page to a set of items in a data collection.

Table of Contents

FUNCTIONS

?
Perform actions on an object.
getCurrentItem( )Returns the current item.
getCurrentItemIndex( )Returns the current item's index.
getCurrentPageIndex( )Gets the index of the dataset's current page.
getItems( )Returns the selected items.
getNextDynamicPage( )Gets the next dynamic page URL.
getPageSize( )Gets the dataset's page size.
getPreviousDynamicPage( )Gets the previous dynamic page URL.
getTotalCount( )Returns the number of items in the dataset that match its filter criteria.
getTotalPageCount( )Gets the number of pages in the dataset.
hasNext( )Indicates if there is a next item.
hasNextPage( )Indicates if there is a next page of data.
hasPrevious( )Indicates if there is a previous item.
hasPreviousPage( )Indicates if there is a previous page of data.
loadMore( )Loads the next page of data in addition to the current data.
loadPage( )Loads the specified page.
new( )Create a new blank item.
next( )Saves the current item and moves to the next item.
nextPage( )Moves to the next page of data.
onAfterSave( )Adds an event handler that runs just after a save.
onBeforeSave( )Adds an event handler that runs just before a save.
onCurrentIndexChanged( )Adds an event handler that runs when the current index changes.
onError( )Adds an event handler that runs when an error occurs.
onItemValuesChanged( )Adds an event handler that runs when a value of the current item changes.
onReady( )Adds an event handler that runs when the dataset is ready.
previous( )Saves the current item and moves to the previous item.
previousPage( )Moves to the previous page of data.
refresh( )Refetches the contents of the dataset from the collection.
remove( )Removes the current item.
revert( )Reverts the current item to its saved value.
save( )Saves the current item.
setCurrentItemIndex( )Sets the current item by index.
setFieldValue( )Updates the value of a field in the current item.
setFieldValues( )Updates the values of a set of fields in the current item.
setFilter( )Sets the dataset filter.
setPageSize( )Sets the dataset's page size.
setSort( )Sets the dataset sort order.

MIXES IN

?
Where some functionality is inherited from.
wix-dataset.Dataset

getCurrentItem( )

Returns the current item.

Description

The getCurrentItem() function returns an object whose key:value pairs are the field keys 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.

See Also

getCurrentItemIndex( ), setCurrentItemIndex( )

Syntax

function getCurrentItem(): Object
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Object
The current item, or null if there is no current item.

MIXED IN FROM

?
Where this functionality is inherited from.
wix-dataset.Dataset

Examples

Get the dataset's current item

let itemObj = $w("#myDataset").getCurrentItem();

/*  
 *  {
 *    "_id":                "fcec780a-3e37-4b64-8a66-37c552c53f99",
 *    "_owner":             "f6c0f9c3-a62d-7e9f-g58d-943829af244d9",
 *    "_createdDate":       "2017-05-01T17:19:03.823Z",
 *    "_updatedDate":       "2017-05-01T17:19:10.477Z",
 *    "title":              "Dr. ",
 *    "name":               "B",
 *    "link-dynamic-name":  "/myCollection/B"
 *  }
 */

Get the dataset's current item when the page loads

$w.onReady( () => {
  $w("#myDataset").onReady( () => {
    let itemObj = $w("#myDataset").getCurrentItem();

  } );

} );

/*  itemObj:
 *
 *  {
 *    "_id":                "fcec780a-3e37-4b64-8a66-37c552c53f99",
 *    "_owner":             "f6c0f9c3-a62d-7e9f-g58d-943829af244d9",
 *    "_createdDate":       "2017-05-01T17:19:03.823Z",
 *    "_updatedDate":       "2017-05-01T17:19:10.477Z",
 *    "title":              "Dr. ",
 *    "name":               "B",
 *    "link-dynamic-name":  "/myCollection/B"
 *  }
 */

getCurrentItemIndex( )

Returns the current item's index.

Description

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.

See Also

setCurrentItemIndex( ), getCurrentItem( )

Syntax

function getCurrentItemIndex(): number
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
number
The index of the current item, or null if there is no current item.

MIXED IN FROM

?
Where this functionality is inherited from.
wix-dataset.Dataset

getCurrentPageIndex( )

Gets the index of the dataset's current page.

Description

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.

Syntax

function getCurrentPageIndex(): number
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
number

MIXED IN FROM

?
Where this functionality is inherited from.
wix-dataset.Dataset

Examples

Get the current page's index

let pageCount = $w("#myDataset").getCurrentPageIndex(); // 1

getItems( )

Returns the selected items.

Description

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.

See Also

getCurrentItem( )

Syntax

function getItems(fromIndex: number, numberOfItems: number): Promise<GetItemsResult>
PARAMETERS
?
Values that you pass to a function.
fromIndex
number
The index of the first item to return.
numberOfItems
number
The number of items to return.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.

Fulfilled - The items retrieved and the total number of items in the dataset that match its filter criteria. Rejected - An error object.

MIXED IN FROM

?
Where this functionality is inherited from.
wix-dataset.Dataset

Examples

Get items from the dataset

$w("#myDataset").getItems(3, 2)
  .then( (result) => {
    let items = result.items;
    let totalCount = result.totalCount;
    let offset = result.offset;
  } )
  .catch( (err) => {
    let errMsg = err.message;
    let errCode = err.code;
  } );

Get items from the dataset when the page loads

$w.onReady( () => {
  $w("#myDataset").onReady( () => {
    $w("#myDataset").getItems(3, 2)
      .then( (result) => {
        let items = result.items;
        let totalCount = result.totalCount;
        let offset = result.offset;
      } )
      .catch( (err) => {
        let errMsg = err.message;
        let errCode = err.code;
      } );

  } );

} );

getNextDynamicPage( )

Gets the next dynamic page URL.

Description

The getNextDynamicPage() function can only be called on a dynamic page dataset.

The function returns a Promise that is resolved to the relative URL of the next dynamic page or null if there is no next page.

The next page is determined by the lexicographical order of the dynamic page relative URLs. You can see all of the relative URLs for a dynamic page by viewing the collection connected to the page.

URLs for items that do not match the dataset's filters are not returned.

For example, consider the following situation:

  • You have a collection of employees that contains a boolean field named Active.
  • Your dynamic page datset is filtered to only show employees where Active is true.
  • Some of your dynamic page URLs include:
    • employees/Alice
    • employees/Bob
    • employees/Cathy

If Bob is not an active employee, when you call getNextDynamicPage() from Alice's page, the returned Promise will resolve to "employees/Cathy".

Pass the returned URL to the to() function to navigate to the next dynamic page.

See Also

getPreviousDynamicPage( )

Syntax

function getNextDynamicPage(): Promise<string>
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<string>
Fulfilled - The URL of the next dynamic page, or null if there is no next page.

Examples

Get the URL of the next dynamic page

$w("#myDataset").getNextDynamicPage()
  .then( (next) => {
    // do something with next page URL
    // URL looks like: "/myCollection/Value"
  } );

Navigate to the next dynamic page

import wixLocation from 'wix-location';

$w("#myDataset").getNextDynamicPage()
  .then( (next) => {
    if(next){
      wixLocation.to(next);
    }
  } );

getPageSize( )

Gets the dataset's page size.

Description

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

See Also

setPageSize( )

Syntax

function getPageSize(): number
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
number

MIXED IN FROM

?
Where this functionality is inherited from.
wix-dataset.Dataset

Examples

Get the current page size

let pageSize = $w("#myDataset").getPageSize(); // 6

getPreviousDynamicPage( )

Gets the previous dynamic page URL.

Description

The getPreviousDynamicPage() function can only be called on a dynamic page dataset.

The function returns a Promise that is resolved to the relative URL of the previous dynamic page or null if there is no previous page.

The previous page is determined by the lexicographical order of the dynamic page relative URLs. You can see all of the relative URLs for a dynamic page by viewing the collection connected to the page.

URLs for items that do not match the dataset's filters are not returned.

For example, consider the following situation:

  • You have a collection of employees that contains a boolean field named Active.
  • Your dynamic page datset is filtered to only show employees where Active is true.
  • Some of your dynamic page URLs include:
    • employees/Alice
    • employees/Bob
    • employees/Cathy

If Bob is not an active employee, when you call getPreviousDynamicPage() from Cathy's page, the returned Promise will resolve to "employees/Alice".

Pass the returned URL to the to() function to navigate to the previous dynamic page.

See Also

getNextDynamicPage( )

Syntax

function getPreviousDynamicPage(): Promise<string>
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<string>
Fulfilled - The URL of the previous dynamic page, or null if there is no previous page.

Examples

Get the URL of the previous dynamic page

$w("#myDataset").getPreviousDynamicPage()
  .then( (prev) => {
    // do something with previous page URL
    // URL looks like: "/myCollection/Value"
  } );

Navigate to the previous dynamic page

import wixLocation from 'wix-location';

$w("#myDataset").getPreviousDynamicPage()
  .then( (prev) => {
    if(prev){
      wixLocation.to(prev);
    }
  } );

getTotalCount( )

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

Description

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.

Syntax

function getTotalCount(): number
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
number

MIXED IN FROM

?
Where this functionality is inherited from.
wix-dataset.Dataset

Examples

Get the number of items in the dataset that match its filter criteria

let count = $w("#myDataset").getTotalCount(); // 23

Get the number of items in the dataset that match its filter criteria when the page loads

$w.onReady( () => {
  $w("#myDataset").onReady( () => {
    let count = $w("#myDataset").getTotalCount(); // 23

  } );
  
} );

getTotalPageCount( )

Gets the number of pages in the dataset.

Description

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.

Syntax

function getTotalPageCount(): number
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
number

MIXED IN FROM

?
Where this functionality is inherited from.
wix-dataset.Dataset

Examples

Get the number of pages in the dataset

let pageCount = $w("#myDataset").getTotalPageCount(); // 4

hasNext( )

Indicates if there is a next item.

Description

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.

See Also

hasPrevious( )

Syntax

function hasNext(): boolean
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
boolean

MIXED IN FROM

?
Where this functionality is inherited from.
wix-dataset.Dataset

Examples

Get whether the current item is the last item

let hasNext = $w("#myDataset").hasNext(); // true

Get whether the current item is the last item when the page loads

$w.onReady( () => {
  $w("#myDataset").onReady( () => {
    let hasNext = $w("#myDataset").hasNext(); // true

  } );
  
} );

hasNextPage( )

Indicates if there is a next page of data.

Description

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.

See Also

nextPage( ), hasPreviousPage( )

Syntax

function hasNextPage(): boolean
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
boolean

MIXED IN FROM

?
Where this functionality is inherited from.
wix-dataset.Dataset

Examples

Get whether the current page is the last page of data

let hasNextPage = $w("#myDataset").hasNextPage(); // true

Get whether the current page is the last page of data when the page loads

$w.onReady( () => {
  $w("#myDataset").onReady( () => {
    let hasNextPage = $w("#myDataset").hasNextPage(); // true

  } );

} );

hasPrevious( )

Indicates if there is a previous item.

Description

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.

See Also

hasNext( )

Syntax

function hasPrevious(): boolean
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
boolean

MIXED IN FROM

?
Where this functionality is inherited from.
wix-dataset.Dataset

Examples

Get whether the current item is the first item

let hasPrevious = $w("#myDataset").hasPrevious(); // true

Get whether the current item is the first item when the page loads

$w.onReady( () => {
  $w("#myDataset").onReady( () => {
    let hasPrevious = $w("#myDataset").hasPrevious(); // true

  } );
  
} );

hasPreviousPage( )

Indicates if there is a previous page of data.

Description

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.

See Also

previousPage( ), hasNextPage( )

Syntax

function hasPreviousPage(): boolean
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
boolean

MIXED IN FROM

?
Where this functionality is inherited from.
wix-dataset.Dataset

Examples

Get whether the current page is the first page of data

let hasPreviousPage = $w("#myDataset").hasPreviousPage(); // true

Get whether the current page is the first page of data when the page loads

$w.onReady( () => {
  $w("#myDataset").onReady( () => {
    let hasPreviousPage = $w("#myDataset").hasPreviousPage(); // true

  } );

} );

loadMore( )

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

Description

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.

Syntax

function loadMore(): Promise<void>
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<void>

Fulfilled - When the additional data has been loaded and any connected repeaters have been updated. Rejected - An error message.

MIXED IN FROM

?
Where this functionality is inherited from.
wix-dataset.Dataset

Examples

Load more dataset content

$w("#myDataset").loadMore()
  .then( () => {
    console.log("Done loading more data");
  } );

Load more dataset content when the page loads

$w.onReady( () => {
  $w("#myDataset").onReady( () => {
    $w("#myDataset").loadMore()
      .then( () => {
        console.log("Done loading more data");
      } );

  } );

} );

loadPage( )

Loads the specified page.

Description

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.

Note

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.

See Also

previousPage( ), nextPage( )

Syntax

function loadPage(pageIndex: number): Promise<Array<Object>>
PARAMETERS
?
Values that you pass to a function.
pageIndex
number
The index of the page to load.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<Array<Object>>

Fulfilled - When the specified page has been loaded and any connected elements have been updated. Rejected - An error message.

MIXED IN FROM

?
Where this functionality is inherited from.
wix-dataset.Dataset

Examples

Move to the fourth page of dataset content

$w("#myDataset").loadPage(4)
  .then( (items) => {
    let firstItem = items[0];
    let fieldValue = firstItem.fieldName;
  } )
  .catch( (err) => {
    let errMsg = err.message;
    let errCode = err.code;
  } );

Move to the fourth page of dataset content when the page loads

$w.onReady( () => {
  $w("#myDataset").onReady( () => {
    $w("#myDataset").loadPage(4)
      .then( (items) => {
        let firstItem = items[0];
        let fieldValue = firstItem.fieldName;
      } )
      .catch( (err) => {
        let errMsg = err.message;
        let errCode = err.code;
      } );

  } );

} );

new( )

Create a new blank item.

Description

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.

Syntax

function new(): Promise<void>
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<void>

Fulfilled - When a new empty item is the current item of the dataset. Rejected - An error message.

MIXED IN FROM

?
Where this functionality is inherited from.
wix-dataset.Dataset

Examples

Save the current item and create a new blank item

$w("#myDataset").new()
  .then( ( ) => {
    console.log("New item created");
  } )
  .catch( (err) => {
    let errMsg = err;
  } );

Save the current item and create a new blank item when the page loads

$w.onReady( () => {
  $w("#myDataset").onReady( () => {
    $w("#myDataset").new()
      .then( ( ) => {
        console.log("New item created");
      } )
      .catch( (err) => {
        let errMsg = err;
      } );

  } );
  
} );

next( )

Saves the current item and moves to the next item.

Description

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.

Note

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.

See Also

previous( ), hasNext( )

Syntax

function next(): Promise<Object>
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<Object>

Fulfilled - The next item in the dataset. Rejected - An error message.

MIXED IN FROM

?
Where this functionality is inherited from.
wix-dataset.Dataset

Examples

Move to the next item

$w("#myDataset").next()
  .then( (item) => {
    let fieldValue = item.fieldName;
  } )
  .catch( (err) => {
    let errMsg = err;
  } );

Move to the next item when the page loads

$w.onReady( () => {
  $w("#myDataset").onReady( () => {
    $w("#myDataset").next()
      .then( (item) => {
        let fieldValue = item.fieldName;
      } )
      .catch( (err) => {
        let errMsg = err;
      } );

  } );
  
} );

nextPage( )

Moves to the next page of data.

Description

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.

Note

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.

See Also

previousPage( ), hasNextPage( ), loadPage( )

Syntax

function nextPage(): Promise<Array<Object>>
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<Array<Object>>

Fulfilled - When the next page of data has been loaded and any connected elements have been updated. Rejected - An error message.

MIXED IN FROM

?
Where this functionality is inherited from.
wix-dataset.Dataset

Examples

Move to the next page of dataset content

$w("#myDataset").nextPage()
  .then( (items) => {
    let firstItem = items[0];
    let fieldValue = firstItem.fieldName;
  } )
  .catch( (err) => {
    let errMsg = err.message;
    let errCode = err.code;
  } );

Move to the next page of dataset content when the page loads

$w.onReady( () => {
  $w("#myDataset").onReady( () => {
    $w("#myDataset").nextPage()
      .then( (items) => {
        let firstItem = items[0];
        let fieldValue = firstItem.fieldName;
      } )
      .catch( (err) => {
        let errMsg = err.message;
        let errCode = err.code;
      } );

  } );

} );

onAfterSave( )

Adds an event handler that runs just after a save.

Description

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.

Syntax

function onAfterSave(handler: AfterSaveHandler): void
callback AfterSaveHandler(itemBeforeSave: Object, itemAfterSave: Object): void
PARAMETERS
?
Values that you pass to a function.
handler
function(itemBeforeSave: Object, itemAfterSave: Object)
The after save event handler.
?
Values that you pass to a function.
itemBeforeSave
Object
The item before being saved.
itemAfterSave
Object
The item after being saved.

MIXED IN FROM

?
Where this functionality is inherited from.
wix-dataset.Dataset

Examples

Register a callback to run after a save

$w("#myDataset").onAfterSave( () => {
  console.log("After save");
} );

onBeforeSave( )

Adds an event handler that runs just before a save.

Description

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 either false, a rejected Promise, or it throws an error, the save operation is canceled.

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

Syntax

function onBeforeSave(handler: BeforeSaveHandler): void
callback BeforeSaveHandler(): Promise<boolean>
PARAMETERS
?
Values that you pass to a function.
handler
function()
The before save event handler.

MIXED IN FROM

?
Where this functionality is inherited from.
wix-dataset.Dataset

Examples

Register a callback to run before a save and continue with the save

$w("#myDataset").onBeforeSave( () => {
  console.log("Continuing save");
} );

Register a callback to run before a save and cancel the save

$w("#myDataset").onBeforeSave( () => {
  console.log("Canceling save");
  return false;
} );

onCurrentIndexChanged( )

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

Description

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.

Syntax

function onCurrentIndexChanged(handler: CurrentIndexChangedHandler): void
callback CurrentIndexChangedHandler(index: number): void
PARAMETERS
?
Values that you pass to a function.
handler
function(index: number)
The current index change event handler.
?
Values that you pass to a function.
index
number
The new index.

MIXED IN FROM

?
Where this functionality is inherited from.
wix-dataset.Dataset

Examples

Register a callback to run when the current index changes

$w("#myDataset").onCurrentIndexChanged( (index) => {
  let newIndex = index; // 3
} );

onError( )

Adds an event handler that runs when an error occurs.

Description

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"

Syntax

function onError(handler: ErrorHandler): void
callback ErrorHandler(operation: string, error: DatasetError): void
PARAMETERS
?
Values that you pass to a function.
handler
function(operation: string, error: DatasetError)
The error handler.
?
Values that you pass to a function.
operation
string
The operation during which the error occurred.
error
The error that occurred.

MIXED IN FROM

?
Where this functionality is inherited from.
wix-dataset.Dataset

Examples

Register a callback to run when an error occurs

$w("#myDataset").onError( (operation, error) => {
  let errorOp = operation;    // "save"

  let errorCode = error.code; // "DS_VALIDATION_ERROR"

  let errorMessage = error.message;
  // DatasetError: Some of the elements validation failed
} );

onItemValuesChanged( )

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

Description

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.

Syntax

function onItemValuesChanged(handler: ItemValuesChangedHandler): void
callback ItemValuesChangedHandler(itemBeforeChange: Object, updatedItem: Object): void
PARAMETERS
?
Values that you pass to a function.
handler
function(itemBeforeChange: Object, updatedItem: Object)
The current value changed event handler.
?
Values that you pass to a function.
itemBeforeChange
Object
The item before the change.
updatedItem
Object
The updated item.

MIXED IN FROM

?
Where this functionality is inherited from.
wix-dataset.Dataset

Examples

Register a callback to run when the current item's values change

$w("#myDataset").onItemValuesChanged( (itemBeforeChange, updatedItem) => {
  let oldValue = itemBeforeChange.fieldName;
  let newValue = updatedItem.fieldName;
} );

onReady( )

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

Description

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.

Syntax

function onReady(handler: ReadyHandler): void
callback ReadyHandler(): void
PARAMETERS
?
Values that you pass to a function.
handler
function()
The ready handler.

MIXED IN FROM

?
Where this functionality is inherited from.
wix-dataset.Dataset

Examples

Register a callback to run after the dataset is ready

$w("#myDataset").onReady( () => {
  console.log("The dataset is ready");
} );

previous( )

Saves the current item and moves to the previous item.

Description

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.

Note

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.

See Also

next( ), hasPrevious( )

Syntax

function previous(): Promise<Object>
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<Object>

Fulfilled - The previous item in the dataset. Rejected - An error message.

MIXED IN FROM

?
Where this functionality is inherited from.
wix-dataset.Dataset

Examples

Move to the previous item

$w("#myDataset").previous()
  .then( (item) => {
    let fieldValue = item.fieldName;
  } )
  .catch( (err) => {
    let errMsg = err;
  } );

Move to the previous item when page loads

$w.onReady( () => {
  $w("#myDataset").onReady( () => {
    $w("#myDataset").previous()
      .then( (item) => {
        let fieldValue = item.fieldName;
      } )
      .catch( (err) => {
        let errMsg = err;
      } );

  } );
  
} );

previousPage( )

Moves to the previous page of data.

Description

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

Note

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.

See Also

nextPage( ), hasPreviousPage( ), loadPage( )

Syntax

function previousPage(): Promise<Array<Object>>
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<Array<Object>>

Fulfilled - When the previous page of data has been loaded and any connected repeaters have been updated. Rejected - An error message.

MIXED IN FROM

?
Where this functionality is inherited from.
wix-dataset.Dataset

Examples

Move to the previous page of dataset content

$w("#myDataset").previousPage()
  .then( (result) => {
    let firstItem = items[0];
    let fieldValue = firstItem.fieldName;
  } )
  .catch( (err) => {
    let errMsg = err.message;
    let errCode = err.code;
  } );

Move to the previous page of dataset content when the page loads

$w.onReady( () => {
  $w("#myDataset").onReady( () => {
    $w("#myDataset").previousPage()
      .then( (result) => {
        let firstItem = items[0];
        let fieldValue = firstItem.fieldName;
      } )
      .catch( (err) => {
        let errMsg = err.message;
        let errCode = err.code;
      } );

  } );

} );

refresh( )

Refetches the contents of the dataset from the collection.

Description

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.

See Also

revert( ), save( )

Syntax

function refresh(): Promise<void>
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<void>

Fulfilled - When the refresh is finished. Rejected - An error message.

MIXED IN FROM

?
Where this functionality is inherited from.
wix-dataset.Dataset

Examples

Refresh the dataset contents

$w("#myDataset").refresh()
  .then( () => {
    console.log("Done refreshing the dataset");
  } );

Refresh the dataset contents when the page loads

$w.onReady( () => {
  $w("#myDataset").onReady( () => {
    $w("#myDataset").refresh()
      .then( () => {
        console.log("Done refreshing the dataset");
      } );

  } );

} );

remove( )

Removes the current item.

Description

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.

See Also

revert( ), refresh( )

Syntax

function remove(): Promise<void>
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<void>
Fulfilled - When the current item has been removed from the collection.

MIXED IN FROM

?
Where this functionality is inherited from.
wix-dataset.Dataset

Examples

Remove the current item

$w("#myDataset").remove()
  .then( () => {
    console.log("Done removing current item");
  } );

Remove the current item when the page loads

$w.onReady( () => {
  $w("#myDataset").onReady( () => {
    $w("#myDataset").remove()
      .then( () => {
        console.log("Done removing current item");
      } );
    
  } );

} );

revert( )

Reverts the current item to its saved value.

Description

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.

See Also

refresh( ), save( )

Syntax

function revert(): Promise<void>
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<void>

Fulfilled - When the item has been reverted to its saved state. Rejected - An error message.

MIXED IN FROM

?
Where this functionality is inherited from.
wix-dataset.Dataset

Examples

Revert the current item

$w("#myDataset").revert()
  .then( () => {
    console.log("Done reverting the item");
  } )
  .catch( (err) => {
    let errMsg = err;
  } );

Revert the current item when the page loads

$w.onReady( () => {
  $w("#myDataset").onReady( () => {
    $w("#myDataset").revert()
      .then( () => {
        console.log("Done reverting the item");
      } )
      .catch( (err) => {
        let errMsg = err;
      } );

  } );

} );

save( )

Saves the current item.

Description

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.

Note

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() function inside the page’s onReady() event handler to ensure that both the page and the dataset have finished loading.

See Also

revert( ), refresh( )

Syntax

function save(): Promise<Object>
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<Object>

Fulfilled - The saved item. Rejected - An error message.

MIXED IN FROM

?
Where this functionality is inherited from.
wix-dataset.Dataset

Examples

Save the current item

$w("#myDataset").save()
  .then( (item) => {
    let fieldValue = item.fieldName;
  } )
  .catch( (err) => {
    let errMsg = err;
  } );

Save the current item when the page loads

$w.onReady( () => {
  $w("#myDataset").onReady( () => {
    $w("#myDataset").save()
      .then( (item) => {
        let fieldValue = item.fieldName;
      } )
      .catch( (err) => {
        let errMsg = err;
      } );

  } );

} );

setCurrentItemIndex( )

Sets the current item by index.

Description

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.

Note

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.

setCurrentItemIndex() saves the current item even if the requested item is same as the current item.

See Also

getCurrentItemIndex( ), getCurrentItem( )

Syntax

function setCurrentItemIndex(index: number): Promise<void>
PARAMETERS
?
Values that you pass to a function.
index
number
The index of the item to set as the current item.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<void>

Fulfilled - When the item with the given index is set to the current item. Rejected - Rejects if the item with the given index does not exist or it cannot be set to the current item.

MIXED IN FROM

?
Where this functionality is inherited from.
wix-dataset.Dataset

Examples

Set the dataset's current item

$w("#myDataset").setCurrentItemIndex(3);

Set the dataset's current item when the page loads

$w.onReady( () => {
  $w("#myDataset").onReady( () => {
    $w("#myDataset").setCurrentItemIndex(3)
      .then( () => {
        console.log("Done setting current item");
      } );

  } );
  
} );

setFieldValue( )

Updates the value of a field in the current item.

Description

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.

See Also

setFieldValues( )

Syntax

function setFieldValue(fieldKey: string, value: *): void
PARAMETERS
?
Values that you pass to a function.
fieldKey
string
The field key of the field to update.
value
*
The new value.

MIXED IN FROM

?
Where this functionality is inherited from.
wix-dataset.Dataset

Examples

Set a field's value

$w("#myDataset").setFieldValue("title", "New Title");

Set a field's value and save the item to the connected collection

$w("#myDataset").setFieldValue("title", "New Title");
$w("#myDataset").save();

Set a field's value when the page loads

$w.onReady( () => {
  $w("#myDataset").onReady( () => {
    $w("#myDataset").setFieldValue("title", "New Title");

  } );
  
} );

setFieldValues( )

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

Description

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.

See Also

setFieldValue( )

Syntax

function setFieldValues(fieldValues: Object): void
PARAMETERS
?
Values that you pass to a function.
fieldValues
Object
A map of field keys to new values.

MIXED IN FROM

?
Where this functionality is inherited from.
wix-dataset.Dataset

Examples

Set several fields' values

$w("#myDataset").setFieldValues( {
  "title":  "New Title",
  "name":   "New Name"
} );

Set several fields' values when the page loads

$w.onReady( () => {
  $w("#myDataset").onReady( () => {
    $w("#myDataset").setFieldValues( {
      "title":  "New Title",
      "name":   "New Name"
    } );

  } );
  
} );

setFilter( )

Sets the dataset filter.

Description

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.

Note

When using the and, not, or or functions, be sure to pass them a WixDataFilter object created by calling the filter() function and not a WixDataQuery object.

See Also

setSort( )

Syntax

function setFilter(filter: WixDataFilter): Promise<void>
PARAMETERS
?
Values that you pass to a function.
filter
A wix-data filter object.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<void>

Fulfilled - When the filter has been set. Rejected - An error object.

MIXED IN FROM

?
Where this functionality is inherited from.
wix-dataset.Dataset

Examples

Set a dataset's filter

This example filters a dataset to only have items where the lastname field starts with "D" and the age field is greater or equal to 21.

import wixData from 'wix-data';

// ...

$w("#myDataset").setFilter( wixData.filter()
  .startsWith("lastName", "D")
  .ge("age", "21")
);

Build and set a dataset's filter

This example builds a filter based on certain conditions. It then uses the built filter to filter a dataset.

import wixData from 'wix-data';

// ...

function filter(low, high) {
  let filter = wixData.filter();

  if(low) {
    filter = filter.ge("price", low);
  }

  if(high) {
    filter = filter.le("length", high);
  }

  $w("#myDataset").setFilter(filter);
}

Set a dataset's filter

import wixData from 'wix-data';

// ...

$w("#myDataset").setFilter( wixData.filter()
  .startsWith("lastName", "D")
  .ge("age", "21")
)
.then( () => {
  console.log("Dataset is now filtered");
} )
.catch( (err) => {
  console.log(err);
} );

Clear a dataset's filters

import wixData from 'wix-data';

// ...

$w("#myDataset").setFilter( wixData.filter() );

Set a dataset's filter with an or condition

import wixData from 'wix-data';

// ...

$w("#myDataset").setFilter( wixData.filter()
  .startsWith("lastName", "D")
  .or(
    wixData.filter()
      .ge("age", "21")
  )
)
.then( () => {
  console.log("Dataset is now filtered");
} )
.catch( (err) => {
  console.log(err);
} );

setPageSize( )

Sets the dataset's page size.

Description

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.

See Also

getPageSize( )

Syntax

function setPageSize(pageSize: number): Promise<void>
PARAMETERS
?
Values that you pass to a function.
pageSize
number
The new page size.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<void>

Fulfilled - When the page size has been set. Rejected - An error object.

MIXED IN FROM

?
Where this functionality is inherited from.
wix-dataset.Dataset

Examples

Set a dataset's page size

$w("#myDataset").setPageSize(6)
  .then( () => {
    console.log("Page size set.");
  } )
  .catch( (err) => {
    let errMsg = err.message;
    let errCode = err.code;
  } );

setSort( )

Sets the dataset sort order.

Description

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 Wix Data 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.

See Also

setFilter( )

Syntax

function setSort(sort: WixDataSort): Promise<void>
PARAMETERS
?
Values that you pass to a function.
sort
A wix-data sort object.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<void>

Fulfilled - When the sort has been set. Rejected - An error message.

MIXED IN FROM

?
Where this functionality is inherited from.
wix-dataset.Dataset

Examples

Set a dataset's sort

This example sorts a dataset by lastname field in ascending order and when more than one item has the same lastname value they are sorted by the age field in descending order.

import wixData from 'wix-data';

// ...

$w("#myDataset").setSort( wixData.sort()
  .ascending("lastName")
  .descending("age")
);

Build and set a dataset's sort

This example builds a sort based on certain conditions. It then uses the built sort to sort a dataset.

import wixData from 'wix-data';

// ...

function sort(name, dob) {
  let sort = wixData.sort();

  if(name === "desc") {
    sort = sort.descending("name");
  }
  else {
    sort = sort.ascending("name");
  }

  if(dob === "desc") {
    sort = sort.descending("dob");
  }
  else {
    sort = sort.ascending("dob");
  }

  $w("#myDataset").setSort(sort);
}

Set a dataset's sort

import wixData from 'wix-data';

// ...

$w("#myDataset").setSort( wixData.sort()
  .ascending("lastName")
  .descending("age")
)
.then( () => {
  console.log("Dataset is now sorted");
} )
.catch( (err) => {
  console.log(err);
} );

Clear a dataset's sorts

import wixData from 'wix-data';

// ...

$w("#myDataset").setSort( wixData.sort() );