wix-dataset

wix-dataset

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

A dataset serves as an intermediary between page elements, such as input elements and buttons, and the data in a collection. The dataset controls which collection is available to be used by page elements, what those elements can do with the collection data (display, add, modify), which item is currently active and whether the data is filtered or sorted.

A dataset can be in one of three modes, which are set in Dataset Settings panel in the Editor. The dataset's mode cannot be changed programmatically.

  • Read & Write: Display and modify data.
  • Read-only: Display data.
  • Write-only: Add new data.

Dataset modes

Another way to work with collection data and page elements is to use the Data API. The Data API lets you work directly with your collections. However, you'll need to write code to read from and write to your page elements. Using the Dataset API allows you to take advantage of the data binding that can be set up in the Editor's connect panels.

The wix-dataset API can only be used in your site’s front-end code.

You do not need to import wix-dataset.

Dataset Pages

Datasets retrieve information from your collections in chunks of items. Each of these chunks is called a page.

A dataset's page size determines how many items are initially displayed in repeaters that are connected to it. Elements that have their own settings for how many items are shown at once, such as tables and galleries, are not affected by the dataset's page size.

Elements that display data from the dataset's current item, such as images and text elements, are affected when you change the current dataset page because the dataset's current item also changes.

You set the page size of a dataset:

  • In the Editor using the Number of items to display setting in the Dataset Settings panel.
  • In code using the setPageSize() function.

Contents

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.
GetItemsResult An object used by the getItems() function that contains the items retrieved and the total number of items in the dataset that match its filter criteria
getCurrentItem( )

getCurrentItem( )

Returns the current item.

function getCurrentItem(): Object

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.

Return Value

Object The current item, or null if there is no current item.

Examples

Get the dataset's current item

bGV0IGl0ZW1PYmogPSAkdygiI215RGF0YXNldCIpLmdldEN1cnJlbnRJdGVtKCk7CgovKiAgCiAqICB7CiAqICAgICJfaWQiOiAgICAgICAgICAgICAgICAiZmNlYzc4MGEtM2UzNy00YjY0LThhNjYtMzdjNTUyYzUzZjk5IiwKICogICAgIl9vd25lciI6ICAgICAgICAgICAgICJmNmMwZjljMy1hNjJkLTdlOWYtZzU4ZC05NDM4MjlhZjI0NGQ5IiwKICogICAgIl9jcmVhdGVkRGF0ZSI6ICAgICAgICIyMDE3LTA1LTAxVDE3OjE5OjAzLjgyM1oiLAogKiAgICAiX3VwZGF0ZWREYXRlIjogICAgICAgIjIwMTctMDUtMDFUMTc6MTk6MTAuNDc3WiIsCiAqICAgICJ0aXRsZSI6ICAgICAgICAgICAgICAiRHIuICIsCiAqICAgICJuYW1lIjogICAgICAgICAgICAgICAiQiIsCiAqICAgICJsaW5rLWR5bmFtaWMtbmFtZSI6ICAiL215Q29sbGVjdGlvbi9CIgogKiAgfQogKi8K
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

JHcub25SZWFkeSggKCkgPT4gewogICR3KCIjbXlEYXRhc2V0Iikub25SZWFkeSggKCkgPT4gewogICAgbGV0IGl0ZW1PYmogPSAkdygiI215RGF0YXNldCIpLmdldEN1cnJlbnRJdGVtKCk7CgogIH0gKTsKCn0gKTsKCi8qICBpdGVtT2JqOgogKgogKiAgewogKiAgICAiX2lkIjogICAgICAgICAgICAgICAgImZjZWM3ODBhLTNlMzctNGI2NC04YTY2LTM3YzU1MmM1M2Y5OSIsCiAqICAgICJfb3duZXIiOiAgICAgICAgICAgICAiZjZjMGY5YzMtYTYyZC03ZTlmLWc1OGQtOTQzODI5YWYyNDRkOSIsCiAqICAgICJfY3JlYXRlZERhdGUiOiAgICAgICAiMjAxNy0wNS0wMVQxNzoxOTowMy44MjNaIiwKICogICAgIl91cGRhdGVkRGF0ZSI6ICAgICAgICIyMDE3LTA1LTAxVDE3OjE5OjEwLjQ3N1oiLAogKiAgICAidGl0bGUiOiAgICAgICAgICAgICAgIkRyLiAiLAogKiAgICAibmFtZSI6ICAgICAgICAgICAgICAgIkIiLAogKiAgICAibGluay1keW5hbWljLW5hbWUiOiAgIi9teUNvbGxlY3Rpb24vQiIKICogIH0KICovCg==
$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"
 *  }
 */

