Create Your Own WordPress Theme Option Panel With Redux Framework

Redux framework is one of the most popular, advanced, and free to use option panel frameworks for WordPress themes and plugins. Its flexibility gives you the freedom to create any type of options and settings for your WordPress project.

In this tutorial I will show you how you can install, customize, and use Redux framework in your own theme.

We’ll be walking through the following steps:

1. Installation
2. General Configuration
3. Creating an Option Panel
4. Using Options Within a Theme

Note: I’ll be referring to Redux Framework simply as Redux throughout this tutorial. This is not to be confused with Redux, the “predictable state container for JavaScript apps”.

1. Installation

There are three ways you can include Redux in your project:

• Install it as a separate plugin
• Include it in your theme core
• Include it in a theme-dependent plugin
  
  

Install It as a Separate Plugin

By default Redux can be installed as a plugin. If you go to the Redux Framework WordPress Plugin Page you will see that you can download it as a regular plugin and install it in your WordPress site with any theme. This does not create any options though; all you can do is activate the demo mode with sample options. 

To get an option panel with customized options for your theme or plugin you will need to create a separate config.php file. Read more about how this works:

• WordPress
  Getting Started With Redux Framework: Introducing It and Integrating It Into Your Theme
  Bonang Salemane

Hence the pros and cons of this approach are:

Include It in Your Theme Core

There’s nothing to stop you including Redux in your theme, unless it conflicts with the Theme Check plugin. The logic is the same as before, you still need a config.php file with your custom options, but now you avoid extra plugin installation.

Include It in a Theme-Dependent Plugin

In my opinion, this approach is the best way to include Redux framework. The process is as simple as a normal plugin installation, the only difference being that it is now part of your own theme’s required add-on plugin. 

Modern premium themes usually come with custom elements–custom post types and so on–all of which belongs in a plugin, so the logical approach is to create an add-on plugin linked with your theme. In that add-on plugin you can include your theme options panel. Learn more about creating theme-dependant plugins in this tutorial:

• WordPress
  How to Create a Packed Addons Plugin for WordPress
  Karen Pogosyan

The configuration process of Redux is unaffected by the installation method, so it is up to you how you want to include Redux in your project. That said, I still prefer the last option, so that’s the approach I’ll use to describe configuration.

2. General Configuration

If you examine the default Redux Framework plugin folder you will find lots of files and directories, but all you need here is the ReduxCore folder. 

Copy the all content of that folder to your add-on plugin folder. Create a folder, call it whatever you want, for example optionpanel, and put the ReduxCore content into it. Next, create an empty file inside that folder and call it config.php. Next we will need to require reduxframework, which we will do in a no-conflict way, so if the add-on plugin is installed in the WordPress environment the site will not crash.

In your add-on plugin main file add the code:

<?php

if (!class_exists('ReduxFramework') && file_exists(plugin_dir_path(__FILE__) . '/optionpanel/framework.php'))
    {
	require_once ('optionpanel/framework.php');

	}

if (!isset($redux_demo) && file_exists(plugin_dir_path(__FILE__) . '/optionpanel/config.php'))
	{
	require_once ('optionpanel/config.php');

	}

That is all! Your Redux Framework is now integrated, though you won’t see any option panel yet, as we first need to create some options. This will all be done in the config.php file we created.

3. Creating an Option Panel

As a guideline and starting point you can use the sample-config.php file provided with the Redux plugin. This contains all the code that is needed to start creating your own custom options. For now let’s highlight the main configuration process.

Open your config.php file and at the beginning add this code (the opening <?php tag won’t be needed if it is already present):

<?php

if (!class_exists('Redux'))
    {
	return;
	}

This check makes sure that the Redux Framework is active, otherwise all the options we create will fail to work and will likely throw tons of PHP errors.

Before we start creating our options, we first need some additional configuration. Create a variable that will store all your options and can be used within your theme files:

$opt_name = "your_variable_name";

Make it unique, using prefixes, for example: yourbrandname_yourthemename.

After that, add the code:

$theme    = wp_get_theme();

This is needed to configure any Redux arguments which use information about the installed theme.

Arguments

At this point we need to add the following arguments:

