Creating a Custom Module Type

 

In this post we’ll learn how to create a new module type to be used with the theme. This is advanced stuff and coding knowledge is definitely going to be needed in order to make this work. In addition to this, styling will probably be needed to make the new module type look and behave nicely. Again, this is advanced stuff and meant to help developers in the need of code customization.

We’ll assume you’re already working on a child theme for this. If you’re not, there’s one ready to be downloaded in your Artisan Dashboard, and some useful tutorials here.

Also, we’ll be using filters to add the new module type. If you ever need to know the available hooks and filters across the theme, take a look at the /inc/qi-framework/hooks.php file which holds a list of all of those, and also points to the file locations for each in the theme.

Alright, let’s begin.

The first thing we need to do is to filter the list of available module types. For that, in your child theme’s functions.php file, add this:

function at_define_new_module_type( $types ) {
$types['your_module_slug'] = array(
'name' => esc_html__( 'Your New Module Title', 'quadro' ),
'slug' => 'your_module_slug',
'img' => 'your_module_slug', // this serves as name for the .png module icon
'img_path' => get_stylesheet_directory_uri() . '/path-inside-child-theme/'
'desc' => esc_html__( 'Module type description for hover card', 'quadro' ),
);
return $types;
}
add_filter( 'qi_filter_available_modules', 'at_define_new_module_type' );
view raw gistfile1.txt hosted with ❤ by GitHub

Now, pay attention to a couple of things here.

  1. The new module type slug appears in this function three times. Make it as short as possible so to avoid errors later on, but still descriptive so you know what it is at first sight.
  2. You should create an icon image for this module type. The file needs to be a .png and it has to be located in a folder of the child theme. You can specify the location in that function with the ‘img_path’ line.

Once you have that, you should already be seeing your new module type in the list. So let’s add some fields to it.

For that, add this to your functions.php file (but modify it before saving):

function at_my_new_module_box( $boxes ) {
$boxes['mod_crelly_type_metabox'] = array(
'id' => 'mod-crelly-qi-type-metabox',
'title' => esc_html__('Crelly Slider Options', 'quadro'),
'page' => 'quadro_mods',
'context' => 'normal',
'priority' => 'high',
'fields' => array(
array(
'name' => esc_html__('Slider Shortcode', 'quadro'),
'id' => $prefix . 'mod_crelly_shortcode',
'type' => 'text',
'desc' => esc_html__('Paste in this field the shortcode for the slider as you would normally paste on any page.', 'quadro')
),
array(
'name' => esc_html__('Slider Name', 'quadro'),
'id' => $prefix . 'mod_crelly_name',
'type' => 'text',
'desc' => esc_html__('This is an example of a different field.', 'quadro')
),
)
);
return $boxes;
}
add_filter( 'qi_filter_cfields_mods_definition', 'at_my_new_module_box' );
view raw gistfile1.txt hosted with ❤ by GitHub

In this case, this is the example code for the Crelly Slider module. Pay attention to how the slug for the module type (‘crelly’, in this case) is used in the array index “mod_crelly_type_metabox” and then again in the metabox name “mod-crelly-qi-type-metabox”.

You should imitate that structure on your own metabox definition too.

Then, use that array to specify the required fields for the new module type. The ‘id’ of each custom field to be accessed later on in the template files will be ‘quadro_’ + the id you give each option field in that array.

To create each option field for the module, take a quick read at the /inc/custom-fields-definition.php file on the parent theme folder.

Look for the ‘type’ => lines to see what option types you have available. There are many to pick from, and in case you need to checkout what everyone does, the file that controls the render of each field is inside the same folder with the name custom-fields-functions.php.

Note: Pay close attention to the id names for the fields you create so to not override already used ids in the theme.

The only thing left to do after this, is creating a template file for the newly created module type. For that, start by copying one of the template files for the existing modules in the parent theme folder, to get an idea of the proper markup and variables to include in them.

The new template file should be named module-your_module_slug.php.

After this you should be ready to create your own module types.