Collection Widget View API

The Collection Widget View API is how you would display 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.

The View API will retrieve the Collection data, including it's collection items, and display it either with the specified template or the default template for that Collection Widget.

You can also use the Items API if you want to get just the items data. Or you can use the Data API if you also need data about the collection widget.

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.

From the collection details tab

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

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.

Learn more about APIs.

Minimum Tag

Example Tags

Limit the number of items returned to 3 items

Get items in a random order

Get 5 items in a random order

{{ _api.widgets.collection.get.key('collection-key').random().limit(5) }}

Limit the items returned to those that match an attribute value

{{ _api.widgets.collection.get.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.get.key('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(',')}) If you're trying to get app items by their ids you can also sort them in the order that the ids are passed. attr({'id': myIds\|join(',')}).sort({'id': 'asc'}) Type: Hash Examples: attr('layoutKey', 'value') Get items that match a list of item ids attr({'id': myIds\|join(',')})
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') If you're trying to get app items by their ids you can also sort them in the order that the ids are passed. attr({'id': myIds\|join(',')}).sort({'id': 'asc'}) 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')
template	The template key of the collection widget template to use. If this is not passed then the default template for the collection widget will be used. You an alternately use the short form "t" instead of "template" Type: String Examples: template('template-key') t('template-key') Type: String Example: template('template-key')
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')