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 includes 2 settings, let's say a title (text) and a background image (image), then the editor UI will generate for this section a form with 2 input elements: a text input for the input and an image picker to select the background image.
Default definition setting attributes
Name
Type
Description
label
string
Label displayed in the editor UI as the input label.
id
string
Identifier of the section. Required when you want to display the value of the setting inside the HTML template of the section or block. It has to be unique among the settings of a section.
type
string
Describe which kind of input the editor UI will render. See below for a list of available types.
default
string
When a section or a block is added to the page, in order to avoid blank content, Maglev will fill the section or block content with the default value of each setting. 
A value is required.
 advanced
boolean
If the setting is not content related, the editor UI will put this setting in a different tab in the section form.
Available types and their options
text
Display a text input, simple or a rich text editor depending on the setting options.
Definition:
Option
Type
Description
html
boolean
Enable the rich text editor for this setting. False by default.
line_break
boolean
If true (and if the html option is also true), will cause the carriage return (enter key) to generate a <br> tag instead of closing the current element. False by default
nb_rows
integer
Number of rows for the rich text editor.
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:
Template
Raw 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:
Template
Raw 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>
Property
Type
Description
url
string
Url of the image
width
integer
Width of the original image (in px)
height
integer
Height of the original image (in px)
alt_text
string
Alternate text added by the content editor
to_s
string
Alias of the url method
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:
Option
Type
Description
with_text
Boolean
False if the developer only needs an url.
Otherwise, the editor UI will present a text field 
in addition on the URL picker.
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:
Template
Template without text
Raw template (without text)
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:
​
Property
Type
Description
href
String
URL of the page / external URL / email address.
text
String
Text typed by the content editor (if functionality enabled by the with_text option.
open_new_window?
Boolean
True if the content editor wants the link to be opened in a new browser tab.
target_blank
String
Returns _blank or nil depending on the property above.
to_s
String
Alias of the href property.
collection_item
This setting type allows content editors to select an instance of any ActiveRecord class of the main Ruby on Rails application. For instance, in your e-commerce site, if your section is named featured_product_01, chances are big that you will need a collection_item setting type to let your editors pick the product of their choice among the products table.
Definition:
Option
Type
Description
collection_id
String
ID of the collection as set up 
in theme.yml file
app/theme/sections/sample.yml
settings:
- label: "Product"
  id: collection_item
  type: collection_item
  collection_id: products
​
Usage in the HTML/ERB template:
Template
Raw 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" data-maglev-id="<%= 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 %>
If the content editor hasn't chosen an item or if the item doesn't exist anymore, the setting tag won't rendered.
List of properties: 
Property
Type
Description
exists?
Boolean
True if the collection item exists in DB.
item
Model
The collection item loaded from the DB.
color
Display a color picker. The content editor will have to choose between a selection of color presets defined by the developer.
Definition:
Option
Type
Description
presets
Array of strings
List of hexadecimal colors.
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:
Property
Type
Description
dark?
Boolean
True if the brightness index of this color is less than 128.
light?
Boolean
True if the brightness index of this color is great than 155.
brightness
Integer
Value between 0 and 255.
checkbox
Display a toggle input.
Definition:
app/theme/sections/sample.yml
settings:
- label: "Display warning message ?"
    id: cta_link
    type: checkbox
    default: false
Usage in the HTML/ERB template:
app/views/theme/sections/sample.html.erb
<% if section.settings.display_warning_message %>
  <div>My warning message</div>
<% end %>
List of properties:
Property
Type
Description
true?
Boolean
​
false?
Boolean
​
​

Last modified 2yr ago

Name	Type	Description
label	string	Label displayed in the editor UI as the input label.
id	string	Identifier of the section. Required when you want to display the value of the setting inside the HTML template of the section or block. It has to be unique among the settings of a section.
type	string	Describe which kind of input the editor UI will render. See below for a list of available types.
default	string	When a section or a block is added to the page, in order to avoid blank content, Maglev will fill the section or block content with the default value of each setting. A value is required.
advanced	boolean	If the setting is not content related, the editor UI will put this setting in a different tab in the section form.

Option	Type	Description
html	boolean	Enable the rich text editor for this setting. False by default.
line_break	boolean	If true (and if the `html` option is also true), will cause the carriage return (enter key) to generate a `<br>` tag instead of closing the current element. False by default
nb_rows	integer	Number of rows for the rich text editor.

Property	Type	Description
url	string	Url of the image
width	integer	Width of the original image (in px)
height	integer	Height of the original image (in px)
alt_text	string	Alternate text added by the content editor
to_s	string	Alias of the `url` method

Property	Type	Description
href	String	URL of the page / external URL / email address.
text	String	Text typed by the content editor (if functionality enabled by the `with_text` option.
open_new_window?	Boolean	True if the content editor wants the link to be opened in a new browser tab.
target_blank	String	Returns `_blank` or nil depending on the property above.
to_s	String	Alias of the `href` property.