Collection Widget Data API
The Collection Widget Data API gets the data for a collection widget and it's items.
The collection items are retrieved according to the collection widget settings or by any parameters if they are set.
You can also use the View API if you want to display the template output for a collection widget. Or you can use the Items API if you only want the items data.
Return value
The return value from the Data API is an array of data for the collection widget, including the collection items.
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 data = _api.widgets.collection.data('collection-key') %}
The collection key is passed through the data API method.
Alternately you can use the key parameter to set the collection key.
{% set data = _api.widgets.collection.data.key('collection-key') %}
Example Tags
Limit the number of items returned to 3 items
{% set data = _api.widgets.collection.data('collection-key').limit(3) %}
Get items in a random order
{% set data = _api.widgets.collection.data('collection-key').random() %}
Limit the items returned to those that match an attribute value
{% set data = _api.widgets.collection.data('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 data = _api.widgets.collection.data('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 data = _api.widgets.collection.data('collection-key') %} The collection key is passed through the data API method. Alternately you can use the key parameter to set the collection key. {% set data = _api.widgets.collection.data.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') |