Collections API

The Collections API returns filtered, sorted, 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, 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.

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

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

text, number

Checks if the field is equal to the supplied value.

IN

text, number

Checks if the field contains a value within the supplied array.

NE

text, number

Checks if the field is not equal to the supplied value.

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

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.


Did this page help you?