Overview
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.
See how layouts and templates work together.
Layouts
Layouts are the the foundation of your frontend's HTML. Any markup you want to 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> © {{ now format="Y" }} {{ site_name }} </footer> <script src="/js/site.js"></script> </body></html>An entry can control the layout it's rendered with by setting the layout system variable.
# Use /resources/views/rss.antlers.htmllayout: rssTemplates
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.htmltemplate: gallerytitle: Photo GalleryYou can use the template fieldtype to make choosing your template in any entry easy. Any fieldtype that returns a string like in the example above works too, so you have a lot of flexibility.
Map templates to entry blueprints
To automatically map the template from an entry's blueprint, set the collection's default template to @blueprint.
# collections/{collection}.yamltemplate: '@blueprint'By doing this, Statamic will look for the corresponding template in /resources/views/{collection}/{blueprint}.antlers.html.
For example, if you have an articles collection entry that uses a blueprint with the handle of long, the /resources/views/articles/long.antlers.html template will be used.
You can still set a template on the entry level and override the default.
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 and reference them `{{ partial:like-this }}. The underscore is not necessary in the partial tag definition.
We have a video about Partials too!
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
foreachloop 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.
Recommended Conventions
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.htmlOrganize 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.htmlOrganize 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
