Entity

What an entity is, shared properties on every entity, and the entities query API.

An entity is a CMS content record: an article, blog post, page, form, folder, or other type that can have a URL. {{ entity }} is the shared shape for that record, not a separate runtime type. The value is one of the concrete types under Content. Every entity shares a common set of properties (title, guid, url, full_url, canonical_url, object_type, is_valid, and others in the tables below). Use object_type to tell which implementing type you have. Type-specific properties depend on that concrete type.

{{ entity }} is also the reserved root-scope name for the current page’s primary record. It is always set. How to output it on a page versus in a partial is covered in The Entity Object and Entity-Driven Pages under Building Sites.

{{ entities }} and {% entities %} fetch a list of entities (prepended, fetched, appended, items, size, and pagination). Working with Lists covers the shared list model. Creating and Using Collections covers fetch, filter, loop, and paginate recipes. Site search is the {% search %} method under List methods.

{{ entity }} is the shared shape for a CMS content record. It is not a separate runtime type: the value is one of the concrete entity objects (article, blog_post, form, folder, and the rest). Every entity exposes shared properties such as title, guid, url, full_url, and canonical_url. Use object_type to tell which implementing type you have. Type-specific properties depend on that concrete type.

Properties

Properties of {{ entity }} objects
Name	Type	Description
`object_type`	string	Will always be varies
`is_valid`	boolean	True if this references a published entity
`guid`	string	The unique identifier for this entity
`value`	string	Contains the same value as guid
`name`	{{ text }}	The name of the entity
`title`	{{ text }}	The title of the entity
`linked_title`	string	A link to the entity if it has a URL, or the escaped title if not
`has_url`	boolean	True if the entity has a URL
`include_in_search`	boolean	Whether or not this entity should be returned in on-site search results
`domain_name`	{{ text }}	The domain name used by the URL for this entity
`url`	{{ text }}	The portion of the URL for this entity following the domain name
`full_url`	string	The full URL for this entity including the scheme, domain name, and path
`visited`	boolean	Whether or not the user has visited this URL previously in their current session. Note that this will always be false if the user has not allowed session permission (see the Permissions and Personalization documentation). Using this property prevents the page from being fast-cached
`template_guid`	string	The unique identifier for the template that would be used to respond to this URL
`template`	{{ template }}	The template that would be used to respond to this URL
`canonical_url`	{{ url }}	The canonical URL if this is not the original source of content for this URL
`browser_title`	{{ text }}	The browser title to use for this URL
`meta_description`	{{ textarea }}	The meta description for this URL
`meta_robots`	{{ text }}	The meta robots for this URL
`keywords`	{{ textarea }}	The SEO keywords for this URL
`search_entity_guid`	string	The unique identifier for the entity that search results should be directed to (if this entity does not have a URL)
`search_entity`	{{ entity }}	The entity that search results should be directed to (if this entity does not have a URL)
`folder_guid`	string	The unique identifier for the folder that contains this entity.
`folder`	{{ folder }}	The folder that contains this entity.
`field_id`	string	The identifier for this field
`label`	string	The label for this field
`output`	string	The default output that the entity would produce if it were output directly to the template. The default output may change at any time. Template developers should avoid using this and should handle the output of different entity types themselves
`data`	{{ data }}	Object containing the custom fields on this entity
`*`	string	Specific custom fields may be accessed using {{ entity.fieldid }} or {{entity['field-id']}}

The reserved root-scope name entity is always the current page's primary record. An entity-typed custom field uses this same shared shape: the runtime value is still a concrete entity type. See Entity under Content for shared properties and the entities query API.

Example Check entity or value type with if and object_typeUse if/elsif with object_type or type checks to branch on entity or value type.

{%- if entity.object_type == 'tag' -%}
	I am a tag
{%- elsif entity.object_type == 'author' -%}
	I am an author
{%- elsif entity.object_type == 'folder' -%}
	I am a folder
{%- else -%}
	What am I?
{%- endif -%}

Properties