See Also

getCurrentItemIndex( ), setCurrentItemIndex( )

getCurrentItemIndex( )

getCurrentItemIndex( )

Returns the current item's index.

function getCurrentItemIndex(): Number

Description

The getCurrentItemIndex() function returns the index of current item within the items of the dataset. The indicies 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.

Return Value

Number The index of the current item, or null if there is no current item.

See Also

setCurrentItemIndex( ), getCurrentItem( )

getCurrentPageIndex( )

getCurrentPageIndex( )

Gets the index of the dataset's current page.

function getCurrentPageIndex(): number

Description

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

Return Value

Number

Examples

Get the current page's index

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

getItems( )

Returns the selected items.

function getItems(fromIndex: Number, numberOfItems: Number):
  Promise<GetItemsResult>

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.

Parameters

fromIndex Number The index of the first item to return.
numberOfItems Number The number of items to return.

Return Value

Returns a Promise

On fulfillment GetItemsResult The items retrieved and the total number of items in the dataset that match its filter criteria.
On rejection Error An error object.

Examples

Get items from the dataset

JHcoIiNteURhdGFzZXQiKS5nZXRJdGVtcygzLCAyKQogIC50aGVuKCAocmVzdWx0KSA9PiB7CiAgICBsZXQgaXRlbXMgPSByZXN1bHQuaXRlbXM7CiAgICBsZXQgdG90YWxDb3VudCA9IHJlc3VsdC50b3RhbENvdW50OwogICAgbGV0IG9mZnNldCA9IHJlc3VsdC5vZmZzZXQ7CiAgfSApCiAgLmNhdGNoKCAoZXJyKSA9PiB7CiAgICBsZXQgZXJyTXNnID0gZXJyLm1lc3NhZ2U7CiAgICBsZXQgZXJyQ29kZSA9IGVyci5jb2RlOwogIH0gKTsK
$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

JHcub25SZWFkeSggKCkgPT4gewogICR3KCIjbXlEYXRhc2V0Iikub25SZWFkeSggKCkgPT4gewogICAgJHcoIiNteURhdGFzZXQiKS5nZXRJdGVtcygzLCAyKQogICAgICAudGhlbiggKHJlc3VsdCkgPT4gewogICAgICAgIGxldCBpdGVtcyA9IHJlc3VsdC5pdGVtczsKICAgICAgICBsZXQgdG90YWxDb3VudCA9IHJlc3VsdC50b3RhbENvdW50OwogICAgICAgIGxldCBvZmZzZXQgPSByZXN1bHQub2Zmc2V0OwogICAgICB9ICkKICAgICAgLmNhdGNoKCAoZXJyKSA9PiB7CiAgICAgICAgbGV0IGVyck1zZyA9IGVyci5tZXNzYWdlOwogICAgICAgIGxldCBlcnJDb2RlID0gZXJyLmNvZGU7CiAgICAgIH0gKTsKCiAgfSApOwoKfSApOwo=
$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;
      } );

  } );

} );

See Also

getCurrentItem( )

getNextDynamicPage( )

getNextDynamicPage( )

Gets the next dynamic page URL.

function getNextDynamicPage(): Promise<String>

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.

Return Value

Returns a Promise

On fulfillment String The URL of the next dynamic page, or null if there is no next page.

Examples

Get the URL of the next dynamic page

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

Navigate to the next dynamic page

aW1wb3J0IHdpeExvY2F0aW9uIGZyb20gJ3dpeC1sb2NhdGlvbic7CgokdygiI215RGF0YXNldCIpLmdldE5leHREeW5hbWljUGFnZSgpCiAgLnRoZW4oIChuZXh0KSA9PiB7CiAgICBpZihuZXh0KXsKICAgICAgd2l4TG9jYXRpb24udG8obmV4dCk7CiAgICB9CiAgfSApOwo=
import wixLocation from 'wix-location';

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

See Also

getPreviousDynamicPage( )

getPageSize( )

getPageSize( )

Gets the dataset's page size.

function getPageSize(): number

Description

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

Return Value

Number

Examples

Get the current page size

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

See Also

setPageSize( )

getPreviousDynamicPage( )

