{% datastore_item_collection %}

Syntax

{% datastore_item_collection [[var|set|assign] new_variable_name] [output_to_template] [filter_name:FilterValue [...]] [start:1] [page:1] [limit:25] [sort_by:"date_created"] [sort_direction:"desc"] %}

You MUST include either a variable name to assign the collection to, "output_to_template", or both (if both output_to_template should be the later argument).

If you are assigning the collection to a variable and do not specify one of "var", "set", or "assign", then the "var" behavior will be used - which is to save the result on the current scope. If new_variable_name starts with '&', will attempt to assign the value by reference.

If you are outputting the collection to the template, it will use the default output for datastore_item_collections

Filters

For every filter in the tag, the resulting collection will only contain items that match the filter. Some filters (eg: tag) may be allowed multiple times, in which case the resulting collection will contain items that match any of the values for that filter (eg: {% ... tag:tag1 tag:tag2 tag:tag_collection tag:tag_list %}). You may also include reference variables as filters (eg: {% ... &filtername:filtervalue %}. If you include an invalid filter ({% ... invalid_filter:any %}), or if a reference variable does not evaluate to a valid filter, that filter will simply be ignored.

string filter
Only return datastore items that match the given string filter.
boolean has_url
Filter results to only return datastore items for which has_url exactly matches the specified value.
datastore|datastore_list|datastore_collection|guid|string datastore
Only return datastore items with one of these datastores. You may include this filter multiple times.
template|template_list|template_collection|guid|string template
Only return datastore items with one of these templates. You may include this filter multiple times.
boolean include_in_search
Filter results to only return datastore items for which include_in_search exactly matches the specified value.
guid site_domain_guid
Filter results to only return datastore items for which site_domain_guid exactly matches the specified value.
string ssl_mode
Filter results to only return datastore items for which ssl_mode exactly matches the specified value.
tag|tag_list|tag_collection|guid|string tag
Only return datastore items with one of these tags. You may include this filter multiple times.
author|author_list|author_collection|guid|string tag
Only return datastore items with one of these authors. You may include this filter multiple times.
folder|folder_list|folder_collection|guid|string folder
Only return datastore items with one of these folders. You may include this filter multiple times.
datetime date_created_start
Filter results to return datastore items for which date_created is greater than or equal to date_created_start.
datetime date_created_end
Filter results to return datastore items for which date_created is less than or equal to date_created_end.
string query
Additional conditions to query on. May inclue multiple conditions separated by "AND". Each condition is composed of three parts (separated by spaces).
  1. (required) The datastore item field to query
  2. (optional)The condition that has to be satisfied. If omitted, the condition will match datastore items that have any value at all for the specified field
  3. (optional) The value to check the field against (note: all comparisons are case-insensitive)
The possible conditions are:
  • = or ==: The field must have the exact value specified
  • <> or !=: The field must NOT have the value specified
  • >: The field must have a value greater than the value specified
  • <: The field must have a value less than the value specified
  • >=: The field must have a value greater than or equal to the value specified
  • <=: The field must have a value less than or equal to the value specified
  • CONTAINS or LIKE: The field must contain the value specified

Sorting

By default the results will be sorted by relevance if there is a filter string and date_created (the date the item was first published) desc (newest first) if not. You may customize the order in which results are returned using any of the following options:

  • name
  • title
  • url
  • browser_title
  • relevance (based on which field matches the given filter and where in the field the match is found. When sorting by relevance sort_direction is irrelevant)
  • date_created (Equivalent to the date you first published this item. Unpublishing and republishing the item resets date_created to the current date)
  • random
  • custom (You may specify a custom datastore field to sort by)

sort_direction may either be asc or desc (default).

If sorting by a custom field, the results will be sorted alphabetically. If you need the results to be sorted numerically, specify numeric_sort:true as an additionally filter on the {% datastore_item_collection %} tag.

Developer Overview

Liquid Markup