How-to library · Developer docs

How-to library

Task-shaped pages: a title that starts with a verb, the situation in a few lines, the steps, the working code in both engines, and why this way rather than another. Found from a search, done, and left.

How-to Layouts, areas and components

Build your first standalone component

Published

A component layout is a layout with no controller whose template lives under components/. Create the template, register the layout, add it to a collection's supported layouts, and read your areas from component.

Context

Context. A component is data: one instance of a component layout, with its own content for each of the layout's areas. The layout is registered like a page layout, but with no controller, and instead of being chosen by a page it is placed by an author into a collection or component area of another record. Its template reads its layout areas from component, exactly as a page template reads them from page.

Steps

  1. Create templates/components/quote.html. Deploy.
  2. In the admin, add a layout: name Quote, template components/quote.html. Templates under components/ are always component layouts, so the controller field is hidden.
  3. Add the layout areas: quote (Textarea), attribution (Text).
  4. Open the page layout's collection area and add Quote to its supported layouts.
  5. Add a quote to a page as an author, save, and check the page signed out.

Code

JSON 
{ "areas": { "quote": "Textarea", "attribution": "Text" } }
Template code 
{* templates/components/quote.html *}
{$quote = $component->quote}
{if !empty($quote)}
<blockquote class="quote">
  <p>{$quote|nl2br}</p>
  {if !empty($component->attribution)}<footer>{$component->attribution}</footer>{/if}
</blockquote>
{/if}
{# templates/components/quote.html #}
{% set quote = component.quote %}
{% if quote is not empty %}
<blockquote class="quote">
  <p>{{ quote|nl2br }}</p>
  {% if component.attribution is not empty %}<footer>{{ component.attribution }}</footer>{% endif %}
</blockquote>
{% endif %}

Why this and not that

Not a partial included from the page template: a partial is markup a developer places, a component is content an author places and fills, and only the second shows up in the admin. Not a page layout with the controller left blank by accident: the sign is a "page layout" that never appears in the page form. Guard for empty: a component whose areas are all empty is still a component, and renders whatever your template prints for nothing.

Go deeper
GuideComponents and collections GuideWhat a layout is, field by field

Was this page helpful?

Your answer goes to the docs team.