Collection

The collection component displays a collection of entries on the page. The collection component can be used on any page, layout or partial.

# Available Properties

The following properties are supported by the component.

# Basic Usage

The following adds a collection of Blog\Post entries to the page. The collection is accessed in Twig by looping the default collection variable.

[collection]
handle = "Blog\Post"

{% for post in collection %}
    <h1>{{ post.title }}</h1>
{% endfor %}

When multiple collections are used on the same page, the component can be assigned a name posts using the component alias and this is the variable name that becomes available to the page. The following collection is accessed using the posts variable instead.

[collection posts]
handle = "Blog\Post"

{% for post in posts %}
    <h1>{{ post.title }}</h1>
{% endfor %}

Use the is empty or is not empty expression to check if a collection has at least one record available to display.

{% if posts is not empty %}
    {# ... #}
{% endif %}

# Performing Queries

When accessing the component variable using a method it will switch to a database model query. For example, to only show entries that have a field color with the value blue use the where query method. Using the {% set %} Twig tag will assign the result to a new variable.

{% set bluePosts = posts.where('color', 'blue').get() %}

To show only posts that have a related author, you can use the whereRelation query method. To complete the query, proceed with the get() method. The following lists posts that are assigned to the author with a slug set to bella-vista.

{% set authorPosts = posts.whereRelation('author', 'slug', 'bella-vista').get() %}

# Accessing the Entry Type

To filter records by their entry type, perform a where() query using the content_group attribute. The following will list posts that use the entry type code featured_post.

{% set featuredPosts = posts.where('content_group', 'featured_post').get() %}

# Paginating Records

You could also apply pagination to the collection with the paginate() method instead. The following will paginate the posts at 10 per page and displays the paginated navigation.

{% set authorPosts = posts.whereRelation(...).paginate(10) %}

{{ pager(authorPosts) }}

# Searching Records

To search records, use the searchWhere() method to perform a search query on a column's value. The following will search for records the supplied term and columns using a case insensitive query.

{% set foundPages = pages.searchWhere(searchTerm, ['title', 'content']).get() %}

You may also use the searchWhereRelation() method to search related records, where the relation name is included in the method for querying the relationship existence.

{% set foundPages = pages.searchWhereRelation(searchTerm, 'author', ['title']).get() %}

# Eager Loading Related Records

In some cases, and for performance reasons, you may wish to eager load related records. Use the load method on the collection, passing the relation name. In the next example, the categories relation will be loaded with every post in the collection.

{% do authorPosts.load('categories') %}

# Counting Records

Let's assume you want to display a list of blog categories and count the number of posts in each category. First, define the inverse relation on the category blueprint as posts.

posts:
    type: entries
    source: Blog\Post
    inverse: categories
    hidden: true

Then, call the withCount function on the collection component, followed by get to return a collection of category records. This will create an attribute on each category called post_count.

{% set categories = collection.withCount('posts').get() %}
{% for category in categories %}
    <h5>{{ category.title }} ({{ category.post_count }} posts)</h5>
{% endfor %}

# See Also