What are "layouts", "r:yield" and "TEMPLATE_CONTENT"?

CleanSlate Theme Development Tutorial Series
Video #9 Templates, radius tags & layouts

Layouts are a new way of organizing your theme. The concept was born from the structure of Rails applications. The goal is to modularize your code and keep it DRY'er.

To better understand the layouts concept, let's examine Slate themes are structured.

In Slate, we split up partials with a _header.rhtml, _masthead.rhtml, _navigation.rhtml, and index.rhtml/ backpage.rhtml. _header.rhtml houses most of our code for our <head>. Often, our _header.rhtml file would open the <head> tag, but not close it. This can lead to questions like, "Where is the closing <head> tag? Why don't tags open and close in the same file?"

Enter layouts.

Layouts allow us to have a central place to open and close tags and keep everything modularized in one file. Layouts allow the flexibility to include partials (other modularized bits of code) and yield content into other parts of the document where we see fit.

What is <r:yield />?

<r:yield /> is where a template gets rendered and inserted into your document. For example, all the code in backpage.html will be inserted wherever your <r:yield /> tag is.

How is <r:yield /> different than a partial?

<r:yield /> allows you to select a template—like Backpage or Frontpage—to use through the UI. 

In contrast, a partial only grabs a unique file containing a single set of code.

Can I see an example?

Sure! Check out default.html in the CleanSlate toolkit. 

Note the <r:yield /> tag. Now check out the backpage.html template . This backpage.html template defines a layout at the top of the file (layout: default , around line 2). From this, we know that the contents of backpage.html will be yielded into default.html , where the <r:yield /> tag is (around line 30).

At the end of the day, layouts are just a different approach to making themes. Layouts will make more sense to you after you build a couple themes. My guess is, after you have familiarized yourself with the concept, you'll enjoy the new structure. You'll also notice how much less repeated code exists between templates (backpage.html, for example) using layouts.

Layouts are a new way of organizing your theme. The concept was born from the structure of Rails applications. The goal is to modularize your code and keep it DRY'er.

To better understand the layouts concept, let's examine Slate themes are structured.

In Slate, we split up partials with a _header.rhtml, _masthead.rhtml, _navigation.rhtml, and index.rhtml/ backpage.rhtml. _header.rhtml houses most of our code for our <head>. Often, our _header.rhtml file would open the <head> tag, but not close it. This can lead to questions like, "Where is the closing <head> tag? Why don't tags open and close in the same file?"

Enter layouts.

Layouts allow us to have a central place to open and close tags and keep everything modularized in one file. Layouts allow the flexibility to include partials (other modularized bits of code) and yield content into other parts of the document where we see fit.

What is {{ __TEMPLATE_CONTENT__ }}?

{{ __TEMPLATE_CONTENT__ }} is where a template gets rendered and inserted into your document. For example, all the code in backpage.html will be inserted wherever your {{ __TEMPLATE_CONTENT__ }} tag is.

How is {{ __TEMPLATE_CONTENT__ }} different than a partial?

{{ __TEMPLATE_CONTENT__ }} allows you to select a template—like Backpage or Frontpage—to use through the UI.

In contrast, a partial only grabs a unique file containing a single set of code.

Can I see an example?

Sure! Check out default.html in the CleanSlate Toolkit.

Note the {{ __TEMPLATE_CONTENT__ }} tag. Now check out the backpage.html template. This backpage.html template defines a layout at the top of the file (layout: default, around line 2). From this, we know that the contents of backpage.html will be yielded into default.html, where the {{ __TEMPLATE_CONTENT__ }} tag is (around line 30).

At the end of the day, layouts are just a different approach to making themes. Layouts will make more sense to you after you build a couple themes. My guess is, after you have familiarized yourself with the concept, you'll enjoy the structure. You'll also notice how much less repeated code exists between templates (backpage.html, for example) using layouts.

Last updated on July 20, 2022.

We welcome all questions, feedback and bug reports. If you're having an issue, we usually need the following information:

  • A brief description of the issue
  • A link to the page where you saw the issue
  • Screenshots that illustrate the problem - How do I take a screenshot?

Kindly email CleanSlate@mail.wvu.edu for help or use the form on the request help page.