$args = array(
    'opt_name' => $opt_name,
	'display_name' => $theme->get('Name') ,
	'display_version' => $theme->get('Version') ,
	'menu_type' => 'submenu',
	'allow_sub_menu' => true,
	'menu_title' => esc_html__('Theme Settings', yourtextdomain'),'page_title'           => esc_html__('ThemeSettings', yourtextdomain') ,
	'google_api_key' => '',
	'google_update_weekly' => false,
	'async_typography' => true,
	'admin_bar' => true,
	'admin_bar_icon' => '',
	'admin_bar_priority' => 50,
	'global_variable' => $opt_name,
	'dev_mode' => false,
	'update_notice' => false,
	'customizer' => true,
	'page_priority' => null,
	'page_parent' => 'themes.php',
	'page_permissions' => 'manage_options',
	'menu_icon' => '',
	'last_tab' => '',
	'page_icon' => 'icon-themes',
	'page_slug' => 'themeoptions',
	'save_defaults' => true,
	'default_show' => false,
	'default_mark' => '',
	'show_import_export' => true
);

There are lots of arguments here, but don’t worry, I will highlight the most important ones.

menu_type

If you want your theme option page to appear as a separate top level menu item you should set this value to menu, if you need your theme options to appear as a submenu (I prefer to put them under Appearance) set the value to submenu.

dev_mode

You can enable this during development, but don’t forget to disable it when publishing the theme.

update_notice

As Redux will be part of your project you won’t want your users to get any update notices from Redux Framework, so set this to false.

customizer

If you want to show your custom settings as part of the WordPress customizer just set this argument to true.

The arguments array contains plenty more items, and if you want information on each one you can find details in the sample-config.php. For our needs, we’ve customized the arguments enough. Now let’s set the arguments.

Redux::setArgs( $opt_name, $args );

Adding Sections

Now your theme panel is ready, you can add sections with options. Think about sections as being groups. If you want to add (for example) header options, you create a header section and add options to it. To create any section you will need the following structure:

Redux::setSection($opt_name, array(
    'title' => esc_html__('Section title', 'yourtextdomain') ,
	'id' => esc_html__('section-unique-id', ' yourtextdomain') ,
	'icon' => 'icon-name',
	'fields' => array()
));

Here I want to highlight the id attribute–make sure it is unique. You can use custom icons, but the default icon pack is elusiveicons.

Your section is created, so now you can add options to the fields array. A list of available option types, as well as the code structure with explanations and highlights, can be found here. 

If you want to make the section a subsection of the previously added section, just add a new argument 'subsection' => true. 

The option itself is nothing more than an array with arguments, for example:

array(
    'id' => 'opt-checkbox',
	'type' => 'checkbox',
	'title' => esc_html__('Checkbox', 'yourtextdomain') ,
	'subtitle' => esc_html__('No validation can be done on this field type', 'yourtextdomain') ,
	'desc' => esc_html__('This is the description field, again good for additional info.', ' yourtextdomain') ,
	'default' => '1' // 1 = on | 0 = off),

With this code we’ve added a checkbox to our section. The most important things here are the id (it should be unique), and the type (it should be correct, and follow the exact naming of the field type that Redux provides). Again, more details on fields can be found in the sample-config.php file.

Generally, this is all that you need to know to create an options panel. Next we will look at how to use these options.

4. Using Options Within a Theme

Redux stores all options in a global variable. Remember the $opt_name variable that we created in the config.php file? That is the variable that stores all your options, and you can access them in the following way.

First, you need to declare the global variable. And this presents the first potential problem: it isn’t recommended to declare a global variable outside a function or action. The solution is to add to your functions.php file this small function:

function yourprefix_theme_options_global_variable()
    {
	global $yourglobalvariable;
	}

Then, in each page you want to use your options, execute the function first like this:

yourprefix_theme_options_global_variable ();

If you need the global variable inside another function or action you can declare it without this function.

Using Options

If you use options without first checking the option exists you will get a PHP notice saying something about undefined variable/index. Why is this important? Because if the user activates your theme, but does not activate the add-on plugin that contains your option panel, he or she will see a collection of PHP warning notices on undefined variables. Not ideal.

There is a good pattern to avoid this situation—it looks like this:

$your_option_name = (isset($GLOBALS['yourglobalvariable']['youroption'])) ? $GLOBALS['yourglobalvariable']['youroption'] : “yourdefaultvalue
for thisoption”;

With this small check you ensure that you won’t get any undefined variable/index notices. If you don’t want to assign default values or create a variable, you can use this pattern instead: 

If (isset($GLOBALS['yourglobalvariable']['youroption'])
    { // do the stuff…}

Conclusion

Thanks for reading, I hope this gets you started using Redux for your theme options! If you have any questions or suggestions, please leave a comment below.

Useful Links

• reduxframework.com
• ReduxFramework on Facebook
  
• @ReduxFramework on Twitter