Caress the Divine Detail! (Part One)

Namaste!

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 third tut in this series, meant for Divi users that want to begin creating and customizing the builder modules. There is a lot of details that need to be covered, so these tutorials are a little dense. Take it slow (maybe several sittings) and feel free to ask questions!

In our last tut, we examined the first method (remember, in a class object, a function is called a method) that initialized the class – adding our slug, outlining what fields would be used, and adding some defaults and options. In this tut, we are going to begin digging into the second method, ‘get_fields()’. This method delineates what each field presented in the module will look like – what type it is, what labels are added, what tab of the builder it is located in, and whether it impacts other fields in the builder. There is a lot to cover, but let’s get started.

In this case, I will be using the Post Slider Module because it has a relatively simple ‘get_fields()’ method. As we will cover in future tuts, some of the modules are split in their design. A good example of this is the Contact Form module where you have a number of additional fields for email, message, etc… that can be added. Each of these are treated as an item that is added to the main ‘get_field()’ method. The Image module that we used in the last tut has some code for animation options at the beginning of its method, so I’ll start with a simple one.

In essence, this method is simply creating an array of comma-separated arrays. Each field is one element in the array. The first field in the Post Slider module sets the number of posts that should be shown. That option is defined by the first array in the ‘get_fields()’ method.

'posts_number' => array(
                'label'             => esc_html__( 'Posts Number', 'et_builder' ),
                'type'              => 'text',
                'option_category'   => 'configuration',
                'description'       => esc_html__( 'Choose how many posts you would like to display in the slider.', 'et_builder' ),
            ),

The first line is saying, “set the key ‘posts_number’ equal to the following array”. Remember, in PHP the equal sign followed by a greater-than sign is used to set “key”=>”value” pairs. Essentially setting the key property equal to a certain value. So in the above code, we are setting a total oof four “key”, “value” pairs. Looking at the ‘init()’ method proceeding it, we can see that ‘posts_number’ is one of the whitelisted_fields. The other thing that I will point out is that we don’t have to define our fields in the same order as they are listed in the whitelisted_fields. When designing from scratch, I like to put them in the same order so that I make sure I white_list everything for which I define a field and vice-versa. 

Almost every field is going to then have four properties defined within its array. First is the ‘label’ – this is what appears to the left of the input area in the picture above. The esc_html__() function in WordPress does two jobs. If you are using a different language, it retrieves the translation of the string from the provided domain, in this case, ‘et_builder’. Second, it escapes any HTML in the translation file making the output safe. 

Second is the ‘type’ – in this case we are asking the Divi builder to put a simple text input field to accept user input. Defined types (exhaustive, I think):

1. ‘text’  Provides a simple input field – short input like a name or number
2. ‘textarea’  Provides a simple input field – long input like a message
3. ‘select’    Provides a drop down list of values for the user to select from
4. ‘yes_no_button’  Provides a switch that can toggle between two values (doesn’t have to be yes and no)
5. ‘color’  Provides a color picker without the option for opacity (rgb)
6. ‘color-alpha’  Provides a color picker with opacity option (rgba)
7. ‘upload’  Provides a link to the media library to select a file
8.  ‘multiple_checkboxes’  Provides multiple checkboxes to allow for selection of more than one option (Used for display on phone/tablet/desktop)
9. ‘range’  Provides a slider for the input of a number
10. ‘hidden’  Provides an empty field that isn’t shown to the user
11. ‘skip’ Provides an empty field like a ‘text’ type that is used for custom padding and margins
12. ‘tiny_mce’  Provides a WYSIWYG editor for input – like in the Code module

I will go through the options for each of the different types in my next tutorial (might take several depending on detail!).

Third, is the ‘option_category’. This field typically has one of four different values that I have to admit I don’t fully understand the differences:

1. ‘basic-option’  Seems to be used for fields that change the content of the output (like adding an image or author name)
2. ‘configuration’  Seems to be used for that change how the content is displayed
3. ‘layout’ Similiar to ‘configuration’, not sure of the difference
4. ‘color_option’  Used in conjuction with the ‘select’ type, not with the ‘color-alpha’ or ‘color’ types

Note – as far as I can tell, the ‘color’ and ‘color-alpha’ types do not have an ‘option-category’ value.

Fourth is the ‘description’ property. This property provides a string that is displayed to the user below the input field to inform the user what type of input is expected (light gray in the picture above). Once again, this value is put through the ‘esc_html__()’ function to ensure that it is translated and safe to display.

So, those are the basic properties that are set for almost every field. Another basic property is the ‘tab_slug’. If undefined, our field will be presented on the first ‘General Settings’ tab. If it is set equal to ‘advanced’ it will be shown on the ‘Advanced Design Settings’ tab (the second tab). Finally, a value of ‘custom_css’ will cause display of the field on the third tab, ‘Custom CSS’.

So, I know this tut had a lot of information, but still leaves a lot out! In the next few tuts I will go through the additional properties that need to be set-up to give choices for the ‘select’, ‘multiple_checkboxes’, and ‘yes_no_button’ types.

As always, feel free to ask questions or point out errors in the comments or by email. I hope this series is proving useful. Only a few more informative tuts and we will begin the design of our first custom module!

Metta!!