The Redux API

With Redux 3.5+, we’ve completely redesigned the way in which config files for Redux Framework options panels are created.  In the past, the process involved creating a PHP class, dividing the declaration of arguments, help tabs, and section into different functions and feeding them into a new instance of the Redux Framework object (see sample-config-legacy.php in the sample folder for a more detailed analysis).  The biggest drawback to this method was the name of the class.  Each needed to be unique among multiple instances of Redux.  This causes many headaches for developers, and by extension, the Redux support team.

With the Redux API, no longer is this an issue.  The process has been streamlined into a handful of API calls, without the hassles of ensuring unique class names, and understanding of how PHP classes work.

If reviewing documentation isn’t your thing, you are always free to jump directly to the updated sample-config.php in the sample folder of the Redux Framework package to see how it’s all put together.

The Basic API

The API is wrtten as a static class.  Don’t worry, you don’t need any knowledge of static classes, only how to call them, which is done with the class name, two semicolons, and the function name as demonstrated in the examples below.

Ideally, a basic Redux Framework config file will use three or four basic API calls to create the standard options panel.  We’ll begin with the suggested order in which to use them.

First, it’s always a good idea to check that the API class exists.  it avoids potential errors in the event an older version of Redux is still in use on your site by a different dev or vendor.  The following should be the first lines in your config file:

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

Next, set the opt_name variable of your panel to a variable. It’s easier to set the opt_name in the fashion as it is used for each and every Redux API call. The next line in our example config would be as follows:

// Remember, 'redux_demo' is stricly for this example.  
// Please change it to your own unique name.
$opt_name = "redux_demo";

Remember, the classname of the Redux API is titled Redux. To call the function, two semi-colons follow the classname, and then the actual API call.

Now, we’ll begin with the first API call, Redux::setArgs

setArgs

Redux::setArgs ($opt_name, $args)

The setArgs API requires two parameters, the opt_name string value and the actual arguments, an array value.

Here is an example:

$args = Array(
    'opt_name'    => $opt_name,
    // Any other arguments you wish to set.  To save space in this example
    // please refer to the arguments documentation, or review the
    // sample-config.php file
);

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

The next two APIs deal with setting the help tabs and sidebar of the admin panel when the Redux Framework options panel is visible.

setHelpTab

Redux::setHelpTab ($opt_name, $tabs)

setHelpTab requires two parameters, the $opt_name string value, followed by an array value of tab data.

$tabs = array(
    array(
        'id'      => 'redux-help-tab-1',
        'title'   => 'Theme Information 1',
        'content' => '<br />This is the tab content, HTML is allowed.<br />')
    ),
    array(
        'id'      => 'redux-help-tab-2',
        'title'   => 'Theme Information 2',
        'content' => '<br />This is the tab content, HTML is allowed.<br />')
    )
);
Redux::setHelpTab( $opt_name, $tabs );

setHelpSidebar

Redux::setHelpSidebar ($opt_name, $content)

setHelpSidebar requires two parameters. First, the $opt_name string value, the second, the $content string value.

$content = '<br />This is the sidebar content, HTML is allowed.<br />');
Redux::setHelpSidebar( $opt_name, $content );

Now it’s time to set our sections.

setSection

Redux::setSection ($opt_name, $sections)

setSections requires two parameters. First, the $opt_name string value, the second, an array of section data.

Each call to the setSection API will create a section tab (or subsection of a section) in the options panel.

// Lets create a section with no subsections, a basic section, if you will.
$section = array(
    'title'  => 'Basic Field',
    'id'     => 'basic',
    'desc'   => '',
    'icon'   => 'el el-home'   
    'fields' => array(
        array(
            'id'       => 'opt-text-example',
            'type'     => 'text',
            'title'    => 'Text Field',
            'subtitle' => 'Subtitle',
            'desc'     => 'Field Description',
            'default'  => 'Default Text',
        ),    
    )
);
Redux::setSection($opt_name, $section);

// Now let's create a section with two subsections
// First, create the parent panel.
$section = array(
    'title' => 'Basic Subsection Fields',
    'id'    => 'basic-subsection',
    'desc'  => '',
    'icon'  => 'el el-home'   
    )
);
Redux::setSection($opt_name, $section);

// The first subsection
$section = array(
    'title'      => 'Text Field',
    'id'         => 'basic-text-subsection',
    'subsection' => true,
    'desc'       => '',
    'fields'     => array(
        array(
            'id'       => 'opt-text-subsection-example',
            'type'     => 'text',
            'title'    => 'Text Field',
            'subtitle' => 'Subtitle',
            'desc'     => 'Field Description',
            'default'  => 'Default Text',
        ),        
    )
);
Redux::setSection($opt_name, $section);

