Skip to main content

WFCMSList 🆕

The WFCMSList class offers powerful functionality for loading, filtering, sorting, and paginating collection lists without the need for page redirection or refreshing.

Getting Started​

Initialization: To begin using the WFCMSList class in your xAtom project, you'll first need to install the @xatom/cmslist package. After installation, initialize WFCMSList as demonstrated in the example below:

Installing the package​

Terminal
npm install @xatom/cmslist
Example
import { WFCMSList } from "@xatom/cmslist";
import { onReady, WFComponent, createComponent } from "@xatom/core";

// Wait until the webflow page has loaded
onReady(() => {
  // Initialize WFCMSList with configuration object
  const cms = new WFCMSList(".cms", {
    numberOfItemPerPage: 10,
    removeNativePaginationElements: true,
  });

  // Clone an item as a template
  const itemClone = cms.getInitialItemAsTemplate();

  // Update the text content of the cloned item
  itemClone.updateTextViaAttrVar({
    title: "Hello World",
  });

  // Create a custom item using createComponent
  const myItem = createComponent("div");
  myItem.setTextContent("Another Item");

  // Wait for all collection items to be fetched
  cms.onAllCollectionItemsReady(() => {
    // Add the cloned item and the custom item to the CMS list
    cms.addItem(itemClone, 0); // Add to zeroth index
    cms.addItem(myItem, 1); // Add to first index
  });

  // Initialize WFComponent for the next button
  const nextBtn = new WFComponent(".next-btn");

  // Event listener for the next button to navigate to the next page
  nextBtn.on("click", () => {
    cms.goToNextPageIndex();
  });

  // Initialize WFComponent for the filter button
  const filterBtn = new WFComponent(".filter-btn");

  // Event listener for the filter button to apply a filter and render the list
  filterBtn.on("click", () => {
    cms.setFilterSortConfig({
      filter: (item, dataset) => {
        return dataset.title.includes("Hello");
      },
    });
    cms.goToPageIndex(0);
    cms.forceRenderList();
  });

  // Initialize WFComponent for the reset button
  const resetBtn = new WFComponent(".reset-btn");

  // Event listener for the reset button to clear the filter and render the list
  resetBtn.on("click", () => {
    cms.setFilterSortConfig({});
    cms.goToPageIndex(0);
    cms.forceRenderList();
  });
});

This example demonstrates the integration of WFCMSList into an xAtom project, showcasing the following features:

  • Waiting until all items are dynamically fetched from the collection.
  • Setting the maximum number of items per page.
  • Adding an item to the list even if it's not present in the collection.
  • Applying filters to the list and resetting the filter.
  • Obtaining a clone of the item template for customization.

Syntax

new WFCMSList(selector: string, config?: CMSListConfig);

Configuration Object​

NameTypeDescription
configCMSListConfigThe optional configuration object for customizing the behavior of the CMS list.

CMSListConfig object type

NameTypeDescription
numberOfItemPerPagenumberThe maximum number of items allowed per page. If set to 0, it means infinite items per page. Default is 0.
autoLoadAllItemsbooleanDetermines whether to automatically load all items on page load. Default is true.
removeNativePaginationElementsbooleanDetermines whether to remove Webflow's native pagination buttons. Default is true.
resetIX2booleanIf you are using Webflow interactions on the item, set resetIX2 to true. Default is true.

Note​

Compatibility with WFComponent

The WFCMSList seamlessly extends the capabilities of the WFComponent class. This means that all the properties and methods available in WFComponent are fully compatible and can be used with WFCMSList. This compatibility provides you with a wide range of options for enhancing and customizing the behavior of your cms lists. Feel free to leverage the power of both components to achieve your desired results efficiently.

Methods​

The WFCMSList class provides a comprehensive set of properties and methods to enhance your development workflow:

loadAllCollectionItems()​

The loadAllCollectionItems() method in the WFCMSList class allows you to load all items from paginated pages and add them to the current collection. This method is useful when autoLoadAllItems is set to false and you need to load items manually based on some interaction.

Example
// Initialize WFCMSList with autoLoadAllItems set to false
const list = new WFCMSList(".cms", { autoLoadAllItems: false });

// Load all items after a certain delay
setTimeout(() => {
    list.loadAllCollectionItems();
}, 5000);

Syntax

loadAllCollectionItems(): void;

addItem(el, index)​

The addItem() method in the WFCMSList class allows you to add a new item to the collection list at a specified index.

Example
// Initialize WFCMSList
const list = new WFCMSList(".cms");

// Create a new item using WFComponent
const newItem = new WFComponent(".new-item");

// Add the new item to the collection list at index 0
list.addItem(newItem, 0);

Syntax

addItem(el: WFComponent, index?: number): void;

Parameters​

