Collection Widget Items API

The Collection Widget Items API provides you with the items data for a collection widget.

You can also use the View API if you want to display the template output for a collection widget. Or you can use the Data API if you also need data about the collection widget.

Learn more about APIs.

Return value

The return value from the Items API is an array of collection items for the specified collection widget.

Minimum Tag

Because the return value is an array of data, instead of the output from a template, you will want to set the returned value to a variable.

{% set items = _api.widgets.collection.items('collection-key') %}

The collection key is passed through the items API method.

Alternately you can use the key parameter to set the collection key.

{% set items = _api.widgets.collection.items.key('collection-key') %}

Example Tags

Limit the number of items returned to 3 items

{% set items = _api.widgets.collection.items('collection-key').limit(3) %}

Get items in a random order

{% set items = _api.widgets.collection.items('collection-key').random() %}

Limit the items returned to those that match an attribute value

{% set items = _api.widgets.collection.items('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.

{% set items = _api.widgets.collection.items('collection-key').attr({'firstName': 'Bob'}) %}

API Tag Parameters

Parameter Description
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(',')})
key

The collection widget key. You must either use the "key" parameter or you must pass the collection key in the "items" parameter.

Both are valid:

{% set items = _api.widgets.collection.items('collection-key') %}

The collection key is passed through the items API method.

Alternately you can use the key parameter to set the collection key.

{% set items = _api.widgets.collection.items.key('collection-key') %}

limit
l
The number of results to return. Defaults to return all matching results (no limit).

You can alternately use the short form "l" instead of "limit"

Type: Integer

Examples:
limit(5)


l(5)
match Whether or not to match all parameter conditions or any of the parameter conditions. Defaults to 'all'.

For example, if you passed multiple attribute values with the "attr" parameter then this would decide whether or not to only return items that match all of the attr values, or ones that match at least one of the attr values.

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')
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')