getPreviousDynamicPage( )

Gets the previous dynamic page URL.

function getPreviousDynamicPage(): Promise<String>

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.

Return Value

Returns a Promise

On fulfillment String The URL of the previous dynamic page, or null if there is no previous page.

Examples

Get the URL of the previous dynamic page

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

Navigate to the previous dynamic page

aW1wb3J0IHdpeExvY2F0aW9uIGZyb20gJ3dpeC1sb2NhdGlvbic7CgokdygiI215RGF0YXNldCIpLmdldFByZXZpb3VzRHluYW1pY1BhZ2UoKQogIC50aGVuKCAocHJldikgPT4gewogICAgaWYocHJldil7CiAgICAgIHdpeExvY2F0aW9uLnRvKHByZXYpOwogICAgfQogIH0gKTsK
import wixLocation from 'wix-location';

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

See Also

getNextDynamicPage( )

getTotalCount( )

getTotalCount( )

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

function getTotalCount(): Number

Description

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

Return Value

Number

Examples

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

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

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

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

  } );
  
} );
getTotalPageCount( )

getTotalPageCount( )

Gets the number of pages in the dataset.

function getTotalPageCount(): number

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.

Return Value

Number

Examples

Get the number of pages in the dataset

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

hasNext( )

Indicates if there is a next item.

function hasNext(): boolean

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.

Return Value

Boolean

Examples

Get whether the current item is the last item

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

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

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

  } );
  
} );

See Also

hasPrevious( )

hasNextPage( )

hasNextPage( )

Indicates if there is a next page of data.

function hasNextPage(): boolean

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.

Return Value

Boolean

Examples

Get whether the current page is the last page of data

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

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

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

  } );

} );

See Also

nextPage( ), hasPreviousPage( )

hasPrevious( )

hasPrevious( )

Indicates if there is a previous item.

function hasPrevious(): boolean

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.

Return Value

Boolean

Examples

Get whether the current item is the first item

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

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

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

  } );
  
} );

See Also

hasNext( )

hasPreviousPage( )

hasPreviousPage( )

Indicates if there is a previous page of data.

function hasPreviousPage(): boolean

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.

Return Value

Boolean

Examples

Get whether the current page is the first page of data

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

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

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

  } );

} );

See Also

previousPage( ), hasNextPage( )

loadMore( )

loadMore( )

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

function loadMore(): Promise<void>

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.

Return Value

Returns a Promise

On fulfillment void When the additional data has been loaded and any connected repeaters have been updated.
On rejection String An error message.

Examples

Load more dataset content

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

Load more dataset content when the page loads

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

  } );

} );
loadPage( )

loadPage( )

Loads the specified page.

function loadPage(pageIndex: number): Promise<>

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 indicies of the dataset's pages start at 1.

Parameters

pageIndex Number The index of the page to load.

Return Value

Returns a Promise

On fulfillment Object[ ] When the specified page has been loaded and any connected elements have been updated.
On rejection String An error message.

Examples

Move to the fourth page of dataset content

JHcoIiNteURhdGFzZXQiKS5sb2FkUGFnZSg0KQogIC50aGVuKCAoaXRlbXMpID0+IHsKICAgIGxldCBmaXJzdEl0ZW0gPSBpdGVtc1swXTsKICAgIGxldCBmaWVsZFZhbHVlID0gZmlyc3RJdGVtLmZpZWxkTmFtZTsKICB9ICkKICAuY2F0Y2goIChlcnIpID0+IHsKICAgIGxldCBlcnJNc2cgPSBlcnIubWVzc2FnZTsKICAgIGxldCBlcnJDb2RlID0gZXJyLmNvZGU7CiAgfSApOwo=
$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

JHcub25SZWFkeSggKCkgPT4gewogICR3KCIjbXlEYXRhc2V0Iikub25SZWFkeSggKCkgPT4gewogICAgJHcoIiNteURhdGFzZXQiKS5sb2FkUGFnZSg0KQogICAgICAudGhlbiggKGl0ZW1zKSA9PiB7CiAgICAgICAgbGV0IGZpcnN0SXRlbSA9IGl0ZW1zWzBdOwogICAgICAgIGxldCBmaWVsZFZhbHVlID0gZmlyc3RJdGVtLmZpZWxkTmFtZTsKICAgICAgfSApCiAgICAgIC5jYXRjaCggKGVycikgPT4gewogICAgICAgIGxldCBlcnJNc2cgPSBlcnIubWVzc2FnZTsKICAgICAgICBsZXQgZXJyQ29kZSA9IGVyci5jb2RlOwogICAgICB9ICk7CgogIH0gKTsKCn0gKTsK
$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;
      } );

  } );

} );

