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

Create an input type for a design-token dropdown

Published

A select input type whose option keys are CSS classes and whose labels are what the author reads. Define it once, reuse it on every layout that offers the choice, and print the key straight into class="".

Context

Context. Half the input types on a mature site are selects that each control one design choice: section background, text alignment, column width, button style. Give each its own input type, name it after the choice, and make every option's key the CSS class the template will print. The author sees the label; the template receives the key.

Steps

  1. In the admin, under Customization, Input types, add one: name Section style, category text, editor select.
  2. Enter the possible values one per line as key::Label, keys being the classes.
  3. Set a default (section-light) so templates can assume a value.
  4. Add a layout area of that type to each layout that offers the choice, named sectionStyle and marked as an attribute.
  5. Print the key into the class attribute with getAreaText(), never the shorthand, which wraps the value in live preview.

Code

section-light::Light
section-dark::Dark
section-primary::Brand colour
Template code 
<section class="section {$component->getAreaText('sectionStyle')}">
  {$component->body}
</section>
<section class="section {{ component.getAreaText('sectionStyle') }}">
  {{ component.body }}
</section>

Why this and not that

Not a free-text area: authors type inconsistent values and typos become missing styles. Not labels as keys: a label changes when the wording changes, a key must not, because records hold the key and a record holding an old key fails validation on its next save. Not one input type per layout: a new option added to one shared type appears everywhere at once, and the option lists never drift apart. Through the API, send the key alone.

Go deeper
GuideCategory and editor decide behaviour GuidePattern: attributes to CSS classes

Was this page helpful?

Your answer goes to the docs team.