Views

Views contain HTML, have access to your data, and are used to render the front-end of your site. Layouts, templates, and partials are all different types of views.

Views contain the HTML served by the frontend of your site and are stored in the resources/views directory. A simple view might look something like this (but should it?):

// resources/views/greeting.antlers.html

<html>
  <body>
    <p>The invention of the shovel was ground breaking.</p>
  </body>
</html>

Each file inside your resources/views directory is a view. Each view can be used in different ways — given different roles and responsibilities.

Layouts

Layouts are the the foundation of your frontend’s HTML. Any markup you want present no matter what page you’re on, no matter where you go, how far you travel, or loud you sing, should go into a layout.

By default, Statamic will look for and use /resources/views/layout.antlers.html, but you’re welcome to create other layouts and configure specific entries, whole sections, or the whole site to use those instead.

Layouts usually contain <head></head> markup, global header, navigation, footer, JavaScript includes, and so on. In between all that HTML is your template area — the magical place where unique, non-global things happen. Use the {{ template_content }} variable to set where you’d like that live.

// resources/views/layout.antlers.html
<html>
  <head>
    <title>{{ title }} | {{ site_name }}</title>
    <link rel="stylesheet" href="/css/tailwind.css">
  </head>
  <body>
    {{ partial:nav }}
    {{ template_content }}
    <footer>
      &copy; {{ now format="Y" }} {{ site_name }}
    </footer>
    <script src="/js/site.js"></script>
  </body>
</html>

An entry can control the layout its rendered with by setting the layout system variable.

# Use /resources/views/rss.antlers.html
layout: rss

Templates

Templates are views that can be used by any entry or section on your site. The template’s contents will be inserted into the {{ template_content }} variable in your layout much like the way a painting goes into an ornate picture frame.

An entry can control the template it’s rendered with by setting the template system variable.

# This fake entry will use /resources/views/gallery.antlers.html
template: gallery
title: Photo Gallery

You can use the template fieldtype to make choosing your template in any entry easy.

Partials

Partials are reusable views that may find themselves in any number of other layouts, templates, and other partials. You can use any view as a partial by using the partial tag.

// This will import /resources/views/blog/_card.antlers.html
{{ partial:blog/card }}

We recommend prefixing any views intended to be only used as partials with an underscore, _like-this.antlers.html. You don’t need to include the underscore in your partial tag.

Using Blade

If your view ends with .blade.php instead of .antlers.html, it will be rendered with Laravel’s Blade engine. All of the same data will be injected into the view, but you won’t have access to Statamic’s tags.

This is useful if…

  • You want to reuse existing Laravel views and keep your markup DRY.
  • You have some gnarly loops to work with and can benefit from temporary variables and the foreach loop approach.
  • You’re really used to using Blade and don’t want to learn anything else even if it’s really simple, similar, and powerful. You do you.

We recommend the following conventions for consistency. These are just suggestions, not requirements.

Naming

  • Use lowercase filenames
  • Use hyphens to separate words
  • Prefix partials with _underscores
  • Be consistent with plurality (e.g. blog, articles, faq)

Organizing

There are a few recommended ways to organize your layouts, templates, and partials. But you don’t have to take our word for it. 🌈

Go Super Flat

Partials are indicated by a prefixed underscore (_header), layout by the word layout and everything else is a template. Best for small sites.

resources/views/
|-- _header.antlers.html
|-- about.antlers.html
|-- article.antlers.html
|-- layout.antlers.html
|-- listing.antlers.html
|-- page.antlers.html

Organize by Type

This is a bit more of a Statamic v2 style where views are grouped by type - partials, layouts, and templates. Best for medium sized sites.

resources/views/
|-- partials/
|   |-- _card.antlers.html
|   |-- _footer.antlers.html
|   |-- _nav.antlers.html
|-- layouts/
|   |-- amp.antlers.html
|   |-- api.antlers.html
|   |-- main.antlers.html
|-- templates/
|   |-- about.antlers.html
|   |-- article-list.antlers.html
|   |-- article-show.antlers.html
|   |-- faq-list.antlers.html
|   |-- faq-show.antlers.html
|   |-- form.antlers.html

Organize by Section

A more Laravel/application approach where views are grouped by section (or collection), along with their own partials and alternate layout files. Best for large sites.

resources/views/
|-- blog/
|   |-- _card.antlers.html
|   |-- index.antlers.html
|   |-- layout.antlers.html
|   |-- rss.antlers.html
|   |-- show.antlers.html
|-- contact/
|   |-- index.antlers.html
|   |-- success.antlers.html
|-- faq/
|   |-- layout.antlers.html
|   |-- index.antlers.html
|   |-- show.antlers.html
|-- layout.antlers.html

Additional Reading

  • If you want to learn more about how data gets into your view, check out The Cascade
  • If you’d like to manipulate your data before it arrives in your view, check out View Models.
  • If you want to use a third-party template engine (like Twig), check out Other Template Engines.
  • If you want to fetch data from Laravel or do other more programmery-things, you’ll want to do that from a Controller.
Betterify this page on Github!