Settings overview

Setting types#

All the data that can be added in the builder mode exist in the form of settings. In turn, there are several levels of settings:

  1. module settings;
  2. template settings;
  3. global settings;

The module settings can be added for modules; they include any CSS settings, HTML attributes (including classes and custom IDs), module scoped CSS custom properties, content settings (for content modules), and some unique settings (if available).

The template settings are applied to the whole template. Among them are responsive mode strategy, CSS custom properties, data variables, custom CSS code 'PRO', and custom JS code 'PRO'.

The global settings are saved separately in DB. They are split by types of templates and are used by all templates of the same type. Among them are responsive mode strategy, CSS custom properties, data variables, custom CSS code 'PRO', and custom JS code 'PRO'.

info

All the module settings and all the template settings are being saved inside a template config. We can export a template config from one site and import it to another site. Template configs are perfectly portable, so we can say that module and templates settings are also portable. However, global settings are NOT included in an exported template config.

Settings data structure#

The layers of settings data specifically designed to work in a certain way. Understanding this data flow is crucial for using Builderius more efficiently!

Key concepts:

  • module settings are attached to a module; module's CSS related settings values are rendered on the page only if the module exists;
  • template settings and all settings of all modules are added in template config, which can be versioned/exported;
  • global settings are saved in DB; these settings are split by template type, so for any given template, only global settings saved under 'all' and the template type are shown and used (e.g. if we are editing template type 'single', then only global settings which belong to 'all' and 'single' types are shown);
  • CSS custom properties (variables) might be overwritten; the order of their appearance (therefore their possibility to be overwritten) is the following: global CSS vars under 'all' -> global CSS vars under specific template type -> template CSS vars -> local (added via module settings) CSS vars (e.g. global CSS var --bgcolor: #fff added under 'all' will be overwritten with template CSS vars named as --bgcolor);
  • Data variables declared first might be used in the next data variable declarations; the order of their evaluation (therefore their possibility to be overwritten) is the following: global data vars under 'all' -> global data vars under specific template type -> template data vars;

Scopes for CSS related settings#

We can assign any CSS related module settings to a specific combination of a media query and CSS selector. By default, these values are chosen:

  • 'all' in media query dropdown
  • 'original' in CSS selector dropdown

Effectively, the above values mean that currently accessible settings are applied only under the module's unique class scope. An example:

.uni-node-u1234567 {
width: 150px;
}
info

We have designed Builderius to keep the builder output as minimal as possible. Each module has only three classes "pre-created": "uni-node", "uni-<module_name>" (e.g. "uni-Paragraph"), and ".uni-node-<unique_id>" (e.g. .uni-node-u4rg5674).

To understand better how to create custom media queries and custom CSS selectors, please, proceed to the following article: Creating media queries and CSS selectors (in development...).

An example with a custom media query and the default CSS selector. In this case, setting "width" was defined twice with different values: under the 'all' default media query and under the custom media query (max-width: 600px):

.uni-node-u1234567 {
width: 150px;
}
@media (max-width: 600px) {
.uni-node-u1234567 {
width: 70px;
}
}

Another example. Same as the previous one plus a complex custom CSS selector #hamburger-input:checked + .navWrapper created under 'all' default media query:

.uni-node-u1234567 {
width: 150px;
}
.uni-node-u1234567 #hamburger-input:checked + .navWrapper {
background-color: red;
}
@media (max-width: 600px) {
.uni-node-u1234567 {
width: 70px;
}
}

Scopes for CSS custom property settings#

As for CSS-related settings, we can assign CSS custom property settings to a specific combination of a media query and a CSS selector.

Global and template CSS custom properties are being rendered in the global :root scope. The global ones first, then the template ones. Naturally, the cascading algorithm is applied in this case. For example, using two CSS variables with the same name added in global and template setting, the priority will be given to the one defined in template settings. The browser will use its value.

Scopes for other types of settings#

Non CSS settings do not take part in the output of any CSS. Some of them might be visible in the final HTML, though. For instance, setting "Custom HTML class" allows adding custom values to the HTML attribute class.

Data variables flow#

Data variables are not CSS related settings and do not render anything just because they created. However, this type of settings has its flow or "cascading" algorithm.

Each data variable has a name and a setting value(s)/expression. For instance, static variables have values, like '12' or 'some text'. Type 'Query to DB' of variables has several values: a query and variables object. The setting of type 'Expression' uses Symphony Expression Language (EL) with its specific syntax. It means all values of 'expression' settings will be evaluated with EL.

Setting value(s)/expression is getting evaluated every time we change an applicant or add/remove data variables or on-demand. In the evaluation process, an object with all data variable names and their evaluated values is getting created in the builder.

Speaking about the flow of data variables, there are two main principles: data variable declared earlier might be used in value/expression of data variable declared later; data variables with the same names overwrite values of each other: those declared later overwrite those declared earlier;

Pro tip

Being aware of data variables data flow, we can create quite complex data logic. An example: the first variable fetches the data from DB (let's say a custom meta field), then this variable is used in an expression of the second variable to modify its value somehow based on information from the current template; then the third variable that also fetches some data from DB based on the unique value of the second variable and so on. the possibilities are truly endless! :)