Collection Widget API

The Collection Widget API is how you would include a collection widget on a page. Because collection widgets do not have pages of their own the only way to include them on a page is to use their API tag. 

Where to get the API tag

You can get the collection API tag from one of three places.

From the main collections page

Go to Widgets -> Collections and copy the whole tag from the "Tag" column.

Collection list API

From the collection details tab

Click on a collection to view it's items and details. Go to the "Collection Details" tab.

Collection Details API

From the API generator

Click on a collection to view it's items and details. Go to the "API" tab. There you can change the options and have an API tag automatically generated for you. 

You would only need to use this tool if you need to alter the default way that the collection works. 

Collection API generator

Learn more about APIs.

Minimum Tag

{{ _api.widgets:collection:view key="COLLECTION_KEY" }}

Example Tags

Limit the number of items returned to 3 items

{{ _api.widgets:collection:view key="COLLECTION_KEY".limit('3') }}

Get items in a random order

{{ _api.widgets:collection:view key="COLLECTION_KEY".random() }}

Get 5 items in a random order

{{ _api.widgets:collection:view key="COLLECTION_KEY".random().limit('5') }}

Limit the items returned to those that match an attribute value

{{ _api.widgets:collection:view key="COLLECTION_KEY".attr[ATTRIBUTE_KEY]('ATTRIBUTE_VALUE') }}

You would replace "ATTRIBUTE_KEY" with the attributes layout key.

You would replace "ATTRIBUTE_VALUE" with the actual value that you want to match.

For example, if your attribute is called "First Name", has a layout key of "firstName" and you only want to returns collection items that have a first name equal to "Bob" then you could use the following API tag.

{{ _api.widgets:collection:view key="COLLECTION_KEY".attr[firstName]('Bob') }}

API Tag Parameters

ParameterDescription
attr List of attribute layout keys and the values that the filter should match.
If multiple values for an attribute need to be matched then you can separate them with a comma.

The first parameter is the attribute layout key.
The subsequent parameters are the value or values to match.

There are a few ways to pass values:

attr('layoutKey', 'value')

attr('layoutKey', 'value', 'value2', 'value3')

attr({'layoutKey': 'value'})

If you're trying to get app items by their ids and the ids are stored in an array then the following is the best way to get them.

attr({'id': myIds|join(',')})

Type: Hash

Examples:
attr('layoutKey', 'value')


Get items that match a list of item ids
attr({'id': myIds|join(',')})
limit The number of results to return. Defaults to return all matching results (no limit).

Type: Integer

Example:
limit(5)
match Whether or not to match all conditions or any of the conditions. Defaults to 'all'.

Type: String

Accepted Values:
'any' or 'all'

Example:
match('any')
random Sets the results to be returned in random order. If sorting is setup that will override this value.

Simply using the parameter turns random ordering on.

By default results are returned in an order based off of the app settings.

Type: String

Example:
random()
sort Sets the layout keys and the direction to sort by. If this is not used then sortDirection and sortKey will be used if they are set.

You can target a value beyond the first level of an array by using the "dot syntax". Example: myDate.timestamp will get the 'timestamp' value within the 'myDate' array.
array('myDate' => array('timestamp' => '1393657200', 'date' => 'March 1, 2014')).

The first parameter is the attribute layout key to sort by.
The second parameter is the direction to sort by.

You can set layout keys to sort by passing the parameter multiple times.
sort('layoutKey', 'asc').sort('anotherKey', 'desc')

Type: String

Accepted Values:
asc - Ascending order (A - Z or 1 - 10)
desc - Descending order (Z - A or 10 - 1)

Examples:
sort('layoutKey', 'asc')


Sort by a value beyond the first level of a multi-dimensional array
sort('myDate.timestamp', 'asc')
sortDirection The direction to sort. Allowed values are "asc" and "desc"

Type: String

Accepted Values:
asc - Ascending order (A - Z or 1 - 10)
desc - Descending order (Z - A or 10 - 1)

Example:
sortDirection('desc')
sortKey A single layout key to sort on. If you need to sort on multiple layout keys use the 'sort' parameter instead.

You can target a value beyond the first level of an array by using the "dot syntax". Example: myDate.timestamp will get the 'timestamp' value within the 'myDate' array.
array('myDate' => array('timestamp' => '1393657200', 'date' => 'March 1, 2014')).

Type: String

Examples:
sortKey('layoutKey')


Sort by a value beyond the first level of a multi-dimensional array
sortKey('myDate.timestamp')
templateId The id of the collection template to use. If this is not passed then the default collection template is used.

Type: Integer

Example:
templateId('3')
unique Specifies whether or not the result should have unique values. This is really only useful if one layout key is returned for each item.

Type: String

Accepted Values:
'true', 'false', '1', '0', 'yes', 'no'

Example:
unique('yes')