Calendar Category Filter API

The Calendar Category Filter API allows you to pull in Calendar categories into different parts of the website.

Learn more about APIs.

By default sub-categories and events will not be included. This is done to avoid extra overhead in cases where those data values are not needed.

To include sub-categories set the getSubCategories parameter to yes.

To include events set the getEvents to yes.

Minimum Tag

{{ _api.calendar.categoryFilter.template('template-key') }}

Example Tags

Get 5 categories and get any events assigned to them

{{ _api.calendar.categoryFilter.template('template-key').limit(5).getEvents('yes') }}

Get categories, category events and sub-categories

{{ _api.calendar.categoryFilter.template('template-key').getEvents('yes').getSubCategories('yes') }}

Get information for a specific category

This will get information for a category with an id of 3.

{{ _api.calendar.categoryFilter.template('template-key').attr('id', 3).getEvents('yes') }}

Get 10 categories in random display order

{{ _api.calendar.categoryFilter.template('template-key').limit(10).random() }}

Get 10 categories ordered by their category name

Typically categories are ordered according to the display order settings set in the app. You can override that setting. There are two ways to do sorting. One is to use a combination of the sortKey and sortDirection parameters. The other is to use the sort parameter.

{{ _api.calendar.categoryFilter.template('template-key').limit(10).sortKey('categoryName').sortDirection('asc') }}

{{ _api.calendar.categoryFilter.template('template-key').limit(10).sort('categoryName', 'asc') }}

Tag Parameters

ParameterDescription
allInstances Whether or not to query accross all instances of this app.

Type: String

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

Example:
allInstances('yes')
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(',')})
getEvents Whether or not to get any events for each category.

Type: String

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

Example:.getEvents('yes')
getSubCategories Whether or not to get any subcategories for each category.

Type: String

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

Example:
getSubCategories('yes')
keys Comma separated list of layout keys that will be used to only return that data.

Type: String

Example:
keys('layoutKey1, layoutKey2')
instanceKey The key for the instance to get results in. If nothing is passed then the current instance will be used if this is called within the same app.

Type: String

Example:
instanceKey('appInstanceKey')
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')
parentId The numeric id of a single parent category or a comma separate separated numeric ids of parent categories to get subcategories for. This will limit the categories returned to only the specified subcategories.

If no value is passed then parentId will default to "0", which means that only top level categories will be returned (unless getSubCategories('yes') is also passed).

Type: String

Examples:
One parent id
parentId(5)


Multiple parent ids
parentId(7, 5, 4) or parentId('7, 5, 4')
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()
randomSelect Whether or not the results will be randomly selected from the database. This is done independantly of the sorting. This makes it possible to randomly select some data and then sort that random data by a specific column.

Type: String

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

Example:
randomSelect('yes')
responseFormat Sets how the API response will be returned.

Type: String

Accepted Values:
template - The default value. This tells the system to use a Content Template to build the API response.
ui - This is used if the data from the API call will used in the administration as a UI form component. A Content Template will be used to structure the data correctly to build the form component HTML.

Example:
responseFormat('ui')
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')
startAt Where to start in the results. Defaults to 0.

Type: Integer

Example:
startAt(2)
template Required if responseFormat is not 'data'. The template key of the template to use.

If this is not passed when it's required then nothing will be returned. In some cases by not passing this parameter you will get just the raw data back.

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')
useParentId Whether or not to pay attention to the "parentId" parameter.

By default the "parentId" parameter is "0" if no value is passed, which means that the API call targets top level categories in it's search. However, if you need to target subcategories then you would want to set useParentId to "no".

The default value for "useParentId" is "yes".

Type: String

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

Example:
useParentId('no')