Collections JS API

The Collections API returns filtered, sorted, searched and paginated data from your collections using Javascript. This article will walk you through how to use the Collections API and all of its options.

Usage

In the interest of page speed, the Collections API is not included in the page until it is initialized using Duda's JavaScript API.

var collection = await dmAPI.loadCollectionsAPI()

Once the Collections API is initialized, it can be used to fetch, filter, sort, search and paginate collection data via chaining additional methods to the data method. At a minimum, you must pass the collection name to the data method, followed by calling the get method. This configuration will return a single page of results from the specified collection.

await collection.data("collectionName").get()

Each call to the get method makes an asynchronous network request. This method returns a promise, which will be resolved with data matching the query.

Options

The Collection API supports optional method chaining to add specific filtering, sorting, and pagination when querying data. Below is an example using all optional methods.

await collection.data("collectionName")
		.where("<field>", "<operator>", "<value>")
		.orderBy("<field>","<direction>")
		.pageSize(20)
		.pageNumber(2)
		.get()

Paginating Items

Pagination is handled with two methods:

Method Name	Type	Required	Notes
pageSize	Int	No	Defaults to 50 items per page. Max size is 100 items per page.
pageNumber	Int	No	Defaults to 0.

Filtering Items

Use the .where() method to filter the results using a provided comparison. Where takes three arguments:

Argument	Type	Required	Description
field	String	Yes	The field in the collection.
operator	String	Yes	Available operators: EQ, IN, NE, NIN, GT, GTE, LT, LTE, BTWN.
value	String \| Array \| number	Yes	A value to compare.

Filter Operators

The .where() method can utilize several different operators to filter fields based on their value. Certain operators can only be applied to fields of a specific data type.

Value	Field Data Type	Description
EQ	string, number	Checks if the field is equal to the supplied value.
IN	string, number	Checks if the field contains a value within the supplied array.
NE	string, number	Checks if the field is not equal to the supplied value.
NIN	string, number	Checks if the field is not a value within the supplied array.
GT	number	Checks if the field is greater than the supplied value.
GTE	number	Checks if the field is greater than or equal to the supplied value.
LT	number	Checks if the field is less than the supplied value.
LTE	number	Checks if the field is less than or equal to the supplied value.
BTWN	number	Combination of LTE and GTE for convenience. Check if the field is equal or between two values. Expects a list of exactly two values.

Sorting Items

Use the .orderBy() method to sort the query results. Order by takes two arguments:

Argument	Type	Required	Notes
field	String	Yes	The field name in the collection.
direction	String	No	Possible values are “asc” and “desc”.

📘
Supported field types
You can sort by all collection field types

Searching collection

Use the .search() method to search a collection.

await collection.data("collectionName").search("<search_query>").get()

You can search for all string fields in a collection.
Search is case insensitive.
When searching in a collection, we check whether the search query is contained in any of the searchable fields in the collection.

Returning Specific Item Properties

Use the .select() method to only return the specific properties you need for the site or widget to function. This can improve performance for collections with a large number of properties per item. Provide each property name as a separate argument to the function.

Code Examples

Let's assume we're calling the API with a collection called Team Collection. The response for that collection would be as follows:

