Setting

A section or block definition comes with a list of settings. Those settings will be used by the editor UI to render the proper content form of a section (or block).

For instance, if your section has two settings—a title (text) and a background image (image)—the editor renders a form with a text field and an image picker.

Default definition setting attributes

Available types and their options

text

Display a text input, simple or a rich text editor depending on the setting options.

Definition:

app/theme/sections/sample.yml
settings:
- label: "Title"
  id: title
  type: text
  # html: true
  # line_break: true
  # nb_rows: 5

Usage in the HTML/ERB template:

app/views/theme/sections/sample.html.erb
<%= maglev_block.setting_tag :title, html_tag: :h2 %>

<h2 <%= section.settings.title.dom_data %>>
  <%= raw section.settings.title %>
</h2>

image

Display an image picker to let the content editor choose or upload any image.

Definition:

app/theme/sections/sample.yml
settings:
- label: "Screenshot"
  id: screenshot
  type: image
  default: "/samples/images/default.svg"

Usage in the HTML/ERB template:

app/views/theme/sections/sample.html.erb
<%= maglev_section.setting_tag :screenshot, class: 'my-css-class' %>

<img
    <%= section.settings.screenshot.dom_data %>
    src="<%= section.settings.screenshot %>"
    alt="<%= section.settings.screenshot.alt_text %>"
    class="my-css-class"
/>

List of properties:

<p><img src="<%= maglev_section.settings.screenshot.url %>" alt="<%= maglev_section.settings.screenshot.alt_text %>" /></p>

link

Display a link picker. The content editor will have the choice between a link to an external URL, a page or an email address.

Definition:

app/theme/sections/sample.yml
settings:
- label: "Call to action"
  id: cta_link
  type: link
  with_text: true
  default: "/"

Usage in the HTML/ERB template:

app/views/theme/sections/sample.html.erb
<%= maglev_section.setting_tag :cta_link %>

<%= maglev_section.setting_tag :cta_link do %>
   Call us
<% end %>

<a
  href="<%= section.settings.cta_link.href %>"
  <% if section.settings.cta_link.open_new_window? %>target="_blank"<% end %>
>
  Call us
</a>

List of properties:

collection_item

This setting type lets editors pick a record from any ActiveRecord model in your Rails app. For example, on an e-commerce site, a featured_product_01 section often uses a collection_item setting so editors can choose a product from the products table.

Definition:

app/theme/sections/sample.yml
settings:
- label: "Product"
  id: product
  type: collection_item
  collection_id: products

Usage in the HTML/ERB template:

app/views/theme/sections/sample.html.erb
<%= maglev_section.setting_tag :product, class: 'featured-product' do |product| %>
  <h2><%= product.name %></h2>
  <p><%= number_to_currency product.price %></p>
<% end %>

app/views/theme/sections/sample.html.erb
<% if maglev_section.settings.product.exists? %>
  <div class="featured-product" <%= maglev_section.settings.product.dom_data %>>
    <h2><%= maglev_section.settings.product.item.name %></h2>
    <p><%= number_to_currency maglev_section.settings.product.item.price %></p>
  </div>
<% end %>

List of properties:

color

Display a color picker. The content editor will have to choose between a selection of color presets defined by the developer.

Definition:

app/theme/sections/sample.yml
settings:
- label: "Background color"
  id: background_color
  type: color
  presets: ["#F87171", "#FBBF24", "#34D399"]
  default: "#F87171"

Usage in the HTML/ERB template:

app/views/theme/sections/sample.html.erb
<div class="banner" style="background-color: <%= section.settings.background_color %>">
  <h2>Hello world</h2>
</div>

List of properties:

checkbox

Display a toggle input.

Definition:

app/theme/sections/sample.yml
settings:
- label: "Display warning message?"
  id: display_warning_message
  type: checkbox
  default: false

Usage in the HTML/ERB template:

app/views/theme/sections/sample.html.erb
<% if section.settings.display_warning_message.true? %>
  <div>My warning message</div>
<% end %>

List of properties:

icon

Display a popup to select an icon among a set of icons. Follow the instructions here to set up the icon library.

Definition:

app/theme/sections/sample.yml
settings:
- label: "Icon"
  id: cta_icon
  type: icon
  default: 'fa fa-github'

Usage in the HTML/ERB template:

<div>
  <%= maglev_section.setting_tag :icon, html_tag: 'i' %>
</div>

select

Display an HTML select field to let the editor pick one of the options defined in the section definition.

Definition:

app/theme/sections/sample.yml
settings:
- label: "Animation on scroll"
  id: aos_class
  type: select
  select_options:
  - label: Fade
    value: fade-up
  - label: Flip
    value: flip-left
  - label: Zoom
    value: zoom-in
  default: fade-up

Advanced examples:

Simple select with basic options:

settings:
- label: "Menu style"
  id: menu_style
  type: select
  select_options:
  - label: "Option 1"
    value: "option1"
  - label: "Option 2"
    value: "option2"
  default: "option1"

Usage in the HTML/ERB template:

<div class="<%= section.settings.aos_class %>">
   My amazing content
</div>

hint

Shows informational text in the section editing form—for example, tips for content editors.

Definition:

app/theme/sections/sample.yml
settings:
- label: "This text will be displayed in the editor UI"
  id: some_hint
  type: hint

divider

Display a line between two adjacent settings in the editor UI. The label can be shown if the with_hint option is enabled.

Definition:

app/theme/sections/sample.yml
settings:
- label: "This text will be displayed in the editor UI"
  id: a_divider_and_hint
  type: divider
  with_hint: true

Translating setting labels

While the label property defines the default text displayed in the editor UI, you can translate these labels by adding translations to your main application's locale files. The translations follow a specific naming convention under the maglev.themes namespace.

Translation structure

In your Rails application, add translations in your locale files (config/locales/[locale].yml) using this structure:

en:
  maglev:
    themes:
      [theme_name]:
        sections:
          [section_name]:
            settings:
              [setting_id]: "Translated Label"

Example

For instance, if you want to translate the "title" setting label of a "showcase" section in a theme named "simple":

en:
  maglev:
    themes:
      simple:
        sections:
          showcase:
            settings:
              title: "Title 😎"

The system will automatically use these translations in the editor interface when displaying setting labels. If no translation is found, it will fall back to the label value defined in the section's YAML file.

Translating select options

For select type settings, you can translate both the setting label and the individual option labels. The option translations use a specific structure where all options for a setting are grouped under {setting_id}_options:

en:
  maglev:
    themes:
      [theme_name]:
        sections:
          [section_name]:
            settings:
              [setting_id]: "Translated Setting Label"
              [setting_id]_options:
                [option_value]: "Translated Option Label"

Select translation example

Given this select setting definition:

settings:
- label: "Alignment"
  id: alignment
  type: select
  select_options:
  - label: "Left"
    value: left
  - label: "Center"
    value: center
  - label: "Right"
    value: right

You can translate it like this:

en:
  maglev:
    themes:
      simple:
        sections:
          jumbotron:
            settings:
              alignment: "Alignment 📏"
              alignment_options:
                left: "Left 🍪"
                center: "Center 👩🏽‍🍳"
                right: "Right 🍔"

The system will automatically use these translations in the editor interface when displaying both the setting label and the option labels. If no translation is found, it will fall back to the label values defined in the section's YAML file.