Redux

# JS Button field

The Redux JS Button extension is a new way to activate JavaScript functions manually from within the options panel. Once you've set up the field code with the buttons you'd like to display, you simply assign a JavaScript function name to the button, include that function in a JavaScript file assigned to the field and watch the magic happen!

Table of Contents

Getting Started

Please be aware that a working knowledge of PHP and CSS is required to properly use this extension. Should you not be familiar with one or the other (or both), please refer to the following guides to get you started: Getting Started with PHP (opens new window), CSS Introduction (opens new window).

Also, knowledge of JavaScript and/or jQuery (opens new window) is required to author your own functions. This extension does all the work behind the scenes to trigger your custom functions, but to accomplish anything when the buttons are clicked, you'll need to be able to author your own code.

# Arguments

Name Type Default Description
type string js_button Value identifying the field type.
id string Unique ID identifying the field. Must be different from all other field IDs.
title string Displays title of the field.
subtitle string Subtitle display of the field, situated beneath the title.
desc string Description of the field, appearing beneath the field control.
class string Appends any number of classes to the field's class attribute.
script array Array of key/pair values defining the JavaScript file containing button functions. See 'Setting up the Script Argument' below.
buttons array Set of arrays defining the buttons to display. Please see 'Setting up Buttons' below.
hint array Array containing the content and optional title arguments for the hint tooltip. More info

Also See

# Settings up the Script Argument

The script argument sets up the JavaScript file and associated options, so that when a JavaScript button is clicked, it knows where to search for the function associated with it. These arguments mirror the WordPress wp_enqueue_script() (opens new window) function parameters, as the extension uses this WordPress API to enqueue your script.

Name Type Default Description
url string Fully qualified URL to and including the JavaScript file name. See Notes below.
dep array Array of the handles of all the registered scripts that this script depends on, that is the scripts that must be loaded before this script. This parameter is only required when the script with the given $handle has not been already registered using wp_register_script(). Default handles are all in lower case.
ver string time() String specifying the script version number, if it has one, which is concatenated to the end of the path as a query string.
in_footer bool true Normally, scripts are placed in of the HTML document. If this parameter is true, the script is placed before the end tag.

NOTES

While it doesn't matter where you might choose to store your script, it is important to never hard code the path to the script's location. To get a proper URL to local scripts, use plugins_url() (opens new window) for plugins and get_template_directory_uri() (opens new window) for themes.

# Setting Up Buttons

The buttons argument accepts a single array populated by arrays that accept the following arguments:

Name Type Default Description
text string Required. The text to appear as the button's caption
class string Optional. Any additional class names to append to the buttons class parameter.
function string Required. The name of the function to call inside the script passed via the scripts argument.

# Example Config

For this example (included in the download), assume we've placed our javascript file in the theme's root directory. We can easily obtain its location using get_template_directory_uri() (opens new window). Since our example javascript (shown below) uses jQuery (opens new window), we must pass the jQuery (opens new window) dependency via the scripts dep argument.

array (
    'id'            => 'opt-js-button',
    'type'          => 'js_button',
    'title'         => 'JS Button',
    'subtitle'      => 'Run javascript manually from the options panel.',
    'script'        => array(
        'url'       => get_template_directory_uri() .  '/sample.js',
        'dep'       => array('jquery'),
        'ver'       => time(),
        'in_footer' => true
    ),
    'buttons'       => array(
        array(
            'text'      => 'Add Date',

            // This class causes the button to appear colored in the options panel
            'class'     => 'button-primary',

            // The name of the function to execute in the sample.js file
            'function'  => 'redux_add_date'
        ),
        array(
            'text'      => 'Alert',
            'class'     => 'button-secondary',

            // The name of the function to execute in the sample.js file
            'function'  => 'redux_show_alert'
        ),
    ),
),

// This empty text field will be used for the redux_add_date function to fill out 
// with the current date, when the button is clicked.
array(
    'id'        => 'opt-blank-text',
    'type'      => 'text',
    'title'     => 'Date',
),

# Example JavaScript File: sample.js

// Function to execute when the Add Date button is clicked.
function redux_add_date() {
    (function($){
        'use strict';

        $(document).ready(function(){
            var date = new Date();
            var text = $('#opt-blank-text');
            
            text.val(date.toString());
        });    
    })(jQuery)    
};

// Function to execute when the Alert button is clicked.
function redux_show_alert() {
    alert ('You clicked the Alert button!');
};

← Metaboxes →