About Datasets and Code

Datasets connect your CMS collections to page elements, allowing you to control how content displays and how visitors interact with it. Unlike the Data API which works directly with collections, datasets handle the connection between data and UI elements automatically.

You use datasets when you want to bind collection data to page elements without writing connection code. The Dataset API extends the built-in dataset functionality with additional control over filtering, sorting, pagination, and data validation.

Dataset API

The Dataset API includes methods to control dataset behavior and interact with collection data. For dynamic pages, use the Dynamic Dataset API which provides similar functionality with additional methods for dynamic page contexts.

These APIs contain the following functionality:

  • Dataset readiness: Use the dataset's onReady() method to ensure both the page and dataset have finished loading before your dataset-related code executes.
  • Current item: Datasets track which item is currently in focus, determining what data displays in connected elements and which item is affected by operations like save and remove.
  • Dynamic filtering and sorting: Beyond basic editor settings, you can dynamically modify filters and sorting based on site visitor interactions, enabling search functionality and custom sorting options.
  • Data validation and saving: Use event handlers like onBeforeSave() to implement custom validation when saving data from connected input elements.
  • Pagination and navigation: Implement custom pagination controls like "load more" functionality, infinite scrolling, or navigate between items based on site visitor actions.
  • Dynamic page navigation: The DynamicDataset API includes additional methods for navigating between dynamic pages, such as moving to the next or previous item's page in the collection.

Dataset modes

Dataset modes control the type of interaction between your dataset and collection data. They determine whether site visitors can view data, add new items, edit existing items, or some combination of these actions.

The mode you choose determines which dataset methods are available for you to call through the Dataset API.

The available modes are:

  • Read: Display collection content only. Allows read-only methods like getCurrentItem() and getItems(). Use for showing data without allowing modifications.
  • Write: Add new items only. Allows write-only methods like add() and save(). Use for forms that collect new data.
  • Read & Write: Display and modify content. Allows all dataset methods including remove() and navigation methods. Use for interactive pages where visitors can view and edit data.

See also

Did this help?