NameTypeDescription
elWFComponentThe new item to add to the collection list.
index?numberThe optional index at which to add the item.

removeItem(index)​

The removeItem() method in the WFCMSList class allows you to remove an item from the collection list at the specified index.

Example
// Initialize WFCMSList
const list = new WFCMSList(".cms");

// Remove the item at index 0 from the collection list
list.removeItem(0);

Syntax

removeItem(index: number): void;

Parameters​

NameTypeDescription
index?numberThe index of the item to be removed.

getAllItems()​

The getAllItems() method in the WFCMSList class returns an array containing all items in the collection list.

Example
// Initialize WFCMSList
const list = new WFCMSList(".cms");

// Get all items from the collection list
const allItems = list.getAllItems();

console.log(allItems); // Array of WFComponent<HTMLDivElement>

Syntax

getAllItems(): WFComponent<HTMLDivElement>[];

getItemCount()​

The getItemCount() method in the WFCMSList class returns the total number of items in the collection list.

Example
// Initialize WFCMSList
const list = new WFCMSList(".cms");

// Get the total number of items in the collection list
const itemCount = list.getItemCount();

console.log(itemCount); // 20

Syntax

getItemCount(): number;

forceRenderList()​

The forceRenderList() method in the WFCMSList class forces the rendering of the collection list.

Example
// Initialize WFCMSList
const list = new WFCMSList(".cms");

// Force render the collection list
list.forceRenderList();

Syntax

forceRenderList(): void;

onLoadingChange(cb)​

The onLoadingChange() method in the WFCMSList class allows you to listen for changes in the loading status of the collection list.

Example
// Initialize WFCMSList
const list = new WFCMSList(".cms");

// Define a callback function
const loadingCallback = (status: boolean) => {
  console.log("Loading status:", status);
};

// Register the callback function to listen for loading status changes
const unregisterCallback = list.onLoadingChange(loadingCallback);

Syntax

onLoadingChange(cb: (status: boolean) => void): () => void;

Parameters​

NameTypeDescription
cb(status: boolean) => voidThe callback function to be invoked when the loading status changes.

Returns​

A function that can be called to unregister the callback.

onAllCollectionItemsReady(cb)​

The onAllCollectionItemsReady() method in the WFCMSList class allows you to listen for the event when all collection items are ready.

Example
// Initialize WFCMSList
const list = new WFCMSList(".cms");

// Define a callback function
const itemsReadyCallback = () => {
  console.log("All collection items are ready.");
};

// Register the callback function to listen for the event
const unregisterCallback = list.onAllCollectionItemsReady(itemsReadyCallback);

Syntax

onAllCollectionItemsReady(cb: () => void): () => void;

Parameters​

NameTypeDescription
cb() => voidThe callback function to be invoked when all collection items are ready.

Returns​

A function that can be called to unregister the callback.

getTotalPagesCount()​

The getTotalPagesCount() method in the WFCMSList class returns the total number of pages in the collection list.

Example
// Initialize WFCMSList
const list = new WFCMSList(".cms");

// Get the total number of pages
const totalPages = list.getTotalPagesCount();

console.log("Total pages:", totalPages);

Syntax

getTotalPagesCount(): number;

Returns​

The total number of pages in the collection list.

getCurrentPageIndex()​

The getCurrentPageIndex() method in the WFCMSList class returns the index of the current page in the collection list.

Example
// Initialize WFCMSList
const list = new WFCMSList(".cms");

// Get the index of the current page
const currentPageIndex = list.getCurrentPageIndex();

console.log("Current page index:", currentPageIndex);

Syntax

getCurrentPageIndex(): number;

Returns​

The index of the current page in the collection list.

goToPageIndex(index)​

The goToPageIndex() method in the WFCMSList class allows you to navigate to a specific page in the collection list.

Example
// Initialize WFCMSList
const list = new WFCMSList(".cms");

// Go to the 3rd page in the collection list
list.goToPageIndex(2);

Syntax

goToPageIndex(index: number): void;

Parameters​

NameTypeDescription
indexnumberThe index of the page to navigate to.

getInitialItemAsTemplate()​

The getInitialItemAsTemplate() method in the WFCMSList class returns a template of the initial item in the collection list.

Example
// Initialize WFCMSList
const list = new WFCMSList(".cms");

// Get the initial item template
const itemTemplate = list.getInitialItemAsTemplate();

Syntax

getInitialItemAsTemplate(): WFComponent<HTMLDivElement>;

Returns​

A template of the initial item in the collection list.

goToNextPageIndex()​

The goToNextPageIndex() method in the WFCMSList class allows you to navigate to the next page in the collection list.

// Initialize WFCMSList
const list = new WFCMSList(".cms");