Properties of {{ entities }} objects
Name	Type	Description
`object_type`	string	Will always be entities
`is_valid`	boolean	Returns true if this contains at least one entity
`prepended`	list	entities that will be listed at the beginning of the items list
`fetched`	list	The primary list of entities to be included in the items list
`appended`	list	entities that will be listed at the end of the items list
`appended_unique`	list	pages that will be listed at the end of the items list, excluding any pages that are already included in either the prepended or fetched lists
`items`	list	The full list of entities in the proper order and uniqueness, including prepended, fetched, and appended entities
`size`	integer	The total number of items in the list of items, including prepended, fetched, and appended entities
`max_size`	integer	If set, the maximum number of entities that will be returned in the items list and the maximum number that will be included when this object is enumerated as a list. When not set, this value will be 0
`unique`	boolean	When true, the items list will not contain any duplicates. Only the first instance of each entity will be included
`limit`	integer	The maximum number of entities that could have been fetched dynamically from the database
`start`	integer	The 1-based index of the first entity that was (or would have been) dynamically fetched from the database
`page`	integer	The 1-based index of the first "page" of entities that could have been fetched dynamically from the database - as determined by the start and limit properties
`total_count`	integer	The total number of entities in the database that matched the provided filter parameters when fetching the list of fetched entities
`total_pages`	integer	The total number of "pages" of results that matched the provided filter parameters when fetching the list of fetched entities - as determined by the total_count and limit properties
`output`	string	The default output that the entities will produce when it is output directly to the template - using the "output_in_list" property of each entity in the items list

Contains a collection of content, including pagination-related information.

{% entities %}

{% entities output_to_template? [[var, set, or assign]? variable]? output_to_template? = arguments %}

Parameters

output_to_template optionalflag

If included the {% entities %} will be output directly to the template.

var, set, or assign optionalkeyword

Optional. Specify either "var", "set" or "assign" to change which scope this {% entities %} is stored on. "var" is the default behavior.

variable optionalvariable

arguments requiredcollection

Key:value pairs. May use the variable arguments syntax.

Options

prepend optionallist

May be a single , a list of entities, or the name or guid of one , to be included at the beginning of the entities list.

append optionallist

May be a single , a list of entities, or the name or guid of one , to be included at the end of the entities list.

exclude optionallist

May be a single , a list of entities, or the name or guid of one that should NOT be included in the fetched results. Has no effect on prepended or appended entities.

exclude_prepended optionalboolean

True to specifically exclude all prepended entities from the fetched results. If "unique:true" is specified this is the default behavior, although you may also specify "exclude_prepended:false" to allow any prepended items to be fetched along with other results anyway.

exclude_appended optionalboolean

True to specifically exclude all appended entities from the fetched results. This is false by default - even if "unique:true" is specified - so that results are returned in the proper order.

unique optionalboolean

True to remove duplicates from each of the resulting lists (prepended, fetched, appended, and items), although there may be duplicates between the prepended, fetched, and appended lists. The "items" list will include objects in the order in which they appear - with prepended items first, then fetched items, then appended items.

max_size optionalinteger

The maximum number of items to be included in the "items" list. If there are any prepended or appended items, this will automatically lower the "limit" to only fetch as many entities as needed. Note that this may also impact both the "page" and "total_pages" values in the resulting entities. In order to use pagination with a list loaded using "max_size" use "start" instead of "page" and "limit".

filter optionalvalue

Only include entities that match the given string filter

global_type_id optionalvalue

May include multiple types. Only include entities of the given types.

tag optionalvalue

May include multiple tags. Only include entities with one of the given tags

author optionalvalue

May include multiple authors. Only include entities with one of the given authors

folder optionalvalue

May include multiple folders. Only include entities with one of the given folders

date_created_start optionalvalue

Only include entities with date_created greater than or equal to date_created_start. Remember that date_created will typically be the date that the entity was first published.

date_created_end optionalvalue

Only include entities with date_created less than or equal to date_created_end. Remember that date_created will typically be the date that the entity was first published.

start optionalinteger

Set the 1-based index of the first to fetch.

page optionalinteger

Used to automatically calculate the first to fetch based on both the "limit" and the 1-based "page" value. Defaults to 1, but is ignored if "start" is set.

limit optionalinteger

The maximum number of entities to fetch. Defaults to 10. Note that if "max_size" is defined, then "limit" may be automatically lowered even if specified separately.

sort_by optionalstring

Specify which property to sort the results by. Has no effect on prepended or appended entities. By default, results will be sorted by relevance if there is a filter string and date_created desc (newest first) if not. Options include:

relevance: only applies when there is a filter string. When sorting by relevance sort_direction is ignored.
date_created: the date each was first published. Unpublishing and republishing one resets date_created to the current date.
random: results will be returned in a random order, which prevents the page from being fast-cached. Setting cache_random:true overrides this behavior and allows the page to be fast-cached anyway.
name
title
url
browser_title

sort_direction optionalstring

asc or desc.

cache_random optionalboolean

True to allow the results to be cached when sort_by is "random".

Fetches a list of {{ entities }}.

Entity

Entity

{{ entity }}

{{ entities }}

{% entities %}

Related