Document Documents API
The Documents API allows you to pull document information into other areas of the website.
By default documents are returned in the display order that are set within the General Settings for the app.
Minimum Tag
{{ _api.document.documents.template('template-key') }}
Example Tags
Get 5 documents in random display order
{{ _api.document.documents.template('template-key').limit(5).random() }}
Get 10 documents in chronological order with the newest document first.
{{ _api.document.documents.template('template-key').sortKey('publishedOnTimestamp').sortDirection('desc').limit(10) }}
Get 10 documents sorted in ascending order (A - Z) by their document titles.
{{ _api.document.documents.template('template-key').sort(documentTitle, 'asc').limit(10) }}
API Tag Parameters
| Parameter | Description |
|---|---|
| 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(',')}) 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(',')}) |
| category |
The numeric id of a single category or a comma separate separated numeric ids of categories to get items for. This will limit the items returned to only the specified categories.
Type: String Examples: Single category category(3) Multiple categories category('3, 4, 5') or category(3, 4, 5) |
| first |
Limits the items returned to the first item. It's the same as using limit(1) Example: first() |
| getCategories |
Whether or not to get the categories that an app item is assigned to. Typically this is set in conjunction with the getAdditionalData parameter. Typically that parameter also needs to be set to "yes", "1" or "true" in order for category data to also be retrieved. Type: Boolean Accepted Values: 'true', 'false', '1', '0', 'yes', 'no' Example: getCategories('yes') |
| getCustomAttributes |
Whether or not to get any custom attributes for an app item. It's helpful to set this to "no" for performance reasons if your API is only using core app item data and not any custom attributes. Type: String Accepted Values: 'true', 'false', '1', '0', 'yes', 'no' Examples: getCustomAttributes('no') getCustomAttributes('yes') |
| getTags
tags |
Whether or not to get tags that an app item is assigned to. This is usually "no" by default. Type: Boolean Accepted Values: 'true', 'false', '1', '0', 'yes', 'no' Example: getTags('yes') |
| id |
Limits the results to one or more app items that match the specified id. This is an alternate option to passing the ids with the "attr" parameter like .attr({id: 3}) You can pass a single app item id, multiple ids separated by a comma, or an array of ids. .id(3) .id(3, 4, 6, 10, 33) .id([3, 4, 6, 10, 33]) Type: String Accepted Values: A single id value, multiple id values separated by a comma, or an array of ids. Examples: id(3) id([3, 5, 7]) |
| instanceKey
i |
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. You can alternately use the short form "i" (lowercase I) instead of "instanceKey" Type: String Examples: instanceKey('app-instance-key') i('app-instance-key') |
| keys |
Comma separated list of layout keys that will be used to only return that data.
Type: String Example: keys('layoutKey1, layoutKey2') |
| 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() |
| 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') |
| slug |
Limit the returned data to one or more URL slugs. You can pass a single URL slug for an item, an array or URL slugs, or a comma separated list of URL slugs. Type: String Examples: slug('my-url-slug') slug('my-url-slug', 'another-url-slug') |
| 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') |
| startAt |
Where to start in the results. Defaults to 0.
Type: Integer Example: startAt(2) |
| tag |
The numeric id of a single tag or a comma separate separated numeric ids of tag to get items for. This will limit the items returned to only the specified tags.
Type: String Examples: tag(3) Multiple tag ids tag('4, 5, 10') or tag(5, 2, 23) |
| template
t |
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. You an alternately use the short form "t" instead of "template" Type: String Examples: template('template-key') t('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') |