User Guides

Collections

Collections allow you to use predefined sets of content types to create multiple items with the same structure. They can include any number of content types including other collections.

Nesting collections is a very powerful feature that unlocks an enormous number of possibilities, enabling you to structure your websites content however you would like.


Example Content Configuration

The rest of this page assumes that you have the below content configuration defined. The examples beyond this point also assume that you are interacting with LexasCMS from within a template.

# Collections
collections:
  service:
    fields:
      - { name: "name", type: "text", title: "Service Name" }
      - { name: "description", type: "html", title: "Service Description" }

# Sections
sections:
  Services:
    fields:
      - { name: "heading", type: "text", title: "Page Heading" }
      - { name: "banner", type: "image", widths: [1140], title: "Page Banner" }
      - { name: "copy", type: "html", title: "Page Copy" }
      - { name: "services": type: "collection", definition: "service", title: "Services" }

Retrieving a Collection

Before you can interact with a collection, you need to retrieve the collection you would like to interact with. Collections can be retrieved in multiple ways.

From a Section

This is the way that you will most commonly interact with a collection. The example below shows how you would retrieve a collection from within a content section.

{{ cms.content.section("Services").services }}

By Definition Name

Alternatively, you can also retrieve collections by their definition name. The below example below shows how you would retrieve a collection by its definition name.

Note: Retrieving collections by their definition name will retrieve all of the items within that collection type regardless of their parents. As a result, the collections items may not be returned in the order that they are displayed in from within the admin panel.
{{ cms.content.collection("service") }}

Finding Items

Once you have access to the collection, you can then retrieve all items within that collection using the find() method.

Basic Usage

The following example shows some basic usage of how you would retrieve all of a collections items and display them.

{% set services = cms.content.section("Services").services %}
<ul>
  {% for service in services.find() %}
    <li>{{ service.name.html() }}</li>
  {% endfor %}
</ul>

Default Iterator

By default a collection will act as an iterator of the find() method, which will iterate through every item in the current set.

{% set services = cms.content.section("Services").services %}
<ul>
  {% for service in services %}
    <li>{{ service.name.html() }}</li>
  {% endfor %}
</ul>

Limiting Results

You can also limit the number of items that you retrieve by passing an integer to the first parameter of the find method:

{% set services = cms.content.section("Services").services %}
<ul>
  {% for service in services.find(5) %}
    <li>{{ service.name.html() }}</li>
  {% endfor %}
</ul>

Available Find Methods

Collections have a number of different find methods that you can use to change which items are returned.

The table below outlines a list of some of the available methods, for a more detailed overview of the available methods and their parameters, see the API reference.

Function Description
find($limit, $offset) Retrieve all of the collection items
findByField($field, $value, $limit, $offset) Retrieve all collections items matching the specified fields value
findOneByField($field, $value) Retrieve a single collection item that matches the specified fields value
findByUuid($uuid) Retrieve a collection item by its UUID
findById($id) Retrieve a collection item by its ID
findBySlug($slug) Retrieve a collection item by its slug

As an example, if you only wanted to retrieve the service with the name 'Some Service', you would do as follows:

{% set services = cms.content.section("Services").services %}
{% set service = services.findOneByField("name", "Some Service") %}

{{ service.name.html() }}

Paginating a Collection

Collections come with built in support for pagination. Using the paginate() method of a collection, you can tell the collection how many items you would like to display per page and which page you would like to display.

For example, the following code shows how you would display the first page of services that had been paginated to five items per page.

{% set services = cms.content.section("Services").services.paginate(5) %}
<ul>
  {% for service in services.page(1) %}
    <li>{{ service.name.html() }}</li>
  {% endfor %}
</ul>

Querying Items

Querying provides you with the ability to write custom SQL queries allowing you to achieve much more complex results. You can query a collection using the query() method. This method will return a query object which you can use to setup a custom query, see advanced queries for further information.


Further Reading

This section only covers the basic functionality available on collections, for a more detailed overview of all of the available methods, please see the API reference