Template Data

This guide explains how to create and use your CMS content withing Elements using Twig, a powerful and user-friendly template language.

The Elements CMS gives you full control over how your content is displayed by supporting the Twig templating language; a fast, secure, and flexible engine widely used in modern content systems.

Twig is a template engine that lets you create dynamic, reusable templates for your website content. Think of it as a way to create a "skeleton" for your content that automatically fills in the details from your CMS items.

Using CMS Data in Elements Components

You can access your CMS data in any Elements component, as long as that component is placed inside a Collection or Item component. This allows you to create dynamic, data-driven layouts without writing custom templates.

Accessing Your Content Data

Basic Properties

You can access any property from your content files using the {{item.PROPERTY_NAME}} syntax, for example:

{{item.title}} - The title of your content
{{item.body}} - The main content/body text
{{item.date}} - The publication date
{{item.tags}} - Any tags you've assigned
{{item.excerpt}} - A short summary or excerpt

Custom Properties

If you've added custom properties in your content's frontmatter (the section at the top of your markdown files), you can access them the same way:

---
title: My Blog Post
author: John Doe
category: Technology
featured: true
custom_field: Some value
---

In your template, you can use:

{{item.category}}
{{item.featured}}
{{item.custom_field}}

Nested Properties

Some properties contain multiple pieces of information. You can access these using dot notation:

{{item.image.url}} - Image URL
{{item.image.alt}} - Image alt text
{{item.image.caption}} - Image caption

The system can automatically connect related data between different content folders. This is especially useful for tags and authors.

How It Works

If you have a folder structure like this:

content/
├── posts/
│   ├── my-first-post.md
│   ├── my-second-post.md
│   └── my-third-post.md
├── tags/
│   ├── technology.md
│   ├── design.md
│   └── business.md
└── authors/
    ├── john-doe.md
    ├── jane-smith.md
    └── bob-wilson.md

When a post references tags or an author, the system automatically connects to the corresponding tag and author files.

Example Content Structure

Post file (posts/my-first-post.md):

---
title: My First Blog Post
author: john-doe
tags: [technology, design]
date: 2024-01-15
---

Author file (authors/john-doe.md):

---
name: John Doe
email: [email protected]
bio: A passionate web developer with 10 years of experience
avatar: /images/john-doe.jpg
website: https://johndoe.com
---

Tag file (tags/technology.md):

---
name: Technology
description: Posts about web development, programming, and tech trends
---

Accessing Related Data

Once the relationships are established, you can access the full data from the related files:

Author Data:

{{item.author.name}} - Full name from author file
{{item.author.email}} - Email from author file
{{item.author.bio}} - Biography from author file
{{item.author.avatar}} - Profile picture from author file
{{item.author.website}} - Website from author file

Tag Data:

{{item.tags[0].name}} - First tag's full name
{{item.tags[0].description}} - First tag's description

Displaying Author Information:

{% if item.author %}
<div class="author-info">
    {% if item.author.avatar %}
    <img
        src="{{item.author.avatar}}"
        alt="{{item.author.name}}"
        class="author-avatar"
    />
    {% endif %}
    <div class="author-details">
        <h3>By {{item.author.name}}</h3>
        {% if item.author.bio %}
        <p>{{item.author.bio}}</p>
        {% endif %} {% if item.author.website %}
        <a href="{{item.author.website}}" target="_blank">Visit Website</a>
        {% endif %}
    </div>
</div>
{% endif %}

Displaying Tags with Full Data:

{% if item.tags %}
<div class="tags">
    {% for tag in item.tags %}
    <span class="tag">
        {{tag.name}} {% if tag.description %}
        <span class="tag-description">{{tag.description}}</span>
        {% endif %}
    </span>
    {% endfor %}
</div>
{% endif %}

Working with URLs

Item URLs

Each piece of content automatically gets a URL. You can access it using:

{{item.url}} - The full URL to this content item
{{item.slug}} - The URL-friendly version of the title

Pretty URLs

Elements CMS system supports "pretty URLs" which are more readable and SEO-friendly. Instead of URLs like:

yoursite.com/blog/post?id=123

You get clean URLs like:

yoursite.com/blog/my-awesome-blog-post

The system automatically generates these pretty URLs based on your component settings, and requires an htaccess file. Read more about setting up Pretty URLs.

Conditional Content

You can show or hide content based on certain conditions:

{% if item.featured %}
<div class="featured-badge">Featured Post</div>
{% endif %} {% if item.image %}
<img src="{{item.image}}" alt="{{item.title}}" />
{% endif %} {% if item.tags %}
<div class="tags">
    {% for tag in item.tags %}
    <span class="tag">{{tag}}</span>
    {% endfor %}
</div>
{% endif %}

Looping Through Lists

If you have multiple items (like tags, categories, or related content), you can loop through them:

<!-- Display all tags -->
{% if item.tags %}
<div class="tags">
    {% for tag in item.tags %}
    <a href="/tags/{{tag}}" class="tag">{{tag}}</a>
    {% endfor %}
</div>
{% endif %}

Formatting Dates

You can format dates in various ways:

<!-- Full date -->
<p>Published on {{item.date|date('F j, Y')}}</p>

<!-- Short date -->
<p>{{item.date|date('M j, Y')}}</p>

<!-- Just the year -->
<p>{{item.date|date('Y')}}</p>

Common Template Patterns

Blog Post Template

<article class="blog-post">
    <header>
        <h1>{{item.title}}</h1>
        <div class="meta">
            <span class="author">By {{item.author}}</span>
            <span class="date">{{item.date|date('F j, Y')}}</span>
        </div>
    </header>

    {% if item.image %}
    <img src="{{item.image}}" alt="{{item.title}}" class="featured-image" />
    {% endif %}

    <div class="content">{{item.body}}</div>

    {% if item.tags %}
    <footer>
        <div class="tags">
            {% for tag in item.tags %}
            <a href="/tags/{{tag}}" class="tag">{{tag}}</a>
            {% endfor %}
        </div>
    </footer>
    {% endif %}
</article>

Product Template

<div class="product">
    <h1>{{item.title}}</h1>

    {% if item.image %}
    <img src="{{item.image}}" alt="{{item.title}}" />
    {% endif %}

    <div class="price">${{item.price}}</div>

    <div class="description">{{item.body}}</div>

    {% if item.features %}
    <ul class="features">
        {% for feature in item.features %}
        <li>{{feature}}</li>
        {% endfor %}
    </ul>
    {% endif %}
</div>

Tips and Best Practices

Always check if properties exist before using them to avoid errors
Use meaningful property names in your content frontmatter
Keep templates simple - focus on structure and let the content drive the design
Test your templates with different types of content to ensure they work properly
Use consistent naming for your properties across all your content

Common Properties Reference

Here's a quick reference of commonly available properties:

Property

Description

Example

item.title

Content title

"My Blog Post"

item.body

Main content

HTML content

item.date

Publication date

2024-01-15

item.author

Author name

"John Doe"

item.slug

URL-friendly title

"my-blog-post"

item.url

Full URL

"/blog/my-blog-post"

item.image

Featured image

"/images/post.jpg"

item.excerpt

Short summary

"This is a brief description..."

item.tags

Content tags

["technology", "web-design"]

item.category

Content category

"Technology"

Remember, you can always add custom properties to your content's frontmatter and access them using the same {{item.property_name}} syntax!

PreviousPretty URL's NextTwig

Last updated 5 days ago