Plugin Customizer is a framework that makes it easy to add the WordPress Customizer to your plugin.
CSS PHP JavaScript
Latest commit 04f62e7 Jan 12, 2017 @soderlind Add missing files

README.md

Plugin Customizer

Build Status Code Climate

The goal

The reason I made Plugin Customizer is to make it easy to add WordPress Customizer to your plugins.

Use

  1. Clone or download this repository and copy the src folder to your plugin.
  2. Add the autoloder to your plugin.
  3. Add Plugin_Customizer class and Plugin_Customizer_Interface to your plugin class.
  4. Init Plugin_Customizer in your constructor my calling PluginCustomizer\Plugin_Customizer::init()

It you'd like to learn more, read the inline comments in the demo plugin and src/Plugin_Customizer.php

// add autoloader
require_once PLUGIN_CUSTOMIZER_DEMO_PATH . 'inc/ps-auto-loader.php';
$class_loader = new PS_Auto_Loader();
$class_loader->addNamespace( 'PluginCustomizer', PLUGIN_CUSTOMIZER_DEMO_PATH . 'src' );
$class_loader->register();

class MyPlugin extends \PluginCustomizer\Plugin_Customizer implements \PluginCustomizer\Plugin_Customizer_Interface {
    function __construct() {
        \PluginCustomizer\Plugin_Customizer::init( array(
            'name' => 'Customizer Demo', // name your plugin
            'url'  => plugins_url( '', __FILE__ ),
            'path' => plugin_dir_path( __FILE__ ),
        ) );
    }
}

Btw, an interface can be considered as a reminder of which methods you must add to your MyPlugin class. They are:

interface Plugin_Customizer_Interface {
    public function plugin_customizer_add_templates();
    public function plugin_customizer_previewer_postmessage_script();
    public function customizer_plugin_sections( $wp_customize );
    public function customizer_plugin_settings( $wp_customize );
    public function customizer_plugin_controls( $wp_customize );
}

plugin_customizer_add_templates();

plugin_customizer_add_templates() let you add the templates you'd like to use in the preview.

/**
 * Load default template
 * Optionally load separate templates for the customizer sections.
 *
 * @author soderlind
 * @version 1.1.0
 */
public function plugin_customizer_add_templates() {
    /**
     * The default template used when opening the customizer
     * @var array
     */
    $default_url = array(
        'url' => parent::template_url( 'newsletter.php' ), // translates to templates/newsletter.php
    );
    /**
     * Option, add a template to a section. key = section name, value = url to template.
     *
     * The last part, title and content in the exmple below, will translate to title.php
     * and content.php in the templates folder.
     */
    $section_urls = array(
        'newsletter_title_section'    => parent::template_url( 'title.php' ), // translates to templates/title.php
        'newsletter_content_section'  => parent::template_url( 'content.php' ), // translates to templates/content.php
    );
    parent::add_templates( $default_url, $section_urls );
    /**
     * If you don't have different templates per section, just load the default template
     */
    // parent::add_templates( $default_url );
}

plugin_customizer_previewer_postmessage_script();

Use the plugin_customizer_previewer_postmessage_script() to add your postmessage javascript file.

/**
 * Load the preview script. The script is needed sice the transport is postmessage
 * @author soderlind
 * @version 1.0.0
 */
public function plugin_customizer_previewer_postmessage_script() {

    $handle = 'plugin-customizer-demo-init';
    $src = plugins_url( 'js/plugin-customizer-init.js' ,  __FILE__ );
    $deps = array( 'customize-preview', 'jquery' );
    $version = PLUGIN_CUSTOMIZER_DEMO_VERSION;
    $in_footer = 1;
    wp_enqueue_script( $handle, $src, $deps, $version , $in_footer );
}

customizer_plugin_sections(), customizer_plugin_settings() and customizer_plugin_controls()

In these functions you add the needed sections, settings and controls followin the specification the Customizer API.

The demo plugin has a simple implementation.

Demo

You know the drill, download, add and activate the plugin. It will add the Plugin Customizer admin menu entries in:

  • Root menu
  • Submenu
  • Admin bar menu
  • Option Page

Copyright and License

Plugin Customizer is copyright 2016 Per Soderlind

Plugin Customizer is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.

Plugin Customizer is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with the Extension. If not, see http://www.gnu.org/licenses/.