See Also

previousPage( ), nextPage( )

new( )

new( )

Create a new blank item.

function new(): Promise<void>

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.

Return Value

Returns a Promise

On fulfillment void When a new empty item is the current item of the dataset.
On rejection String An error message.

Examples

Save the current item and create a new blank item

JHcoIiNteURhdGFzZXQiKS5uZXcoKQogIC50aGVuKCAoICkgPT4gewogICAgY29uc29sZS5sb2coIk5ldyBpdGVtIGNyZWF0ZWQiKTsKICB9ICkKICAuY2F0Y2goIChlcnIpID0+IHsKICAgIGxldCBlcnJNc2cgPSBlcnI7CiAgfSApOwo=
$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

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

  } );
  
} );
next( )

next( )

Saves the current item and moves to the next item.

function next(): Promise<Object>

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.

Return Value

Returns a Promise

On fulfillment Object The next item in the dataset.
On rejection String An error message.

Examples

Move to the next item

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

Move to the next item when the page loads

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

  } );
  
} );

See Also

previous( ), hasNext( )

nextPage( )

nextPage( )

Moves to the next page of data.

function nextPage(): Promise<Object[]>

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.

Return Value

Returns a Promise

On fulfillment Object[ ] When the next page of data has been loaded and any connected elements have been updated.
On rejection String An error message.

Examples

Move to the next page of dataset content

JHcoIiNteURhdGFzZXQiKS5uZXh0UGFnZSgpCiAgLnRoZW4oIChpdGVtcykgPT4gewogICAgbGV0IGZpcnN0SXRlbSA9IGl0ZW1zWzBdOwogICAgbGV0IGZpZWxkVmFsdWUgPSBmaXJzdEl0ZW0uZmllbGROYW1lOwogIH0gKQogIC5jYXRjaCggKGVycikgPT4gewogICAgbGV0IGVyck1zZyA9IGVyci5tZXNzYWdlOwogICAgbGV0IGVyckNvZGUgPSBlcnIuY29kZTsKICB9ICk7Cg==
$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

JHcub25SZWFkeSggKCkgPT4gewogICR3KCIjbXlEYXRhc2V0Iikub25SZWFkeSggKCkgPT4gewogICAgJHcoIiNteURhdGFzZXQiKS5uZXh0UGFnZSgpCiAgICAgIC50aGVuKCAoaXRlbXMpID0+IHsKICAgICAgICBsZXQgZmlyc3RJdGVtID0gaXRlbXNbMF07CiAgICAgICAgbGV0IGZpZWxkVmFsdWUgPSBmaXJzdEl0ZW0uZmllbGROYW1lOwogICAgICB9ICkKICAgICAgLmNhdGNoKCAoZXJyKSA9PiB7CiAgICAgICAgbGV0IGVyck1zZyA9IGVyci5tZXNzYWdlOwogICAgICAgIGxldCBlcnJDb2RlID0gZXJyLmNvZGU7CiAgICAgIH0gKTsKCiAgfSApOwoKfSApOwo=
$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;
      } );

  } );

} );

See Also

previousPage( ), hasNextPage( ), loadPage( )

onAfterSave( )

onAfterSave( )

Adds an event handler that runs just after a save.

function onAfterSave(handler: AfterSaveHandler): void
callback AfterSaveHandler(itemBeforeSave: Object, itemAfterSave: Object): void

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.

Parameters

handler function(itemBeforeSave, itemAfterSave) The after save event handler.
itemBeforeSave Object The item before being saved.
itemAfterSave Object The item after being saved.
Return Value void

Examples

Register a callback to run after a save

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

onBeforeSave( )

Adds an event handler that runs just before a save.

function onBeforeSave(handler: BeforeSaveHandler): void
callback BeforeSaveHandler(): Promise<boolean>

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

Parameters

handler function() The before save event handler.
On fulfillment Boolean Indication whether to continue with save.

Examples

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

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

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

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

onCurrentIndexChanged( )

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

function onCurrentIndexChanged(handler: CurrentIndexChangedHandler): void
callback CurrentIndexChangedHandler(index: Number): void

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.

