Caress the Divine Detail! (Part Two)
Note: There has been updates to the Divi theme that make some changes to the code. This tutorial was written about pre-Divi 3.0.45, but having said that, ET was careful to update in such a way that old code still maps nicely. That means that these tutorials are still germane (at least as of May 13, 2017), but we will see what future updates bring! I will be writing new tutorials to introduces the new features of Divi soon!
This is the fourth post in a series looking at the php code underlying the Divi theme modules. So far, we looked at the overall structure of each class that makes up a module and examined the ‘init()’ method that initializes all of the fields and variables that the class uses. In our last tut, we began looking at the second major method of the Divi module classes, the ‘get_fields()’ function. This method delineates how each of the fields should be presented in the backend. We covered the basic properties that each field typically has defined. One interesting one is the ‘type’ property. To recap,
To recap, there are (at least) 12 different possible values for the ‘type’ property, ranging from the simple ‘text’, which creates a text input field, to the ‘multiple_checkboxes’, which unsurprisingly creates multiple checkboxes that the user can tick for different options. The subjects of today’s tut are four of the ‘type’ values: ‘yes_no_button’, ‘select’, ‘multiple_checkboxes’, and ‘range’.
This value is used to generate a switch. While it is called a ‘yes_no_button’, it delivers back a binary choice that can be anything you want. One common use of this is to determine if the Lightbox is used to display an image. In this case, the choices are ‘On’ and ‘Off’. Let’s look at the code for this.
'show_in_lightbox' => array( 'label' => esc_html__( 'Open in Lightbox', 'et_builder' ), 'type' => 'yes_no_button', 'option_category' => 'configuration', 'options' => array( 'off' => esc_html__( "No", 'et_builder' ), 'on' => esc_html__( 'Yes', 'et_builder' ), ), 'affects' => array( 'url', 'url_new_window', 'use_overlay' ), 'description' => esc_html__( 'Here you can choose whether or not the image should open in Lightbox. Note: if you select to open the image in Lightbox, url options below will be ignored.', 'et_builder' ), ),
Walking through the code, we see several properties that should be familiar from the last tut. We are defining a ‘label’ that is showing up to the left of the switch, setting an ‘option_category’, and giving the ‘description’ a value that shows up below the switch. Now we come to a new property, ‘options’. This property holds an array as a value. This array in turn holds two property:value pairs.
The first property taken by the ‘yes_no_button’ type is ‘off’. This provides a translatable lable for the off position using the WP ‘esc_html__()’ function. The second property, unsurprisingly is ‘on’, and it is a translatable label for the other position of the switch. These labels can be anything – for example, a choice between the ‘light’ and ‘dark’ text layouts we see in some modules. Note, the button is called a ‘yes_no_button’, but it takes ‘off’ and ‘on’ as properties – makes sense, right? 🙂
The second new property is a little more complex. The ‘affects’ property takes an array as a value. Each of the strings stored in the array is comma-separated. They are each the names of other fields that can be presented to the user in the backend. So in the Image module, the ‘url’, ‘url_new_window’, and ‘use_overlay’ options will change how they are displayed when the user changes the position of the ‘show_in_lightbox’ ‘yes_no_button’. What determines whether they are shown by default and hidden on switch, or vice-versa? The answer is another property that is included in the field to either be shown or hidden.
The property ‘depends_show_if’ determines whether the field is shown. As we can see from the picture at the top of this section, the field to put in a link URL for our image (defined by the ‘url’ field) is displayed by default. Looking at the ‘url’ fields it has the following:
'depends_show_if' => 'off',
So, if we set the value to ‘off’ it will show until we flip the switch. In contrast, the ‘use_overlay’ field is only displayed after the button is clicked, as shown in the picture just above. The initial value of the ‘depends_show_if’ for the ‘use_overlay’ field is ‘on’.
This can get a little complicated once we start nesting ‘yes_no_button’ types. In the Image module, once the ‘Open In Lightbox’ switch is turned to ‘Yes’, this displays an additional ‘yes_no_button’ field to add an ‘Image Overlay’. Clicking that brings up additional fields that all have their ‘depends_show_if’ set to ‘on’. One property that I’m not sure about is ‘depends_default’. I’ve tried changing this to false without impact. I’m still digging through the code!!
To summarize – if you have a ‘yes_no_button’ type set for a field you need to also provide a ‘options’ property that supplies the labels for each choice. You also have to supply an ‘affects’ property with an array containing the names fields to either be shown or hidden on click. Each of the ‘affects’ fields needs to have a ‘depends_show_if’ property set to ‘off’ or ‘on’ to be shown or not shown, respectively.
The ‘select’ type provides a drop down list of options for the user to select from. Like the ‘yes_no_button’ it requires an ‘option’ property, in this case an array of property:value pairs that defines each of the choices in the drop down list. Let’s look at the code for the ‘Image Alignment’ choice in the Image module:
'align' => array( 'label' => esc_html__( 'Image Alignment', 'et_builder' ), 'type' => 'select', 'option_category' => 'layout', 'options' => array( 'left' => esc_html__( 'Left', 'et_builder' ), 'center' => esc_html__( 'Center', 'et_builder' ), 'right' => esc_html__( 'Right', 'et_builder' ), ), 'description' => esc_html__( 'Here you can choose the image alignment.', 'et_builder' ), ),
Our friends ‘label’, ‘type’, ‘option_category’, and ‘description’ are all there! Looking at the ‘options’ property, there are three choices, ‘left’, ‘center’, and ‘right’. The actual properties will become important later – they are what is passed to the next function that actually builds the page. Following these properties are values that contain the translatable label for each choice. The actual property does not have to match the label. In fact, when translated, they won’t. So even though a German Divi user might select, ‘Links’, the backend function gets passed ‘left’.
Continuing our pattern from the other two types, the ‘multiple_checkboxes’ has all of the basic field properties, with the addition of an ‘options’ property. An example of this is the ‘Disable on:’ field found in most of the modules. The format of the options field is identical to that of the ‘select’ type. The only difference is that all the choices are displayed and more than one can be selected.
As a side note, there is an addition property that is associated with the ‘disabled_on’ field that generates the selection of devices that get disabled. The key:value ‘additional_att’ =>’disable_on’ is added in this block and is processed by the builder to generate changes in the stylesheet, adding ‘display: none;’ to media queries corresponding to each device.
The ‘range’ type accepts a different property from the other advanced types. The property ‘range_settings’ accepts an array with three properties.
'default' => '96px', 'range_settings' => array( 'min' => '1', 'max' => '120', 'step' => '1', ),
The ‘min’ property is the minimum you want you slider to be able to select. This value a decimal or whole number, and it can be less than zero – for example if you want the user to be able to set a negative margin. The ‘max’ property, unsurprisingly, establishes what you want the maximum amount selectable to be. The final property, ‘step’, is how much you want the value to change as you move the slider. This can be a fractional number like ‘0.02’. One other property that can be set here, rather than in the ‘init()’ method, is ‘default’. This will be the value that your slider starts at and also sets the type of value. In this case ‘px’, but it could be ’em’ or ‘%’ depending on where you are using the slider.
Well, that is it for this method! As you look through the main-modules.php code on your own, you will see that there are other properties I haven’t covered, like the mysterious, ‘mobile_options’ => ‘true’! I also have skipped over a bit of how you add in some of the fields on the ‘Advanced Design Settings’ and ‘Custom CSS’ tabs. Divi “automates” some of this since they are re-used so often. In a later tut I will likely revisit the ‘Custom CSS’ tab.
As always, I hope this helps someone. If you have any questions or corrections, please reach out to me in the comments or by email. Happy coding!!