When an element gets displayed in a custom layout on the frontend of the website, there are certain CSS classes that get outputted in order to give you as much flexibility as possible when writing your custom CSS.
Using default classes
With your web inspector you should setup a custom layout with the Layout Builder as the WordPress user would and then check out what CSS classes get outputted by default for each element.
.element { ... }
All elements are wrapped in the class “element”.
.primary-element-1 { ... }
This provides you with an automatically-generated, unique class for each element. This class includes the area the element is located (i.e. featured, primary, or featured below) and the incremented number. So, for example, a custom layout you create might have classes setup like this for the different elements:
- featured-element-1
- featured-element-2
- primary-element-1
- primary-element-2
- primary-element-3
- featured_below-element-1
- featured_below-element-2
.element-slogan { ... }
Each element also has a class that is unique to the type of element it is – “element-{element_type}” – This allows you to style all elements of a certain type.
.first-element { ... }
The first element of a section (i.e. featured, primary, or featured below) will have the class “first-element”. You could also do the following to style first elements in the two sections uniquely.
#featured .first-element { ... }#main .first-element { ... }#featured_below .first-element { ... }
.last-element { ... }
The last element of a section (i.e. featured, primary, or featured below) will have the class “last-element”. You could also do the following to style last elements in the two sections uniquely.
#featured .last-element { ... }#main .last-element { ... }#featured_below .last-element { ... }
Adding custom CSS classes from the Builder
As of v1.2.1 of the Layout Builder plugin, you can add your own custom CSS classes to elements of your custom layout through the Builder interface.
Since this is a more advanced option, it is hidden by default in order not to confuse the average user who is not making CSS customizations. You can get this option to display for all of your elements by clicking the “Screen Options” tab in top right corner of the Layout Builder page, and selecting for the “CSS Classes” property to show.
Filtering in your own classes
In the previous section, you can see what classes get applied automatically, but what if you want to add in your own classes? You can do this with the filter “themeblvd_element_classes” that gets applied within the themeblvd_get_classes function found in /framework/frontend/functions/helpers.php.
That was a bit of a “themeblvd” mouthful there, I know. So let’s look at where this filter actually gets applied within the theme framework to undersand how it works.
When an element gets displayed, a series of CSS classes are generated as described in the previous section, but then at the end, this themeblvd_get_classes function is called to return any additional classes. The additional classes are based on whatever exists within the $all_classes array shown in the screenshot in correspondence with the type of element.
You can see that, by default, the $all_classes array is empty, meaning no additional CSS classes are added. This is where you have a chance to alter that array by adding your own filter onto “themeblvd_element_classes”. Let’s check out a couple examples on doing this.
Example #1: Adding classes to certain elements
This first example is a common thing I’ve run into in making some of my other themes with this framework.
You have all of these elements in the layout builder and they all have the class “element” where it would easy to style them all a certain way. Let’s say your design requires you to style a box around all elements that get displayed in a custom layout. Well, this would be easy, as you could just do something like this:
.element {
border: 1px solid #ccc;
background-color: #f2f2f2;
}
But then what happens if you want to only put a box around a few types of elements and not other elements? Let’s say you want to style a box around just these types of elements – (1) Slogan (2) Content and (3) Columns. You could do something like this, I suppose:
.element-slogan,
.element-content,
.element-columns {
border: 1px solid #ccc;
background-color: #f2f2f2;
}
This example is very basic but I’m sure you could imagine how this could start to become cumbersome as you start to style different things within those elements or whatever. Wouldn’t it be easier within your CSS if you could style all these elements with a single class? Let’s add the class “boxed-element” to these three types of elements so we could do something like this instead:
.boxed-element {
border: 1px solid #ccc;
background-color: #f2f2f2;
}
That was a bit of a lengthy introduction to this simple example, but none the less, here’s how we would utilize our filter to add this class to those three elements from our Child theme’s functions.php.
function my_builder_classes( $all_classes ) {
$all_classes['element_columns'] = 'boxed-element';
$all_classes['element_content'] = 'boxed-element';
$all_classes['element_slogan'] = 'boxed-element';
return $all_classes;
}
add_filter( 'themeblvd_element_classes', 'my_builder_classes' );
Example #2: Adding classes based on element options
In the previous example, we didn’t utilize the fact that the type of each element and options of each element are also available for us to use when adding these classes. This involves passing additional parameters into our function being used for our filter. This can be a little confusing if you’re new to using the add_filter function.
Here’s our initial setup as we incorporate the additional $type and $options parameter for use when working with our filter. Also when we call add_filter, after the filter and the function name, we need to pass in the third parmeter, the priority (leaving it just at default 10) in order to input to the fourth parameter which tells the filter to utilize three parameters within our function.
function my_builder_classes( $all_classes, $type, $options ) {
// ...
return $all_classes;
}
add_filter( 'themeblvd_element_classes', 'my_builder_classes', 10, 4 );
So basically, without that “2” as the fourth parameter into the add_filter function, we wouldn’t be able to pass in $options into our my_builder_classes function.
Now let’s utilize this by setting up a basic example. Within the “Headline” element of the Layout Builder the user has an option to put in a tagline after the headline text. Let’s say we want to style the element different depending whether the user put in a tagline or not.
So, if the tagline is left empty we won’t do anything, but if the user puts in a tagline, we’ll add the class “headline_has_tagline”.
function my_builder_classes( $all_classes, $type, $options ) {
// Check if this is a headline type option first
// because different elements are going to have
// different options.
if( $type == 'headline' ) {
if( $options['tagline'] ) {
$all_classes['element_headline'] = 'headline_has_tagline';
}
}
return $all_classes;
}
add_filter( 'themeblvd_element_classes', 'my_builder_classes', 10, 3 );