Parameters

handler function(index) The current index change event handler.
index Number The new index.

Examples

Register a callback to run when the current index changes

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

onError( )

Adds an event handler that runs when an error occurs.

function onError(handler: ErrorHandler): void
callback ErrorHandler(operation: string, error: Error): void

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"

Parameters

handler function(operation, error) The error handler.
operation String The operation during which the error occurred.
error Error The error that occurred.

Examples

Register a callback to run when an error occurs

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

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

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

onItemValuesChanged( )

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

function onItemValuesChanged(handler: ItemValuesChangedHandler): void
callback ItemValuesChangedHandler(itemBeforeChange: Object,
  updatedItem: Object): void

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.

Parameters

handler function(itemBeforeChange, updatedItem) The current value changed event handler.
itemBeforeChange Object The item before the change.
updatedItem Object The updated item.

Examples

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

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

onReady( )

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

function onReady(handler: ReadyHandler): void
callback ReadyHandler(): void

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.

Examples

Register a callback to run after the dataset is ready

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

previous( )

Saves the current item and moves to the previous item.

function previous(): Promise<Object>

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.

Return Value

Returns a Promise

On fulfillment Object The previous item in the dataset.
On rejection String An error message.

Examples

Move to the previous item

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

Move to the previous item when page loads

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

  } );
  
} );

See Also

next( ), hasPrevious( )

previousPage( )

previousPage( )

Moves to the previous page of data.

function previousPage(): Promise<Object[]>

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.

Return Value

Returns a Promise

On fulfillment Object[ ] When the previous page of data has been loaded and any connected repeaters have been updated.
On rejection String An error message.

Examples

Move to the previous page of dataset content

JHcoIiNteURhdGFzZXQiKS5wcmV2aW91c1BhZ2UoKQogIC50aGVuKCAocmVzdWx0KSA9PiB7CiAgICBsZXQgZmlyc3RJdGVtID0gaXRlbXNbMF07CiAgICBsZXQgZmllbGRWYWx1ZSA9IGZpcnN0SXRlbS5maWVsZE5hbWU7CiAgfSApCiAgLmNhdGNoKCAoZXJyKSA9PiB7CiAgICBsZXQgZXJyTXNnID0gZXJyLm1lc3NhZ2U7CiAgICBsZXQgZXJyQ29kZSA9IGVyci5jb2RlOwogIH0gKTsK
$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

JHcub25SZWFkeSggKCkgPT4gewogICR3KCIjbXlEYXRhc2V0Iikub25SZWFkeSggKCkgPT4gewogICAgJHcoIiNteURhdGFzZXQiKS5wcmV2aW91c1BhZ2UoKQogICAgICAudGhlbiggKHJlc3VsdCkgPT4gewogICAgICAgIGxldCBmaXJzdEl0ZW0gPSBpdGVtc1swXTsKICAgICAgICBsZXQgZmllbGRWYWx1ZSA9IGZpcnN0SXRlbS5maWVsZE5hbWU7CiAgICAgIH0gKQogICAgICAuY2F0Y2goIChlcnIpID0+IHsKICAgICAgICBsZXQgZXJyTXNnID0gZXJyLm1lc3NhZ2U7CiAgICAgICAgbGV0IGVyckNvZGUgPSBlcnIuY29kZTsKICAgICAgfSApOwoKICB9ICk7Cgp9ICk7Cg==
$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;
      } );

  } );

} );

See Also

nextPage( ), hasPreviousPage( ), loadPage( )

refresh( )

refresh( )

Refetches the contents of the dataset from the collection.

function refresh(): Promise<void>

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.

Return Value

Returns a Promise

On fulfillment void When the refresh is finished.
On rejection String An error message.

Examples

Refresh the dataset contents

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

Refresh the dataset contents when the page loads

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

  } );

} );

See Also

revert( ), save( )

remove( )

remove( )

Removes the current item.

function remove(): Promise<void>

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.

Return Value

Returns a Promise

On fulfillment void When the current item has been removed from the collection.

Examples

Remove the current item

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

Remove the current item when the page loads

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

} );

See Also

revert( ), refresh( )

revert( )

revert( )

Reverts the current item to its saved value.

function revert(): Promise<void>

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.

Return Value

Returns a Promise

On fulfillment void When the item has been reverted to its saved state.
On rejection String An error message.

Examples

Revert the current item

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

Revert the current item when the page loads

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

  } );

} );