// Go to the next page in the collection list
list.goToNextPageIndex();

goToPreviousPageIndex()​

The goToPreviousPageIndex() method in the WFCMSList class allows you to navigate to the previous page in the collection list.

// Initialize WFCMSList
const list = new WFCMSList(".cms");

// Go to the previous page in the collection list
list.goToPreviousPageIndex();

setNumberOfItemsPerPage()​

The setNumberOfItemsPerPage() method in the WFCMSList class allows you to set the number of items per page in the collection list.

// Initialize WFCMSList
const list = new WFCMSList(".cms");

// Set the number of items per page to 10
list.setNumberOfItemsPerPage(10);

Syntax

setNumberOfItemsPerPage(numberOfItemsPerPage: number, pageIndex?: number): void;

Parameters​

NameTypeDescription
numberOfItemsPerPagenumberThe number of items to display per page.
pageIndexnumber(Optional) The index of the page to navigate to after setting the number of items per page. If not provided, the current page remains unchanged.

itemRenderer(cb)​

The itemRenderer() method in the WFCMSList class allows you to specify a custom rendering function for each item in the collection list.

// Initialize WFCMSList
const list = new WFCMSList(".cms");

// Define a custom item renderer function
list.itemRenderer(({ item, index, allItems }) => {
  // Customize the rendering of each item
  const numberText = item.getChildAsComponent(".number-index");
  numberText.setTextContent(`#${index + 1}`);
  return item;
});

Syntax

itemRenderer(cb: (data: { item: WFComponent; index: number; allItems: WFComponent[]; }) => WFComponent): void;

Parameters​

NameTypeDescription
cb(data: { item: WFComponent; index: number; allItems: WFComponent[]; }) => WFComponentThe custom rendering function for each item in the collection list.

setFilterSortConfig(config)​

The setFilterSortConfig() method in the WFCMSList class allows you to set filter and sort configurations for the collection list.

// Initialize WFCMSList
const list = new WFCMSList(".cms");

/**
 * <div class="cms-item" data-category="featured" data-date="June, 08, 2023">
 * ...
 * </div> 
 */

// Define filter and sort configurations
list.setFilterSortConfig({
  // Define a filter function
  filter: (item, datasets) => {
    // Implement your filter logic
    return datasets.category === "featured";
  },
  // Define a sort function
  sort: (itemA, itemB) => {
    // Implement your sort logic
    return itemA.datasets.date.localeCompare(itemB.datasets.date);
  },
});

Syntax

setFilterSortConfig(config: {
  filter?: (item: WFComponent<HTMLElement>, datasets: { [key: string]: string; }) => boolean;
  sort?: (itemA: { item: WFComponent<HTMLElement>; datasets: { [key: string]: string; }; }, itemB: { item: WFComponent<HTMLElement>; datasets: { [key: string]: string; }; }) => number;
}): void;

Parameters​

NameTypeDescription
config{ filter?: (item: WFComponent<HTMLElement>, datasets: { [key: string]: string; }) => boolean; sort?: (itemA: { item: WFComponent<HTMLElement>; datasets: { [key: string]: string; }; }, itemB: { item: WFComponent<HTMLElement>; datasets: { [key: string]: string; }; }) => number; }The filter and sort configurations for the collection list.
Filter Configuration​
NameTypeDescription
filter(item: WFComponent<HTMLElement>, datasets: { [key: string]: string; }) => booleanA function to filter items in the collection.
Sort Configuration​
NameTypeDescription
sort(itemA: { item: WFComponent<HTMLElement>; datasets: { [key: string]: string; }; }, itemB: { item: WFComponent<HTMLElement>; datasets: { [key: string]: string; }; }) => numberA function to sort items in the collection.

getFilterSortConfig()​

The getFilterSortConfig() method in the WFCMSList class retrieves the current filter and sort configurations for the collection list.

// Initialize WFCMSList
const list = new WFCMSList(".cms");

// Get the current filter and sort configurations
const config = list.getFilterSortConfig();

console.log(config);

Syntax

getFilterSortConfig(): {
  filter?: (item: WFComponent<HTMLElement>, datasets: { [key: string]: string; }) => boolean;
  sort?: (itemA: { item: WFComponent<HTMLElement>; datasets: { [key: string]: string; }; }, itemB: { item: WFComponent<HTMLElement>; datasets: { [key: string]: string; }; }) => number;
};

Return Value​

NameTypeDescription
filter(item: WFComponent<HTMLElement>, datasets: { [key: string]: string; }) => booleanThe filter function for the collection list.
sort(itemA: { item: WFComponent<HTMLElement>; datasets: { [key: string]: string; }; }, itemB: { item: WFComponent<HTMLElement>; datasets: { [key: string]: string; }; }) => numberThe sort function for the collection list.