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 Page and Its Inputs 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 for this URL. The editor requires a browser title for every entity that has a 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.

Example Fetch entities with a URL and list type plus linked title{% entities %} returns a cross-type entities list; has_url and shared list options narrow results, and each item exposes object_type plus shared entity fields.

{%- entities var pages = has_url:true limit:50 sort_by:"url" sort_direction:"asc" -%}
<ul>
{%- for page in pages -%}
	<li>{{ page.object_type }}: {{ page.linked_title }}</li>
{%- endfor -%}
</ul>

{% entities %} is the list method that spans every entity type. Options such as has_url, tag, folder, author, and global_type_id combine with the shared list options (limit, sort_by, start, page). The result is an entities object; iterate it directly and use object_type to tell which concrete type each item is.

{% entities %}

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

Parameters

output_to_template optionalflag

Include this flag to write the entities list's output into the page here. That output is a built-in default for most types and may change at any time, so see the output property of the entities object before relying on it. The flag may come before or after the variable name. With no variable named, the output is written whether or not the flag is present; with one, the flag saves the list and writes its output too.

var, set, or assign optionalkeyword

Chooses the scope that holds the variable. var, the default, stores it in the current scope. set and assign can store it in outer scopes; Variable Scopes compares the three and when each fits.

variable_name optionalvariable

The variable that receives the entities list. It may also be written as a reference, &name, which reads the variable's name from another variable (see Methods Overview). Leave it out to write the list to the template instead.

arguments requiredcollection

Key:value pairs. May use the variable arguments syntax. Written after a required =. The name:value pairs choose which entities to fetch and how to narrow, order and page them. Nothing is fetched unless the call gives an argument other than prepend, append, unique, exclude_prepended, exclude_appended, max_size and cache_random; without one, the list holds only the prepended and appended entities.

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.

has_url optionalboolean

If true, only return entities that have a URL. If false, only return entities that do NOT have a URL.

template optionalobject

Only return entities with one of these templates. May be a single template, a list of templates, or the name or guid of a template to filter the results by. A template name is its path from the root, with or without the leading /; unlike {% template %}, a list method does not accept a relative path.

include_in_search optionalboolean

True or false to only return entities whose include_in_search property matches the provided value.

domain_name optionalobject

Only return entities from the given domain.

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; a value that is not a number also gives 10. The largest limit is 1000, and a limit of 0 or less, or above 1000, returns up to 1000 entities. 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. An unrecognized value is ignored without an error and the default order is used. Some methods accept more values than the built-ins listed here; see each method. 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. sort_direction applies: descending, the default, puts the best match first.
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. Defaults to desc; any value other than asc sorts descending.

cache_random optionalboolean

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

Fetches a list of {{ entities }}.

{%- entities var pages = has_url:true limit:50 sort_by:"url" sort_direction:"asc" -%}
<ul>
{%- for page in pages -%}
	<li>{{ page.object_type }}: {{ page.linked_title }}</li>
{%- endfor -%}
</ul>

Entity

Entity

{{ entity }}

{{ entities }}

{% entities %}

Related