[
    {
        "data": {
            "second_image": "https://static-cdn.multiscreensite.com/dynamicpages/defaultCollection/Team_member/second_image_jane_smith.jpg",
            "About title": "I advise companies and NGOs in initiatives and campaigns",
            "Number": "(670)-390-7270",
            "Related Projects": [
                "Design",
                "Performance",
                "New Features"
            ],
            "Join Date": "2023-09-19T00:00",
            "main_image": "https://static-cdn.multiscreensite.com/dynamicpages/defaultCollection/Team_member/main_image_jane_smith.jpg.jpg",
            "About description": "This is the text area for a paragraph describing this service. You may want to give examples of the service and who may be able to benefit from it.",
            "Work experience": "<b>2020-2021</b><br/>\nAdvisor, South Company<br/>\nIn this position, I led a team of more than 40 professional and volunteer staff members, from various company departments.<br/><br/>\n<b>2019-2020</b><br/>\nConsultant, North Company<br/>\nIn this position, I led a team of more than 40 professional and volunteer staff members, from various company departments.<br/><br/>\n<b>2018-2019</b><br/>\nProject manager, East Company<br/>\nIn this position, I led a team of more than 40 professional and volunteer staff members, from various company departments.",
            "Title": "Product Manager",
            "email": "[email protected]",
            "Name": "Jane Smith"
        },
        "page_item_url": "1_jane_smith"
    },
    {
        "data": {
            "second_image": "https://static-cdn.multiscreensite.com/dynamicpages/defaultCollection/Team_member/second_image_john_brown.jpg",
            "About title": "I advise companies and NGOs in initiatives and campaigns",
            "Number": "(671)-390-7270",
            "Related Projects": [
                "New Features",
                "Performance",
                "Tech Debt"
            ],
            "Join Date": "2023-08-03T00:00",
            "main_image": "https://static-cdn.multiscreensite.com/dynamicpages/defaultCollection/Team_member/main_image_john_brown.jpg",
            "About description": "This is the text area for a paragraph describing this service. You may want to give examples of the service and who may be able to benefit from it.",
            "Work experience": "<b>2019-2020</b><br/>\nAdvisor, South Company<br/>\nIn this position, I led a team of more than 40 professional and volunteer staff members, from various company departments.<br/><br/>\n<b>2019-2020</b><br/>\nConsultant, North Company<br/>\nIn this position, I led a team of more than 40 professional and volunteer staff members, from various company departments.<br/><br/>\n<b>2018-2019</b><br/>\nProject manager, East Company<br/>\nIn this position, I led a team of more than 40 professional and volunteer staff members, from various company departments.",
            "Title": "Developer",
            "email": "[email protected]",
            "Name": "John Brown"
        },
        "page_item_url": "2_john_brown"
    },
    {
        "data": {
            "second_image": "https://static-cdn.multiscreensite.com/dynamicpages/defaultCollection/Team_member/second_image_helen_jameson.jpg",
            "About title": "I advise companies and NGOs in initiatives and campaigns",
            "Number": "(672)-390-7270",
            "Related Projects": [
                "Design",
                "New Features"
            ],
            "Join Date": "2023-09-30T00:00",
            "main_image": "https://static-cdn.multiscreensite.com/dynamicpages/defaultCollection/Team_member/main_image_helen_jameson.jpg",
            "About description": "This is the text area for a paragraph describing this service. You may want to give examples of the service and who may be able to benefit from it.",
            "Work experience": "<b>2018-2019</b><br/>\nAdvisor, South Company<br/>\nIn this position, I led a team of more than 40 professional and volunteer staff members, from various company departments.<br/><br/>\n<b>2019-2020</b><br/>\nConsultant, North Company<br/>\nIn this position, I led a team of more than 40 professional and volunteer staff members, from various company departments.<br/><br/>\n<b>2018-2019</b><br/>\nProject manager, East Company<br/>\nIn this position, I led a team of more than 40 professional and volunteer staff members, from various company departments.",
            "Title": "Designer",
            "email": "[email protected]",
            "Name": "Helen Jameson"
        },
        "page_item_url": "3_helen_jameson"
    },
    {
        "data": {
            "second_image": "https://static-cdn.multiscreensite.com/dynamicpages/defaultCollection/Team_member/second_image_tom_philips.jpg",
            "About title": "I advise companies and NGOs in initiatives and campaigns",
            "Number": "(673)-390-7270",
            "Related Projects": [
                "Tech Debt",
                "New Features"
            ],
            "Join Date": "2023-09-17T00:00",
            "main_image": "https://static-cdn.multiscreensite.com/dynamicpages/defaultCollection/Team_member/main_image_tom_philips.jpg",
            "About description": "This is the text area for a paragraph describing this service. You may want to give examples of the service and who may be able to benefit from it.",
            "Work experience": "<b>2022-2023</b><br/>\nAdvisor, South Company<br/>\nIn this position, I led a team of more than 40 professional and volunteer staff members, from various company departments.<br/><br/>\n<b>2019-2020</b><br/>\nConsultant, North Company<br/>\nIn this position, I led a team of more than 40 professional and volunteer staff members, from various company departments.<br/><br/>\n<b>2018-2019</b><br/>\nProject manager, East Company<br/>\nIn this position, I led a team of more than 40 professional and volunteer staff members, from various company departments.",
            "Title": "QA Engineer",
            "email": "[email protected]",
            "Name": "Tom Phillips"
        },
        "page_item_url": "4_tom_phillips"
    }
]

Getting a specific row

await collection.data("Team Collection").where("Name", "EQ", "John Brown").get()

Getting all rows that match a multi-select field

await collection.data("Team Collection").where("Related Projects", "IN", ["Design", "Performance"]).get()

Sorting by Date

await collection.data("Team Collection").sort("Join Date", "asc").get()