See Also

refresh( ), save( )

save( )

save( )

Saves the current item.

function save(): Promise<Object>

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.

Return Value

Returns a Promise

On fulfillment Object The saved item.
On rejection String An error message.

Examples

Save the current item

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

Save the current item when the page loads

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

  } );

} );

See Also

revert( ), refresh( )

setCurrentItemIndex( )

setCurrentItemIndex( )

Sets the current item by index.

function setCurrentItemIndex(index: Number): Promise<void>

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.

Parameters

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

Return Value

Returns a Promise

On fulfillment void When the item with the given index is set to the current item.
On rejection Error Rejects if the item with the given index does not exist or it cannot be set to the current item.

Examples

Set the dataset's current item

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

Set the dataset's current item when the page loads

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

  } );
  
} );

See Also

getCurrentItemIndex( ), getCurrentItem( )

setFieldValue( )

setFieldValue( )

Updates the value of a field in the current item.

function setFieldValue(fieldKey: string, value: *): void

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.

Parameters

fieldKey String The field key of the field to update.
value Object The new value.

Examples

Set a field's value

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

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

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

Set a field's value when the page loads

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

  } );
  
} );

See Also

setFieldValues( )

setFieldValues( )

setFieldValues( )

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

function setFieldValues(fieldValues: Object): void

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.

Parameters

fieldValues Object A map of field keys to new values.

Examples

Set several fields' values

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

Set several fields' values when the page loads

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

  } );
  
} );

See Also

setFieldValue( )

setFilter( )

setFilter( )

Sets the dataset filter.

function setFilter(filter: WixDataFilter): Promise<void>

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.

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.

Parameters

filter WixDataFilter A wix-data filter object.

Return Value

Returns a Promise

On fulfillment void When the filter has been set.
On rejection Error An error object.

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.

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKLy8gLi4uCgokdygiI215RGF0YXNldCIpLnNldEZpbHRlciggd2l4RGF0YS5maWx0ZXIoKQogIC5zdGFydHNXaXRoKCJsYXN0TmFtZSIsICJEIikKICAuZ2UoImFnZSIsICIyMSIpCik7Cg==
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.

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKLy8gLi4uCgpmdW5jdGlvbiBmaWx0ZXIobG93LCBoaWdoKSB7CiAgbGV0IGZpbHRlciA9IHdpeERhdGEuZmlsdGVyKCk7CgogIGlmKGxvdykgewogICAgZmlsdGVyID0gZmlsdGVyLmdlKCJwcmljZSIsIGxvdyk7CiAgfQoKICBpZihoaWdoKSB7CiAgICBmaWx0ZXIgPSBmaWx0ZXIubGUoImxlbmd0aCIsIGhpZ2gpOwogIH0KCiAgJHcoIiNteURhdGFzZXQiKS5zZXRGaWx0ZXIoZmlsdGVyKTsKfQo=
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

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKLy8gLi4uCgokdygiI215RGF0YXNldCIpLnNldEZpbHRlciggd2l4RGF0YS5maWx0ZXIoKQogIC5zdGFydHNXaXRoKCJsYXN0TmFtZSIsICJEIikKICAuZ2UoImFnZSIsICIyMSIpCikKLnRoZW4oICgpID0+IHsKICBjb25zb2xlLmxvZygiRGF0YXNldCBpcyBub3cgZmlsdGVyZWQiKTsKfSApCi5jYXRjaCggKGVycikgPT4gewogIGNvbnNvbGUubG9nKGVycik7Cn0gKTsK
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

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKLy8gLi4uCgokdygiI215RGF0YXNldCIpLnNldEZpbHRlciggd2l4RGF0YS5maWx0ZXIoKSApOwo=
import wixData from 'wix-data';

// ...

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

Set a dataset's filter with an or condition

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKLy8gLi4uCgokdygiI215RGF0YXNldCIpLnNldEZpbHRlciggd2l4RGF0YS5maWx0ZXIoKQogIC5zdGFydHNXaXRoKCJsYXN0TmFtZSIsICJEIikKICAub3IoCiAgICB3aXhEYXRhLmZpbHRlcigpCiAgICAgIC5nZSgiYWdlIiwgIjIxIikKICApCikKLnRoZW4oICgpID0+IHsKICBjb25zb2xlLmxvZygiRGF0YXNldCBpcyBub3cgZmlsdGVyZWQiKTsKfSApCi5jYXRjaCggKGVycikgPT4gewogIGNvbnNvbGUubG9nKGVycik7Cn0gKTsK
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);
} );

