21 |
22 |
23 |
24 |
25 | 
3 | # Plugin Customizer
4 |
5 | [](https://travis-ci.org/soderlind/plugin-customizer) [](https://codeclimate.com/github/soderlind/plugin-customizer)
6 |
7 | ## The goal
8 |
9 | The reason I made Plugin Customizer is to make it easy to add WordPress Customizer to your plugins.
10 |
11 | ## Use
12 |
13 | 1. Clone or [download](https://github.com/soderlind/plugin-customizer/archive/master.zip) this repository and copy the `src` folder to your plugin.
14 | 1. Add the autoloder to your plugin.
15 | 1. Add Plugin_Customizer class and Plugin_Customizer_Interface to your plugin class.
16 | 1. Init Plugin_Customizer in your constructor my calling PluginCustomizer\Plugin_Customizer::init()
17 |
18 | It you'd like to learn more, read the inline comments in the [demo plugin](plugin-customizer-demo.php) and [src/Plugin_Customizer.php](src/Plugin_Customizer.php)
19 |
20 | ```php
21 | // add autoloader
22 | require_once PLUGIN_CUSTOMIZER_DEMO_PATH . 'inc/ps-auto-loader.php';
23 | $class_loader = new PS_Auto_Loader();
24 | $class_loader->addNamespace( 'PluginCustomizer', PLUGIN_CUSTOMIZER_DEMO_PATH . 'src' );
25 | $class_loader->register();
26 |
27 | class MyPlugin extends \PluginCustomizer\Plugin_Customizer implements \PluginCustomizer\Plugin_Customizer_Interface {
28 | function __construct() {
29 | \PluginCustomizer\Plugin_Customizer::init( array(
30 | 'name' => 'Customizer Demo', // name your plugin
31 | 'url' => plugins_url( '', __FILE__ ),
32 | 'path' => plugin_dir_path( __FILE__ ),
33 | ) );
34 | }
35 | }
36 | ```
37 | Btw, an interface can be considered as a reminder of which methods you must add to your MyPlugin class. They are:
38 |
39 | ```php
40 | interface Plugin_Customizer_Interface {
41 | public function plugin_customizer_add_templates();
42 | public function plugin_customizer_previewer_postmessage_script();
43 | public function customizer_plugin_sections( $wp_customize );
44 | public function customizer_plugin_settings( $wp_customize );
45 | public function customizer_plugin_controls( $wp_customize );
46 | }
47 | ```
48 |
49 | ### plugin_customizer_add_templates();
50 |
51 | `plugin_customizer_add_templates()` let you add the [templates](templates) you'd like to use in the preview.
52 |
53 | ```php
54 | /**
55 | * Load default template
56 | * Optionally load separate templates for the customizer sections.
57 | *
58 | * @author soderlind
59 | * @version 1.1.0
60 | */
61 | public function plugin_customizer_add_templates() {
62 | /**
63 | * The default template used when opening the customizer
64 | * @var array
65 | */
66 | $default_url = array(
67 | 'url' => parent::template_url( 'newsletter.php' ), // translates to templates/newsletter.php
68 | );
69 | /**
70 | * Option, add a template to a section. key = section name, value = url to template.
71 | *
72 | * The last part, title and content in the exmple below, will translate to title.php
73 | * and content.php in the templates folder.
74 | */
75 | $section_urls = array(
76 | 'newsletter_title_section' => parent::template_url( 'title.php' ), // translates to templates/title.php
77 | 'newsletter_content_section' => parent::template_url( 'content.php' ), // translates to templates/content.php
78 | );
79 | parent::add_templates( $default_url, $section_urls );
80 | /**
81 | * If you don't have different templates per section, just load the default template
82 | */
83 | // parent::add_templates( $default_url );
84 | }
85 | ```
86 |
87 | ### plugin_customizer_previewer_postmessage_script();
88 |
89 | Use the `plugin_customizer_previewer_postmessage_script()` to add your [postmessage](https://developer.wordpress.org/themes/advanced-topics/customizer-api/#using-postmessage-for-improved-setting-previewing) javascript [file](js/plugin-customizer-init.js).
90 |
91 | ```php
92 | /**
93 | * Load the preview script. The script is needed sice the transport is postmessage
94 | * @author soderlind
95 | * @version 1.0.0
96 | */
97 | public function plugin_customizer_previewer_postmessage_script() {
98 |
99 | $handle = 'plugin-customizer-demo-init';
100 | $src = plugins_url( 'js/plugin-customizer-init.js' , __FILE__ );
101 | $deps = array( 'customize-preview', 'jquery' );
102 | $version = PLUGIN_CUSTOMIZER_DEMO_VERSION;
103 | $in_footer = 1;
104 | wp_enqueue_script( $handle, $src, $deps, $version , $in_footer );
105 | }
106 | ```
107 | ### customizer_plugin_sections(), customizer_plugin_settings() and customizer_plugin_controls()
108 |
109 | In these functions you add the needed sections, settings and controls followin the specification the [Customizer API](https://developer.wordpress.org/themes/advanced-topics/customizer-api/).
110 |
111 | The demo plugin has a [simple implementation](https://github.com/soderlind/plugin-customizer/blob/master/plugin-customizer-demo.php#L92-L191).
112 |
113 | ## Demo
114 |
115 | You know the drill, [download](https://github.com/soderlind/plugin-customizer/archive/master.zip), add and activate the plugin. It will add the `Plugin Customizer` admin menu entries in:
116 | - Root menu
117 | - Submenu
118 | - Admin bar menu
119 | - Option Page
120 |
121 |
122 | ## Copyright and License
123 |
124 | **Plugin Customizer** is copyright 2016 Per Soderlind
125 |
126 | **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.
127 |
128 | **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](LICENSE) for more details.
129 |
130 | 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/.
131 |
--------------------------------------------------------------------------------
/inc/ps-auto-loader.php:
--------------------------------------------------------------------------------
1 | prefixes[ $prefix ] ) === false ) {
43 | $this->prefixes[ $prefix ] = array();
44 | }
45 |
46 | // retain the base directory for the namespace prefix
47 | if ( $prepend ) {
48 | array_unshift( $this->prefixes[ $prefix ], $base_dir );
49 | } else {
50 | array_push( $this->prefixes[ $prefix ], $base_dir );
51 | }
52 | }
53 |
54 | /**
55 | * Loads the class file for a given class name.
56 | *
57 | * @param string $class The fully-qualified class name.
58 | * @return mixed The mapped file name on success, or boolean false on
59 | * failure.
60 | */
61 | public function loadClass( $class ) {
62 | // the current namespace prefix
63 | $prefix = $class;
64 |
65 | // work backwards through the namespace names of the fully-qualified
66 | // class name to find a mapped file name
67 | while ( false !== $pos = strrpos( $prefix, '\\' ) ) {
68 |
69 | // retain the trailing namespace separator in the prefix
70 | $prefix = substr( $class, 0, $pos + 1 );
71 |
72 | // the rest is the relative class name
73 | $relative_class = substr( $class, $pos + 1 );
74 |
75 | // try to load a mapped file for the prefix and relative class
76 | $mapped_file = $this->loadMappedFile( $prefix, $relative_class );
77 | if ( $mapped_file ) {
78 | return $mapped_file;
79 | }
80 |
81 | // remove the trailing namespace separator for the next iteration
82 | // of strrpos()
83 | $prefix = rtrim( $prefix, '\\' );
84 | }
85 |
86 | // never found a mapped file
87 | return false;
88 | }
89 |
90 | /**
91 | * Load the mapped file for a namespace prefix and relative class.
92 | *
93 | * @param string $prefix The namespace prefix.
94 | * @param string $relative_class The relative class name.
95 | * @return mixed Boolean false if no mapped file can be loaded, or the
96 | * name of the mapped file that was loaded.
97 | */
98 | protected function loadMappedFile( $prefix, $relative_class ) {
99 | // are there any base directories for this namespace prefix?
100 | if ( isset( $this->prefixes[ $prefix ] ) === false ) {
101 | return false;
102 | }
103 |
104 | // look through base directories for this namespace prefix
105 | foreach ( $this->prefixes[ $prefix ] as $base_dir ) {
106 |
107 | // replace the namespace prefix with the base directory,
108 | // replace namespace separators with directory separators
109 | // in the relative class name, append with .php
110 | $file = $base_dir
111 | . str_replace( '\\', '/', $relative_class )
112 | . '.php';
113 |
114 | // if the mapped file exists, require it
115 | if ( $this->requireFile( $file ) ) {
116 | // yes, we're done
117 | return $file;
118 | }
119 | }
120 |
121 | // never found it
122 | return false;
123 | }
124 |
125 | /**
126 | * If a file exists, require it from the file system.
127 | *
128 | * @param string $file The file to require.
129 | * @return bool True if the file exists, false if not.
130 | */
131 | protected function requireFile( $file ) {
132 | if ( file_exists( $file ) ) {
133 | require $file;
134 | return true;
135 | }
136 | return false;
137 | }
138 | }
139 | }
140 |
--------------------------------------------------------------------------------
/js/plugin-customizer-init.js:
--------------------------------------------------------------------------------
1 | (function($){
2 | wp.customize( 'newsletter_title', function(value) {
3 | value.bind(function(to) {
4 | $( '#newsletter-title').html(to);
5 | });
6 | });
7 | wp.customize( 'newsletter_content', function(value) {
8 | value.bind(function(to) {
9 | $('#newsletter-content').html(to);
10 | });
11 | });
12 | }(jQuery));
13 |
--------------------------------------------------------------------------------
/plugin-customizer-demo.php:
--------------------------------------------------------------------------------
1 | addNamespace( 'PluginCustomizer', PLUGIN_CUSTOMIZER_DEMO_PATH . 'src' );
30 | $class_loader->register();
31 |
32 |
33 | class PluginCustomizerDemo extends PluginCustomizer\Plugin_Customizer implements PluginCustomizer\Plugin_Customizer_Interface {
34 |
35 | function __construct() {
36 | PluginCustomizer\Plugin_Customizer::init( array(
37 | 'name' => 'Customizer Demo', // name your plugin
38 | 'url' => plugins_url( '', __FILE__ ), // note, '' = url witout slash at the end of url
39 | 'path' => plugin_dir_path( __FILE__ ),
40 | ) );
41 | $this->add_admin_menus();
42 | }
43 |
44 | /**
45 | * Load default template
46 | * Optionally load separate templates for the customizer sections.
47 | *
48 | * @author soderlind
49 | * @version 1.1.0
50 | */
51 | public function plugin_customizer_add_templates() {
52 | /**
53 | * The default template used when opening the customizer
54 | * @var array
55 | */
56 | $default_url = array(
57 | 'url' => parent::template_url( 'newsletter.php' ), // translates to templates/newsletter.php
58 | );
59 | /**
60 | * Option, add a template to a section. key = section name, value = url to template.
61 | *
62 | * The last part, title and content in the exmple below, will translate to title.php
63 | * and content.php in the templates folder.
64 | */
65 | $section_urls = array(
66 | 'newsletter_title_section' => parent::template_url( 'title.php' ), // translates to templates/title.php
67 | 'newsletter_content_section' => parent::template_url( 'content.php' ), // translates to templates/content.php
68 | );
69 | parent::add_templates( $default_url, $section_urls );
70 | /**
71 | * If you don't have different templates per section, just load the default template
72 | */
73 | // parent::add_templates( $default_url );
74 | }
75 |
76 | /**
77 | * Load the preview script. The script is needed sice the transport is postmessage
78 | * @author soderlind
79 | * @version 1.0.0
80 | */
81 | public function plugin_customizer_previewer_postmessage_script() {
82 |
83 | $handle = 'plugin-customizer-demo-init';
84 | $src = plugins_url( 'js/plugin-customizer-init.js' , __FILE__ );
85 | $deps = array( 'customize-preview', 'jquery' );
86 | $version = PLUGIN_CUSTOMIZER_DEMO_VERSION;
87 | $in_footer = 1;
88 | wp_enqueue_script( $handle, $src, $deps, $version , $in_footer );
89 | }
90 |
91 |
92 | /**
93 | * Simple customizer demo. Saves the settings as options.
94 | */
95 |
96 | /**
97 | * Add sections.
98 | *
99 | * @author soderlind
100 | * @version 1.0.0
101 | * @param WP_Customize_Manager $wp_customize
102 | */
103 | public function customizer_plugin_sections( $wp_customize ) {
104 | global $wp_customize;
105 |
106 | $wp_customize->add_section(
107 | 'newsletter_title_section',
108 | array(
109 | 'title' => __( 'Title', 'plugin-customizer' ),
110 | 'description' => __( 'Customize Your Logo Section', 'plugin-customizer' ),
111 | 'priority' => 5,
112 | 'capability' => 'manage_options',
113 | )
114 | );
115 | $wp_customize->add_section(
116 | 'newsletter_content_section',
117 | array(
118 | 'title' => __( 'Content', 'plugin-customizer' ),
119 | 'description' => __( 'Customize newsletter content', 'plugin-customizer' ),
120 | 'priority' => 10,
121 | 'capability' => 'manage_options',
122 | )
123 | );
124 | return true;
125 | }
126 |
127 | /**
128 | * Add settings.
129 | *
130 | * @author soderlind
131 | * @version 1.0.0
132 | * @param WP_Customize_Manager $wp_customize
133 | */
134 | public function customizer_plugin_settings( $wp_customize ) {
135 | global $wp_customize;
136 |
137 | $wp_customize->add_setting(
138 | 'newsletter_title',
139 | array(
140 | 'type' => 'option',
141 | 'capability' => 'manage_options',
142 | 'transport' => 'postMessage',
143 | 'default' => __( 'The Wizard of Oz', 'plugin-customizer' ),
144 | )
145 | );
146 |
147 | $wp_customize->add_setting(
148 | 'newsletter_content',
149 | array(
150 | 'type' => 'option',
151 | 'capability' => 'manage_options',
152 | 'transport' => 'postMessage',
153 | 'default' => 'This was to be an eventful day for the travelers. They had hardly been walking an hour when they saw before them a great ditch that crossed the road and divided the forest as far as they could see on either side. It was a very wide ditch, and when they crept up to the edge and looked into it they could see it was also very deep, and there were many big, jagged rocks at the bottom. The sides were so steep that none of them could climb down, and for a moment it seemed that their journey must end. "What shall we do?" asked Dorothy despairingly. "I haven\'t the faintest idea," said the Tin Woodman, and the Lion shook his shaggy mane and looked thoughtful.', //esc_html( 'Nulla laoreet erat vitae aliquet tristique. Quisque quis suscipit enim, a elementum eros. Vestibulum quis lacus ligula. Mauris sit amet nibh tincidunt, gravida tortor ac, maximus nisi. Nunc turpis mauris, blandit vitae nibh non, blandit pharetra purus. Sed sed convallis diam. In ante nisi, pellentesque in laoreet at, fringilla ac neque.
Cras consequat eros lectus, ac dignissim justo cursus ac. In mi tortor, ornare eu quam a, ultrices tincidunt magna. Fusce non purus quis ex convallis vehicula. Aenean purus diam, vulputate vel pellentesque ultrices, tincidunt ac lectus. Nullam est purus, lobortis ac aliquam eget, egestas a diam. Praesent eget sapien vitae orci faucibus tempus. Ut sit amet lorem elit. Curabitur et vestibulum nibh.
Mauris vestibulum eget nisl sit amet gravida. Nullam in orci ut sem maximus dapibus blandit quis dolor. Sed pretium efficitur elit, eget vulputate sapien bibendum non. Proin congue posuere sagittis. Ut fermentum mauris ut gravida faucibus. Aenean a malesuada magna. Vestibulum nec viverra metus. Nunc aliquam eros orci, ut malesuada felis malesuada vitae. Phasellus vehicula non ex at scelerisque.
' ), 154 | ) 155 | ); 156 | return true; 157 | } 158 | 159 | /** 160 | * Add contronls. 161 | * 162 | * @author soderlind 163 | * @version 1.0.0 164 | * @param WP_Customize_Manager $wp_customize 165 | */ 166 | public function customizer_plugin_controls( $wp_customize ) { 167 | global $wp_customize; 168 | 169 | $wp_customize->add_control( new WP_Customize_Control( 170 | $wp_customize, 171 | 'newsletter_title', 172 | array( 173 | 'label' => __( 'Title', 'plugin-customizer' ), 174 | 'type' => 'text', 175 | 'section' => 'newsletter_title_section', 176 | 'settings' => 'newsletter_title', 177 | ) 178 | ) ); 179 | 180 | $wp_customize->add_control( new WP_Customize_Control( 181 | $wp_customize, 182 | 'newsletter_content', 183 | array( 184 | 'label' => __( 'Content', 'plugin-customizer' ), 185 | 'section' => 'newsletter_content_section', 186 | 'settings' => 'newsletter_content', 187 | 'type' => 'textarea', 188 | ) 189 | ) ); 190 | return true; 191 | } 192 | 193 | /** 194 | * Admin menus 195 | */ 196 | 197 | public function add_admin_menus() { 198 | /** 199 | * Add admin menu, You'll most likely only need one of them. 200 | */ 201 | 202 | // root menu 203 | add_action( 'admin_menu', array( $this, 'register_root_menu' ) ); 204 | add_action( 'admin_init', array( $this, 'root_menu_redirect_to_customizer' ) , 1 ); 205 | // submenu 206 | add_action( 'admin_menu', array( $this, 'register_sub_menu' ) ); 207 | // admin bar 208 | add_action( 'admin_bar_menu', array( $this, 'add_admin_bar_customizer_url' ), 500 ); 209 | // admin options page 210 | add_action( 'admin_menu', array( $this, 'add_option_page' ) ); 211 | add_action( 'admin_init', array( $this, 'settings_init' ) ); 212 | 213 | } 214 | 215 | /** 216 | * Create top level (root) menu. Will create URL with parameter page=redirect-customizer 217 | * 218 | * @author soderlind 219 | * @version 1.0.0 220 | */ 221 | public function register_root_menu() { 222 | add_menu_page( 223 | __( 'Plugin Customizer', 'plugin-customizer' ), 224 | __( 'Plugin Customizer', 'plugin-customizer' ), 225 | 'manage_options', 226 | 'redirect-customizer', 227 | 'function' 228 | ); 229 | } 230 | 231 | /** 232 | * Redirect to customizer url 233 | * 234 | * See http://wordpress.stackexchange.com/a/175574/14546 235 | * @author soderlind 236 | * @version 1.0.0 237 | */ 238 | function root_menu_redirect_to_customizer() { 239 | $menu_redirect = isset( $_GET['page'] ) ? $_GET['page'] : false; 240 | 241 | if ( 'redirect-customizer' == $menu_redirect ) { 242 | wp_safe_redirect( \PluginCustomizer\Plugin_Customizer::get_customizer_url( admin_url() ) ); 243 | exit(); 244 | } 245 | } 246 | 247 | /** 248 | * Create submenu 249 | * @author soderlind 250 | * @version 1.0.0 251 | */ 252 | public function register_sub_menu() { 253 | add_options_page( 254 | __( 'Plugin Customizer', 'plugin-customizer' ), 255 | __( 'Plugin Customizer', 'plugin-customizer' ), 256 | 'manage_options', 257 | 'plugin-template', 258 | '__return_null' 259 | ); 260 | $this->add_sub_menu_customizer_url(); 261 | } 262 | 263 | /** 264 | * Replace the 'plugin-template' string, in the submenu added by register_sub_menu(), 265 | * with the customizer url. 266 | * 267 | * See http://wordpress.stackexchange.com/a/131214/14546 268 | * 269 | * @author soderlind 270 | * @version 1.0.0 271 | */ 272 | function add_sub_menu_customizer_url( $parent = 'options-general.php' ) { 273 | global $submenu; 274 | 275 | if ( ! isset( $submenu[ $parent ] ) ) { 276 | return; 277 | } 278 | foreach ( $submenu[ $parent ] as $k => $d ) { 279 | if ( 'plugin-template' == $d['2'] ) { 280 | $submenu[ $parent ][ $k ]['2'] = \PluginCustomizer\Plugin_Customizer::get_customizer_url( $parent ); 281 | break; 282 | } 283 | } 284 | } 285 | 286 | /** 287 | * [add_admin_bar_customizer_url description] 288 | * @author soderlind 289 | * @version 1.0.0 290 | * @param [type] $wp_admin_bar [description] 291 | */ 292 | function add_admin_bar_customizer_url( $wp_admin_bar ) { 293 | global $post; 294 | if ( is_admin() ) { 295 | $return_url = $this->_get_current_admin_page_url(); 296 | } elseif ( is_object( $post ) ) { 297 | $return_url = get_permalink( $post->ID ); 298 | } else { 299 | $return_url = esc_url( home_url( '/' ) ); 300 | } 301 | 302 | $args = array( 303 | 'id' => 'plugin-customizer-link', 304 | 'title' => __( 'Plugin Customizer', 'plugin-customizer' ), 305 | 'href' => \PluginCustomizer\Plugin_Customizer::get_customizer_url( $return_url ), 306 | ); 307 | 308 | $wp_admin_bar->add_node( $args ); 309 | } 310 | 311 | /** 312 | * Find the current admin url. 313 | * 314 | * From: https://core.trac.wordpress.org/ticket/27888 315 | * 316 | * @author soderlind 317 | * @version 1.0.0 318 | * @return String|Bool The URL to the current admin page, or false if not in wp-admin. 319 | */ 320 | private function _get_current_admin_page_url() { 321 | if ( ! is_admin() ) { 322 | return false; 323 | } 324 | global $pagenow; 325 | 326 | $url = $pagenow; 327 | $query_string = $_SERVER['QUERY_STRING']; 328 | 329 | if ( ! empty( $query_string ) ) { 330 | $url .= '?' . $query_string; 331 | } 332 | return $url; 333 | } 334 | 335 | /** 336 | * Add an example option page. 337 | * @author soderlind 338 | * @version 1.0.0 339 | */ 340 | public function add_option_page() { 341 | add_menu_page( 'Plugin Customizer Options', 'Plugin Customizer Options', 'manage_options', 'plugin-customizer', array( $this, 'options_page' ) ); 342 | } 343 | 344 | public function settings_init() { 345 | register_setting( 'pluginPage', 'settings' ); 346 | add_settings_section( 'pluginPage_section', __( 'Demonstrate how to load the customizer from an option page', 'plugin-customizer' ), '', 'pluginPage' ); 347 | add_settings_field( 'option_page_customizer', __( 'Open customizer ', 'plugin-customizer' ), array( $this, 'option_page_customizer_link' ), 'pluginPage', 'pluginPage_section' ); 348 | } 349 | 350 | public function option_page_customizer_link() { 351 | printf( '%s%s
', 352 | \PluginCustomizer\Plugin_Customizer::get_customizer_url( 'admin.php?page=plugin-customizer', 'newsletter_title_section' ), __( 'Customize', 'plugin-customizer' ), 353 | __( 'Will use autofocus[section]=newletter_title to focus on the title (eg open it)', 'plugin-customizer' ) 354 | ); 355 | } 356 | 357 | public function options_page() { 358 | ?> 359 | 368 | Add New` 22 | 1. Search for `Plugin Customizer` 23 | 1. Install and Activate 24 | 25 | or 26 | 27 | 1. Download the plugin and extract the plugin-customizer.zip 28 | 1. Upload the extracted `plugin-customizer` folder to the `/wp-content/plugins/` directory 29 | 1. Activate the plugin through the 'Plugins' menu in WordPress 30 | 31 | The plugin is also [available at GitHub](https://github.com/soderlind/plugin-customizer) 32 | 33 | == Changelog == 34 | 35 | = 1.1.2 = 36 | * Initial release. 37 | -------------------------------------------------------------------------------- /src/Blank_Slate.php: -------------------------------------------------------------------------------- 1 | slug = $slug; 41 | $this->plugin_url = $plugin_url; 42 | $this->plugin_root = $plugin_root; 43 | add_filter( 'customize_loaded_components', function() { 44 | 45 | $priority = 1; 46 | add_action( 'wp_loaded', function() { 47 | 48 | global $wp_customize; 49 | remove_all_actions( 'customize_register' ); 50 | $wp_customize->register_panel_type( 'WP_Customize_Panel' ); 51 | $wp_customize->register_section_type( 'WP_Customize_Section' ); 52 | $wp_customize->register_section_type( 'WP_Customize_Sidebar_Section' ); 53 | $wp_customize->register_control_type( 'WP_Customize_Color_Control' ); 54 | $wp_customize->register_control_type( 'WP_Customize_Media_Control' ); 55 | $wp_customize->register_control_type( 'WP_Customize_Upload_Control' ); 56 | $wp_customize->register_control_type( 'WP_Customize_Image_Control' ); 57 | $wp_customize->register_control_type( 'WP_Customize_Background_Image_Control' ); 58 | $wp_customize->register_control_type( 'WP_Customize_Cropped_Image_Control' ); 59 | $wp_customize->register_control_type( 'WP_Customize_Site_Icon_Control' ); 60 | $wp_customize->register_control_type( 'WP_Customize_Theme_Control' ); 61 | }, $priority ); 62 | $components = array(); 63 | 64 | return $components; 65 | } ); 66 | add_action( 'customize_controls_init', function() { 67 | global $wp_customize; 68 | $wp_customize->set_preview_url( 69 | add_query_arg( 70 | array( $this->slug => 'on' ), 71 | $wp_customize->get_preview_url() 72 | ) 73 | ); 74 | } ); 75 | 76 | add_action( 'customize_controls_enqueue_scripts', function() { 77 | $handle = 'plugin-customizer-blank-slate'; 78 | $src = $this->plugin_url . 'assets/js/plugin-customizer-blank-slate.js'; 79 | $deps = array( 'customize-controls' ); 80 | $ver = false; 81 | $in_footer = true; 82 | wp_enqueue_script( $handle, $src, $deps, $ver, $in_footer ); 83 | 84 | $args = array( 85 | 'queryParamName' => $this->slug, 86 | 'queryParamValue' => 'on', 87 | ); 88 | wp_add_inline_script( 89 | $handle, 90 | sprintf( 'PluginCustomizerBlankSlate.init( %s );', wp_json_encode( $args ) ), 91 | 'after' 92 | ); 93 | } ); 94 | } 95 | } 96 | } 97 | -------------------------------------------------------------------------------- /src/Plugin_Customizer.php: -------------------------------------------------------------------------------- 1 | 'Plugin Customizer', 45 | 'url' => plugins_url( '', dirname( __FILE__ ) ), 46 | 'path' => plugin_dir_path( dirname( __FILE__ ) ), 47 | ) ); 48 | 49 | $this->slug = sanitize_title( $config['name'] , 'plugin-customizer' ); 50 | $this->plugin_name = $config['name']; 51 | $this->plugin_url = $config['url']; 52 | $this->plugin_root = $config['path']; 53 | $this->url = plugins_url( '/', __FILE__ ); 54 | $this->root = plugin_dir_path( __FILE__ ); 55 | 56 | /** 57 | * When saving the setinngs, the customizer settings must be visible for admin-ajax.php 58 | * so add it before the bailout test. 59 | */ 60 | add_action( 'wp_loaded', function() { 61 | add_action( 'customize_register', array( $this, 'customizer_plugin_settings' ) ); 62 | }, $this->customize_register_priority ); 63 | /** 64 | * Bailout if not called from the plugin menu links. 65 | */ 66 | if ( ! isset( $_GET[ $this->slug ] ) || 'on' !== wp_unslash( $_GET[ $this->slug ] ) ) { 67 | return; 68 | } 69 | /** 70 | * Set the customizer title. 71 | */ 72 | add_filter( 'pre_option_blogname', function(){ 73 | return $this->plugin_name; 74 | } ); 75 | 76 | /** 77 | * WordPres Customizer is dependant on functionality in the theme. Just in case 78 | * the current theme doesn't support WordPress Customizer we'll use a theme 79 | * that supports it. 80 | */ 81 | add_action( 'setup_theme', function() { 82 | add_filter( 'theme_root', array( $this, 'switch_theme_root_path' ) ); 83 | add_filter( 'template_directory_uri', array( $this, 'switch_template_uri' ) ); 84 | add_filter( 'stylesheet_uri', array( $this, 'switch_template_uri' ) ); 85 | add_filter( 'pre_option_stylesheet', function(){ 86 | return $this->theme_name; 87 | } ); 88 | add_filter( 'pre_option_template', function(){ 89 | return $this->theme_name; 90 | } ); 91 | } ); 92 | /** 93 | * Remove all other panels and sections from the customizer. 94 | */ 95 | $blank_slate = Blank_Slate::instance(); 96 | $blank_slate->init( $this->slug, $this->url, $this->root ); 97 | 98 | /** 99 | * Create preview template permalink rules. 100 | * Also see plugin_customizer_configure_previewer(), template_loader() and js/plugin-customizer-preview-templates.js 101 | * 102 | * A 'how to create permalink' tutorial is at https://soderlind.no/wordpress-plugins-and-permalinks-how-to-use-pretty-links-in-your-plugin/ 103 | */ 104 | add_filter( 'generate_rewrite_rules', array( $this, 'rewrite_rule' ) ); 105 | add_filter( 'query_vars', array( $this, 'query_vars' ) ); 106 | add_filter( 'admin_init', array( $this, 'flush_rewrite_rules' ) ); 107 | 108 | /** 109 | * Parse request from js/plugin-customizer-preview-templates.js previewer script and load the template. 110 | */ 111 | add_action( 'parse_request', array( $this, 'template_loader' ) ); 112 | 113 | /** 114 | * Enqueue previewer script. 115 | * 116 | * See https://make.xwp.co/2016/07/21/navigating-to-a-url-in-the-customizer-preview-when-a-section-is-expanded/ 117 | */ 118 | add_action( 'customize_controls_enqueue_scripts', array( $this, 'plugin_customizer_configure_previewer' ) ); 119 | add_action( 'customize_controls_enqueue_scripts', array( $this, 'plugin_customizer_add_templates' ), 11 ); 120 | 121 | /** 122 | * The plugin is using transport => postMessage, set in customizer_plugin_settings(), and needs 123 | * javascript to update the preview. 124 | * 125 | * You can Learn more about postmessage at: 126 | * https://developer.wordpress.org/themes/advanced-topics/customizer-api/#using-postmessage-for-improved-setting-previewing 127 | */ 128 | add_action( 'customize_preview_init', array( $this, 'plugin_customizer_previewer_postmessage_script' ) ); 129 | /** 130 | * Register plugin customizer settings. 131 | */ 132 | add_action( 'wp_loaded', function() { 133 | add_action( 'customize_register', array( $this, 'customizer_plugin_sections' ) ); 134 | add_action( 'customize_register', array( $this, 'customizer_plugin_controls' ) ); 135 | 136 | /** 137 | * If you plan to use selective refresh, set the transport in customizer_plugin_settings() 138 | * to 'refresh' and uncomment the line below. Also comment out the customize_preview_init action above. 139 | * 140 | * You can learn more about selective refresh at: 141 | * https://make.wordpress.org/core/2016/02/16/selective-refresh-in-the-customizer/ 142 | */ 143 | // add_action( 'customize_register', array( $this, 'customizer_plugin_selective_refresh' ) ); 144 | }, $this->customize_register_priority ); 145 | 146 | } 147 | 148 | /** 149 | * Create rewrite rule for the template URL used by js/plugin-cusomizer-scripts.js 150 | * 151 | * See: https://soderlind.no/wordpress-plugins-and-permalinks-how-to-use-pretty-links-in-your-plugin/ 152 | * 153 | * @author soderlind 154 | * @version 1.0.0 155 | * @param Object $wp_rewrite Permalink structure 156 | * @return Array Rewrite rules 157 | */ 158 | function rewrite_rule( $wp_rewrite ) { 159 | $new_rules = array( 160 | sprintf( '%s/templates/(.*)$', $this->slug ) => sprintf( 'index.php?plugin-customizer-template-%s=%s', $this->slug, $wp_rewrite->preg_index( 1 ) ), 161 | ); 162 | 163 | $wp_rewrite->rules = $new_rules + $wp_rewrite->rules; 164 | return $wp_rewrite->rules; 165 | } 166 | 167 | /** 168 | * Add query variable for the rewrite rule used by the template URL 169 | * 170 | * See: https://soderlind.no/wordpress-plugins-and-permalinks-how-to-use-pretty-links-in-your-plugin/ 171 | * 172 | * @author soderlind 173 | * @version 1.0.0 174 | * @param Array $query_vars All defined query variables. 175 | * @return Array The updated array with query variables. 176 | */ 177 | function query_vars( $query_vars ) { 178 | $query_vars[] = sprintf( 'plugin-customizer-template-%s', $this->slug ); 179 | return $query_vars; 180 | } 181 | 182 | /** 183 | * Flush the permalink structure. 184 | * 185 | * See: https://soderlind.no/wordpress-plugins-and-permalinks-how-to-use-pretty-links-in-your-plugin/ 186 | * 187 | * @author soderlind 188 | * @version 1.0.0 189 | */ 190 | function flush_rewrite_rules() { 191 | $rules = $GLOBALS['wp_rewrite']->wp_rewrite_rules(); 192 | if ( ! isset( $rules[ sprintf( '%s/templates/(.*)$', $this->slug ) ] ) ) { // must be the same rule as in rewrite_rule($wp_rewrite) 193 | global $wp_rewrite; 194 | $wp_rewrite->flush_rules(); 195 | } 196 | } 197 | 198 | /** 199 | * Create the preview. 200 | * 201 | * The WordPress customizer uses ajax to communicate with the preview. To load the needed 202 | * scripts, wp_head() and wp_footer() must be added to the template. 203 | * 204 | * @author soderlind 205 | * @version 1.0.0 206 | */ 207 | function template_loader( $wp_query ) { 208 | $key = sprintf( 'plugin-customizer-template-%s', $this->slug ); 209 | if ( isset( $wp_query->query_vars[ $key ] ) ) { // same as the first custom variable in query_vars( $query_vars ) 210 | $template = $wp_query->query_vars[ $key ] . '.php'; 211 | wp_head(); 212 | $this->_load_template( $template ); 213 | wp_footer(); 214 | 215 | exit( 0 ); 216 | } 217 | } 218 | 219 | /** 220 | * Load the themplate and display the template if found 221 | * 222 | * Will try to locate the template in this order: 223 | * 1) [child-theme]/plugin-customizer/ 224 | * 2) [parent-theme]/plugin-customizer/ 225 | * 3) [plugin directory]/templates/ 226 | * 227 | * @author soderlind 228 | * @version 1.0.0 229 | * @param string $template plugin_root to the template 230 | */ 231 | private function _load_template( $template ) { 232 | // from: https://developer.wordpress.org/reference/functions/load_template/#comment-727 233 | if ( $overridden_template = locate_template( "plugin-customizer/{$template}" ) ) { 234 | /* 235 | * locate_template() returns plugin_root to file. 236 | * if either the child theme or the parent theme have overridden the template, load it. 237 | */ 238 | load_template( $overridden_template ); 239 | } else { 240 | /* 241 | * If neither the child nor parent theme have overridden the template, 242 | * we load the template from the 'templates' sub-directory of the directory this file is in. 243 | */ 244 | load_template( $this->plugin_root . "templates/{$template}" ); 245 | } 246 | } 247 | /** 248 | * Load the previewer script and pass the template URL as argument to the script. 249 | * Optionally load separate templates for the customizer sections. 250 | * 251 | * @author soderlind 252 | * @version 1.0.0 253 | */ 254 | public function plugin_customizer_configure_previewer() { 255 | $src = $this->url . 'assets/js/plugin-customizer-preview-templates.js'; 256 | $deps = array( 'customize-controls' ); 257 | $version = PLUGIN_CUSTOMIZER_VERSION; 258 | $in_footer = 1; 259 | wp_enqueue_script( $this->slug, $src, $deps, $version , $in_footer ); 260 | } 261 | 262 | abstract public function plugin_customizer_add_templates(); 263 | 264 | public function template_url( $template ) { 265 | $template = basename( $template, '.php' ); 266 | $template_url = home_url( sprintf( '%s/templates/%s/?%s=on', $this->slug, $template, $this->slug ) ); 267 | 268 | return $template_url; 269 | } 270 | 271 | public function add_templates( $default_url, $section_urls = array() ) { 272 | wp_add_inline_script( 273 | $this->slug, 274 | sprintf( 'PluginCustomizer.init( %s, %s );', 275 | wp_json_encode( $default_url ), 276 | wp_json_encode( $section_urls ) 277 | ), 278 | 'after' 279 | ); 280 | } 281 | 282 | /** 283 | * Load the preview script. The script is needed sice the transport is postmessage 284 | * @author soderlind 285 | * @version 1.0.0 286 | */ 287 | abstract public function plugin_customizer_previewer_postmessage_script(); 288 | 289 | /** 290 | * Create the customizer URL. 291 | * 292 | * @author soderlind 293 | * @version 1.0.0 294 | * @param string $return_url The URL to return to when closing the customizer. 295 | * @param string $autofocus_section Used for deep-linking, i.e. this section will be selected 296 | * when the customizer is opened. 297 | * @return string The customizer URL. 298 | */ 299 | protected function get_customizer_url( $return_url = '', $autofocus_section = '' ) { 300 | // If no return url, set the return url to the main admin url. 301 | if ( '' == $return_url ) { 302 | $return_url = admin_url(); 303 | } 304 | $url = wp_customize_url(); 305 | // Add parameter to identify this as a customizer url for this plugin. 306 | $url = add_query_arg( $this->slug , 'on', $url ); 307 | // If autofocus, add parameter to url. 308 | if ( '' !== $autofocus_section ) { 309 | $url = add_query_arg( 'autofocus[section]', $autofocus_section, $url ); 310 | } 311 | //Add parameter for return url. 312 | $url = add_query_arg( 'return', urlencode( $return_url ), $url ); 313 | //Sanitize url. 314 | $url = esc_url_raw( $url ); 315 | return $url; 316 | } 317 | 318 | 319 | abstract public function customizer_plugin_sections( $wp_customize ); 320 | abstract public function customizer_plugin_settings( $wp_customize ); 321 | abstract public function customizer_plugin_controls( $wp_customize ); 322 | 323 | // inspired by https://gist.github.com/franz-josef-kaiser/8608140 324 | public function switch_theme_root_path( $org_theme_root ) { 325 | $crrent_theme = wp_get_theme( $this->theme_name ); 326 | // if theme exists, no point in changing theme root. 327 | if ( $crrent_theme->exists() ) { 328 | return $org_theme_root; 329 | } 330 | 331 | $new_theme_root = $this->root . 'assets'; 332 | # Too early to use register_theme_directory() 333 | if ( ! in_array( $new_theme_root, $GLOBALS['wp_theme_directories'] ) ) { 334 | $GLOBALS['wp_theme_directories'][] = $new_theme_root; 335 | } 336 | 337 | return $new_theme_root; 338 | } 339 | 340 | public function switch_template_uri( $uri ) { 341 | $new_theme_root_uri = $this->url . 'assets/' . $this->theme_name; 342 | return $new_theme_root_uri; 343 | } 344 | 345 | public function plugin_theme_name() { 346 | return $this->theme_name; 347 | } 348 | } 349 | } 350 | -------------------------------------------------------------------------------- /src/Plugin_Customizer_Interface.php: -------------------------------------------------------------------------------- 1 | 11 | 12 |
27 | 47 |
48 | 49 | 50 | 51 |52 | 'ol', 55 | 'short_ping' => true, 56 | 'avatar_size' => 42, 57 | ) ); 58 | ?> 59 |
60 | 61 | 62 | 63 | 64 | 65 | 69 | 70 | 71 | 72 | '', 75 | 'title_reply_after' => '
', 76 | ) ); 77 | ?> 78 | 79 |