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 NameTypeRequiredNotes
pageSizeIntNoDefaults to 50 items per page.

Max size is 100 items per page.
pageNumberIntNoDefaults to 0.

Filtering Items

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

ArgumentTypeRequiredDescription
fieldStringYesThe field in the collection.
operatorStringYesAvailable operators: eq, in, NE, NIN, GT, GTE, LT, LTE, BTWN.
valueString | ArrayYesA 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.

ValueField Data TypeDescription
EQtext, numberChecks if the field is equal to the supplied value.
INtext, numberChecks if the field contains a value within the supplied array.
NEtext, numberChecks if the field is not equal to the supplied value.
GTnumberChecks if the field is greater than the supplied value.
GTEnumberChecks if the field is greater than or equal to the supplied value.
LTnumberChecks if the field is less than the supplied value.
LTEnumberChecks if the field is less than or equal to the supplied value.
BTWNnumberCombination 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:

ArgumentTypeRequiredNotes
fieldStringYesThe field in the collection.
directionStringNoPossible 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.