See Also

setSort( )

setPageSize( )

setPageSize( )

Sets the dataset's page size.

function setPageSize(pageSize: number): Promise<void>

Description

The setPage() 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 read-only dataset causes an error.

Parameters

pageSize Number The new page size.

Return Value

Returns a Promise

On fulfillment void When the page size has been set.
On rejection Error An error object.

Examples

Set a dataset's page size

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

See Also

getPageSize( )

setSort( )

setSort( )

Sets the dataset sort order.

function setSort(sort: WixDataSort): Promise<void>

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.

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.

Parameters

sort WixDataSort A wix-data sort object.

Return Value

Returns a Promise

On fulfillment void When the sort has been set.
On rejection String An error message.

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.

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKLy8gLi4uCgokdygiI215RGF0YXNldCIpLnNldFNvcnQoIHdpeERhdGEuc29ydCgpCiAgLmFzY2VuZGluZygibGFzdE5hbWUiKQogIC5kZXNjZW5kaW5nKCJhZ2UiKQopOwo=
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.

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKLy8gLi4uCgpmdW5jdGlvbiBzb3J0KG5hbWUsIGRvYikgewogIGxldCBzb3J0ID0gd2l4RGF0YS5zb3J0KCk7CgogIGlmKG5hbWUgPT09ICJkZXNjIikgewogICAgc29ydCA9IHNvcnQuZGVzY2VuZGluZygibmFtZSIpOwogIH0KICBlbHNlIHsKICAgIHNvcnQgPSBzb3J0LmFzY2VuZGluZygibmFtZSIpOwogIH0KCiAgaWYoZG9iID09PSAiZGVzYyIpIHsKICAgIHNvcnQgPSBzb3J0LmRlc2NlbmRpbmcoImRvYiIpOwogIH0KICBlbHNlIHsKICAgIHNvcnQgPSBzb3J0LmFzY2VuZGluZygiZG9iIik7CiAgfQoKICAkdygiI215RGF0YXNldCIpLnNldFNvcnQoc29ydCk7Cn0K
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

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKLy8gLi4uCgokdygiI215RGF0YXNldCIpLnNldFNvcnQoIHdpeERhdGEuc29ydCgpCiAgLmFzY2VuZGluZygibGFzdE5hbWUiKQogIC5kZXNjZW5kaW5nKCJhZ2UiKQopCi50aGVuKCAoKSA9PiB7CiAgY29uc29sZS5sb2coIkRhdGFzZXQgaXMgbm93IHNvcnRlZCIpOwp9ICkKLmNhdGNoKCAoZXJyKSA9PiB7CiAgY29uc29sZS5sb2coZXJyKTsKfSApOwo=
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

aW1wb3J0IHdpeERhdGEgZnJvbSAnd2l4LWRhdGEnOwoKLy8gLi4uCgokdygiI215RGF0YXNldCIpLnNldFNvcnQoIHdpeERhdGEuc29ydCgpICk7Cg==
import wixData from 'wix-data';

// ...

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

See Also

setFilter( )

GetItemsResult

GetItemsResult

An object used by the getItems() function that contains the items retrieved and the total number of items in the dataset that match its filter criteria

Properties

items Object[ ] List of items objects where key:value pairs are the field keys and field values of the retrieved items, including all hidden fields.
totalCount Number The number of items in the dataset that match its filter criteria.
offset Number The index in the dataset of the first item in the items property.

Examples

Get items from the dataset

JHcoIiNteURhdGFzZXQiKS5nZXRJdGVtcygzLCAyKQogIC50aGVuKCAocmVzdWx0KSA9PiB7CiAgICBsZXQgaXRlbXMgPSByZXN1bHQuaXRlbXM7CiAgICBsZXQgdG90YWxDb3VudCA9IHJlc3VsdC50b3RhbENvdW50OwogICAgbGV0IG9mZnNldCA9IHJlc3VsdC5vZmZzZXQ7CiAgfSApCiAgLmNhdGNoKCAoZXJyKSA9PiB7CiAgICBsZXQgZXJyTXNnID0gZXJyLm1lc3NhZ2U7CiAgICBsZXQgZXJyQ29kZSA9IGVyci5jb2RlOwogIH0gKTsK
$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;
  } );

See Also

getItems( )