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.

dmAPI.loadCollectionsAPI().then(api => {
    // do something with API
})

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.

api.data("collectionName").get().then(data => {...})

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.

dmAPI.loadCollectionsAPI().then(api => {
    api.data("collectionName")
        .where("<field>", "<operator>", "<value>")
        .orderBy("<field>","<direction>")
    .select('property1', 'property2', ...)
        .pageSize(20)
        .pageNumber(2)
        .get()
        .then(json => console.log(json))
})

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 in the collection.
direction	String	No	Possible values are “asc” and “desc”. Defaults to “asc”.

Searching collection

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

dmAPI.loadCollectionsAPI().then(api => {
    api.data("collectionName")
    .search("<search_query>")
        .get()
        .then(json => console.log(json))
})

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.