// The second subsection
$section = array(
    'title'      => 'Checkbox Field',
    'id'         => 'basic-checkbox-subsection',
    'subsection' => true,
    'desc'       => '',
    'fields'     => array(
        array(
            'id'       => 'opt-checkbox-subsection-example',
            'type'     => 'checkbox',
            'title'    => 'Checkbox Field',
            'subtitle' => 'Subtitle',
            'desc'     => 'Field Description',
            'default'  => '1'
        ),        
    )
);
Redux::setSection($opt_name, $section);

setExtensions

Redux::setExtensions($opt_name, $path)

If you are a user of Redux Extensions (and why wouldn’t you be? We offer several that take Redux Framework to a whole new level!) the Redux API makes including them in your project a one-liner breeze! No more loader files and setting variables within them, as per the ‘old way’.

setExtensions requires two parameters. First, the $opt_name string value, the second, the path to either a single extension or a folder of extensions. This API may be used multiple times, if needed.

// You will need to determine the specific path to 
// wherever you choose to keep your extensions folder.

// For this example, we're assuming it's in the same 
// directory as our config file.
$ext_path = dirname( __FILE__ ) . '/extensions/';
Redux::setExtensions($opt_name, $ext_path);

The Advanced API

For the advanced developer already familiar with PHP and Redux as a whole, we offer some more advanced API to make your programming tasks a bit easier.

init

Redux::init($opt_name)

init requires one parameter, the $opt_name string value. The API is useful in cases where a force load of the Redux object is neccessary, even if it’s already been run.

setSections

Redux::setSections($opt_name, $sections)

setSections requires two parameters. First, the $opt_name string value, the second, an array of section data. This API is similar to setSection, with the noted difference of this particular API allowing for the setting of a group of sections in one call.

getSection

Redux::getSection($opt_name, $id)

getSection requires two parameters. First, the $opt_name string value, the second, the string id of the section to retrieve. The return value is an array of the requested section, or false on failure.

removeSection

Redux::removeSection($opt_name, $id, $all_fields)

removeSection requires two parameters. First, the $opt_name string value, the second, the string id of the section to remove. The optional third variable is a boolean. If set, all fields associated to that section will also be removed from the API, though if left they will never be initialized. They are simply left if you were to make changes to them as needed.

hideSection

Redux::hideSection($opt_name, $id, $hide)

hideSection requires two parameters. First, the $opt_name string value, the second, the string id of the section to hide. The optional third variable $hide is a boolean used to set the visibility, in the situation where you may want to reverse this function and show the section. By default, it can be omitted and it is set to true.

getField

Redux::getField($opt_name, $id)

getField requires two parameters. First, the $opt_name string value, the second, the string id of the field to retrieve. The return value is an array of the requested field, or false on failure.

setField

Redux::setField($opt_name, $field)

setField requires two parameters. First, the $opt_name string value, the second, an array of field data.  Be sure to add the key/pair 'section_id' => "id of section" (replace “id of section” with the actual section ID) to your field array. This is necessary so the field is set to the correct section.

removeField

Redux::removeField($opt_name, $id)

removeField requires two parameters. First, the $opt_name string value, the second, the string id of the field to remove.

hidefield

Redux::hideField($opt_name, $id, $hide)

hideField requires two parameters. First, the $opt_name string value, the second, the string id of the field to hide. The optional third variable $hide is a boolean used to set the visibility, in the situation where you may want to reverse this function and show the field. By default, it can be omitted and it is set to true.

getArgs

Redux::getArgs($opt_name)

getArgs requires one parameters, the $opt_name string value. The return value is an array of global arguments.

getArg

Redux::getArg($opt_name, $key)

getArg requires two parameters. First, the $opt_name string value, the second, the string name of the argument to retrieve. The return value is the value of the requested argument, or empty on failure.

getExtensions

Redux::getExtensions($opt_name, $key)

getExtensions requires one of two parameters, depending on the desired return value:

An array of all loaded extensions
Use the first parameter and specify the $opt_name string. The return value is an array of loaded extensions containing key/pair information of path (the path to the extension) and class (the classname of the extension). On failure, false is returned.

The path to a specific extension
First, pass an empty string for the first parameter. This is necessary, otherwise the return value will be the one indicated above. For the second parameter, specify the key name of the desired extension. The return value will be it’s path.

Epilogue

In conclusion, we feel the Redux API will assist you in authoring your options panels with additional ease and stability.  That said, we here at Redux frown upon the breaking of backward compatibility.  Should you prefer the ‘old way’ of writing your option panels, you are free to continue to do so.  We’ve kept the legacy sample-config file, now titled sample-config-legacy.php as an example of how those methods work.