From 56bddb65ee0f3bf39355fb06a1ddac31fd0e4d3a Mon Sep 17 00:00:00 2001 From: Ralf Hortt Date: Thu, 24 Jan 2019 22:38:29 +0100 Subject: [PATCH 1/4] Draft --- .gitignore | 1 + composer.json | 16 ++ src/Customizer.php | 378 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 395 insertions(+) create mode 100644 .gitignore create mode 100644 composer.json create mode 100644 src/Customizer.php diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..57872d0 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +/vendor/ diff --git a/composer.json b/composer.json new file mode 100644 index 0000000..27ec85f --- /dev/null +++ b/composer.json @@ -0,0 +1,16 @@ +{ + "name": "horttcore/wp-customizer", + "description": "A helper package for working with the WordPress Customizer", + "license": "MIT", + "authors": [ + { + "name": "Ralf Hortt", + "email": "me@horttcore.de" + } + ], + "autoload": { + "psr-4": { + "Horttcore\\Customizer\\": "src/" + } + } +} diff --git a/src/Customizer.php b/src/Customizer.php new file mode 100644 index 0000000..4ad9c1f --- /dev/null +++ b/src/Customizer.php @@ -0,0 +1,378 @@ + '', + // Optional. Specifies the TYPE of setting this is. Options are 'option' or 'theme_mod' (defaults to 'theme_mod') + 'type' => '', + // Optional. You can define a capability a user must have to modify this setting. Default if not specified: edit_theme_options + 'capability' => '', + // Optional. This can be used to hide a setting if the theme lacks support for a specific feature (using add_theme_support). + 'theme_supports' => '', + // Optional. This can be either 'refresh' (default) or 'postMessage'. Only set this to 'postMessage' if you are writing custom Javascript to control the Theme Customizer's live preview. + 'transport' => '', + // Optional. A function name to call for sanitizing the input value for this setting. The function should be of the form of a standard filter function, where it accepts the input data and returns the sanitized data. + 'sanitize_callback' => '', + // Optional. A function name to call for sanitizing the value for this setting for the purposes of outputting to javascript code. The function should be of the form of a standard filter function, where it accepts the input data and returns the sanitized data. This is only necessary if the data to be sent to the customizer window has a special form. + 'sanitize_js_callback' => '', + ]; + + $controlDefaults = [ + // Optional. Displayed label. Example: 'label' => __( 'Base Color Scheme', 'twentyfifteen' ), + 'label' => $name, + // Optional. + 'description' => '', + // Any readily available or user defined section. Some available sections: themes, title_tagline, colors, header_image (only when enabled), background_image (only when enabled), static_front_page. + 'section' => $this->getCurrentSectionId(), + // Optional. + 'priority' => '', + // Supported types include: text, checkbox, radio, select, textarea, dropdown-pages, email, url, number, hidden, and date. + 'type' => '', + // Optional. If in https://codex.wordpress.org/Class_Reference/WP_Customize_Manager/add_setting you specified "theme_mod" type then you should add here ID of the database setting which you want to modify, e.g. "header_color" (which is your arbitrary name specific to your theme only). It will be stored as a serialized value obtainable with https://codex.wordpress.org/Function_Reference/get_theme_mod like get_theme_mod('header_color');. If you selected "option" type in https://codex.wordpress.org/Class_Reference/WP_Customize_Manager/add_setting then you can add here a plain word like "theme_name_header_color" which will be obtainable with get_option('theme_name_header_color');. Serialized values like "my_namespace[header_color]" are allowed in both cases, however you probably don't need to serialize it when using "theme_mod" as it's already stored in the database as a serialized entry. If not defined, then the $identifier as the setting ID is used. + 'settings' => '', + // Optional. Allows you to add attributes to the input. This extends beyond just using min, max, and step for number and range, to the ability to add custom classes, placeholders, the pattern attribute, and anything else you need to the input element. These are available only for some control types. Example for "number" and "range" controls: 'input_attrs' => array( 'min' => 0, 'max' => 10, 'step' => 2 ) + 'input_attrs' => [], + ]; + + $setting = array_filter( wp_parse_args( $setting, $settingDefaults ) ); + $control = array_filter( wp_parse_args( $control, $controlDefaults ) ); + + $this->settings[$this->getCurrentSectionId()][$identifier]['setting'] = $setting; + $this->settings[$this->getCurrentSectionId()][$identifier]['control'] = $control; + $this->settings[$this->getCurrentSectionId()][$identifier]['renderer'] = $renderer; + + return $this; + } + + + /** + * Register a checkbox control in the customizer + * + * @param string $identifier Identifier + * @param string $label Settings label + * @param array $setting Settings args - https://codex.wordpress.org/Class_Reference/WP_Customize_Manager/add_setting + * @param array $control Control args - https://codex.wordpress.org/Class_Reference/WP_Customize_Manager/add_control + * @return Settings $this for chaining + */ + public function checkbox( string $identifier, string $label, array $setting = [], array $control = [] ) + { + $control['type'] = 'checkbox'; + return $this->add( $identifier, $label, $setting, $control, 'WP_Customize_Control' ); + } + + + /** + * Register a color control in the customizer + * + * @param string $label Settings label + * @param array $setting Settings args - https://codex.wordpress.org/Class_Reference/WP_Customize_Manager/add_setting + * @param array $control Control args - https://codex.wordpress.org/Class_Reference/WP_Customize_Manager/add_control + * @param string $identifier Identifier + * @return Settings $this for chaining + */ + public function color( string $identifier, string $label, array $setting = [], array $control = [] ) + { + return $this->add( $identifier, $label, $setting, $control, '\WP_Customize_Color_Control' ); + } + + + /** + * Get current panel id + * + * @return string + **/ + public function getCurrentPanelId() + { + end( $this->panels ); + return key( $this->panels ); + } + + + /** + * Get current section id + * + * @return string + **/ + public function getCurrentSectionId() + { + end( $this->sections ); + return key( $this->sections ); + } + + + /** + * Register a file control in the customizer + * + * @param string $label Settings label + * @param array $setting Settings args - https://codex.wordpress.org/Class_Reference/WP_Customize_Manager/add_setting + * @param array $control Control args - https://codex.wordpress.org/Class_Reference/WP_Customize_Manager/add_control + * @param string $identifier Identifier + * @return Settings $this for chaining + */ + public function file( string $identifier, string $label, array $setting = [], array $control = [] ) + { + return $this->add( $identifier, $label, $setting, $control, '\WP_Customize_Upload_Control' ); + } + + + /** + * Register a image control in the customizer + * + * @param string $identifier Identifier + * @param string $label Settings label + * @param array $setting Settings args - https://codex.wordpress.org/Class_Reference/WP_Customize_Manager/add_setting + * @param array $control Control args - https://codex.wordpress.org/Class_Reference/WP_Customize_Manager/add_control + * @return Settings $this for chaining + */ + public function image( string $identifier, string $label, array $setting = [], array $control = [] ) + { + return $this->add( $identifier, $label, $setting, $control, '\WP_Customize_Image_Control' ); + } + + + /** + * Init settings in the customizer + * + * @param WP_Customizer $customizer Customizer instance + * @return void + */ + public function init( WP_Customizer $customizer ) + { + + foreach ( $this->panels as $panelId => $panel ) : + + $customizer->add_panel( $panelId, $panel); + + foreach ( $panel['sections'] as $sectionId => $section ) : + + $customizer->add_section( $identifier, $section ); + + foreach ( $section['settings'] as $identifier => $config ) : + + $customizer->add_setting( $identifier, $config['setting'] ); + + if ( $config['renderer'] ) : + $customizer->add_control( new $config['renderer']( + $customizer, + $identifier, + $config['control'] + ) ); + continue; + endif; + + $customizer->add_control( $identifier, $config['control'] ); + + endforeach; + + endforeach; + + endforeach; + + } + + + /** + * Register + * + * @return void + */ + public function register() + { + add_action( 'customize_register', [$this, 'register'] ); + } + + + /** + * Url field + * + * @param string $label Settings label + * @param array $setting Settings args - https://codex.wordpress.org/Class_Reference/WP_Customize_Manager/add_setting + * @param array $control Control args - https://codex.wordpress.org/Class_Reference/WP_Customize_Manager/add_control + * @return Settings $this for chaining + */ + public function page( string $identifier, $label, array $setting = [], array $control = [] ) + { + $setting['sanitize_callback'] = 'absint'; + $control['type'] = 'dropdown-pages'; + return $this->text( $identifier, $label, $setting, $control ); + } + + + /** + * Panel + * + * @param string $label Panel label + * @param array $args Panel args - https://developer.wordpress.org/reference/classes/wp_customize_manager/add_panel/ + * + * @return Manager + **/ + public function panel(string $label, $args) + { + $identifier = sanitize_title( $label ); + $this->panels[$identifier]['title'] = $label; + $this->panels[$identifier]['priority'] = 200; + $this->panels[$identifier]['sections'] = []; + $this->panels[$identifier] = array_merge($this->panels[$identifier], $args); + + return $this; + } + + + /** + * Register a radiobutton control in the customizer + * + * @param string $identifier Identifier + * @param string $label Settings label + * @param array $choices Radio choices, Format: ['value' => 'label'] + * @param array $setting Settings args - https://codex.wordpress.org/Class_Reference/WP_Customize_Manager/add_setting + * @param array $control Control args - https://codex.wordpress.org/Class_Reference/WP_Customize_Manager/add_control + * @return Settings $this for chaining + */ + public function radio( string $identifier, string $label, array $choices = [], array $setting = [], array $control = [] ) + { + $control['type'] = 'radio'; + $control['choices'] = $choices; + + return $this->add( $identifier, $label, $setting, $control, 'WP_Customize_Control' ); + } + + + /** + * Panel + * + * @param string $name A unique slug-like string to use as an id. + * @param array $args - https://developer.wordpress.org/reference/classes/wp_customize_manager/add_section/ + * @return Manger $this for chaining + **/ + public function section( string $label, $args = [] ) + { + $identifier = sanitize_title( $label ); + $args['title'] = $label; + $this->panels[$this->getCurrentPanelId()]['sections'][$identifier] = $args; + + return $this; + } + + + /** + * Register a selectbox control in the customizer + * + * @param string $identifier Identifier + * @param string $label Settings label + * @param array $choices Select options, Format: ['value' => 'label'] + * @param array $setting Settings args - https://codex.wordpress.org/Class_Reference/WP_Customize_Manager/add_setting + * @param array $control Control args - https://codex.wordpress.org/Class_Reference/WP_Customize_Manager/add_control + * @return Settings $this for chaining + */ + public function select( string $identifier, string $label, array $choices = [], array $setting = [], array $control = [] ) + { + $control['type'] = 'select'; + $control['choices'] = $choices; + return $this->add( $identifier, $label, $setting, $control, 'WP_Customize_Control' ); + } + + + /** + * Register a text control in the customizer + * + * @param string $identifier Identifier + * @param string $label Settings label + * @param array $setting Settings args - https://codex.wordpress.org/Class_Reference/WP_Customize_Manager/add_setting + * @param array $control Control args - https://codex.wordpress.org/Class_Reference/WP_Customize_Manager/add_control + * @return Settings $this for chaining + */ + public function text( string $identifier, string $label, array $setting = [], array $control = [] ) + { + return $this->add( $identifier, $label, $setting, $control, 'WP_Customize_Control' ); + } + + + /** + * Register a text control in the customizer + * + * @param string $label Settings label + * @param array $setting Settings args - https://codex.wordpress.org/Class_Reference/WP_Customize_Manager/add_setting + * @param array $control Control args - https://codex.wordpress.org/Class_Reference/WP_Customize_Manager/add_control + * @param string $identifier Identifier + * @return Settings $this for chaining + */ + public function textarea( string $identifier, string $label, array $setting = [], array $control = [] ) + { + $setting['sanitize_callback'] = 'wp_kses_post'; + $control['type'] = 'textarea'; + return $this->text( $identifier, $label, $setting, $control ); + } + + + /** + * Url field + * + * @param string $label Settings label + * @param array $setting Settings args - https://codex.wordpress.org/Class_Reference/WP_Customize_Manager/add_setting + * @param array $control Control args - https://codex.wordpress.org/Class_Reference/WP_Customize_Manager/add_control + * @return Settings $this for chaining + */ + public function url( string $identifier, $label, array $setting = [], array $control = [] ) + { + $setting['sanitize_callback'] = 'esc_url_raw'; + $control['type'] = 'url'; + return $this->text( $identifier, $label, $setting, $control ); + } + + +} From 985461a3834b67b5e50026b507e42aaadfb44691 Mon Sep 17 00:00:00 2001 From: Ralf Hortt Date: Sat, 26 Jan 2019 23:38:11 +0100 Subject: [PATCH 2/4] RC --- .gitignore | 1 + README.md | 25 ++++++----- composer.json | 1 + src/{Customizer.php => Manager.php} | 64 ++++++++++++++++++----------- 4 files changed, 55 insertions(+), 36 deletions(-) rename src/{Customizer.php => Manager.php} (90%) diff --git a/.gitignore b/.gitignore index 57872d0..58f394d 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ /vendor/ +.DS_Store diff --git a/README.md b/README.md index 870e5d2..4544199 100644 --- a/README.md +++ b/README.md @@ -14,19 +14,18 @@ A helper package for working with the WordPress Customizer use Horttcore\Customizer\Manager; (new Manager) - ->panel( $panelLabel ) - ->section( $sectionLabel ) - ->checkbox( $optionLabel, $optionName ) - ->color( $optionLabel, $optionName ) - ->file( $optionLabel, $optionName ) - ->image( $optionLabel, $optionName ) - ->page( $optionLabel, $optionName ) - ->radio( $optionLabel, $optionName, ['option1' => 'Option 1', 'option2' => 'Option 2'] ); - ->select( $optionLabel, $optionName, ['option1' => 'Option 1', 'option2' => 'Option 2'] ); - ->text( $optionLabel, $optionName ) - ->textarea( $optionLabel, $optionName ) - ->url( $optionLabel, $optionName ) - ->init(); // Required + ->panel( 'My Panel' ) + ->section( 'My Section' ) + ->checkbox( 'my-checkbox', 'Checkbox' ) + ->color( 'my-color', 'Color' ) + ->file( 'my-file', 'File' ) + ->image( 'my-image', 'Image' ) + ->page( 'my-page', 'Page' ) + ->radio( 'my-radio', 'Radio', ['option1' => 'Option 1', 'option2' => 'Option 2'] ); + ->select( 'my-select', 'Select', ['option1' => 'Option 1', 'option2' => 'Option 2'] ); + ->text( 'my-text', 'Text' ) + ->textarea( 'my-textarea', 'Textare' ) + ->url( 'my-url', 'Url' ) ``` ## Changelog diff --git a/composer.json b/composer.json index 27ec85f..2cb4fb0 100644 --- a/composer.json +++ b/composer.json @@ -2,6 +2,7 @@ "name": "horttcore/wp-customizer", "description": "A helper package for working with the WordPress Customizer", "license": "MIT", + "version": "1", "authors": [ { "name": "Ralf Hortt", diff --git a/src/Customizer.php b/src/Manager.php similarity index 90% rename from src/Customizer.php rename to src/Manager.php index 4ad9c1f..bfff8dd 100644 --- a/src/Customizer.php +++ b/src/Manager.php @@ -18,28 +18,44 @@ class Manager { + /** - * Panels + * Construct * - * @var array + * @param bool $autoInit + * @return Manager + **/ + public function __construct(bool $autoInit = TRUE ) + { + if ( !$autoInit ) + return; + + $this->register(); + } + + + /** + * Current panel id + * + * @var string */ - protected $panels = []; + protected $currentPanelId = ''; /** - * Settings + * Current section id * - * @var array + * @var string */ - protected $sections = []; + protected $currentSectionId = ''; /** - * Settings + * Panels * * @var array */ - protected $settings = []; + protected $panels = []; /** @@ -92,9 +108,9 @@ public function add( string $identifier, string $name, array $setting, array $co $setting = array_filter( wp_parse_args( $setting, $settingDefaults ) ); $control = array_filter( wp_parse_args( $control, $controlDefaults ) ); - $this->settings[$this->getCurrentSectionId()][$identifier]['setting'] = $setting; - $this->settings[$this->getCurrentSectionId()][$identifier]['control'] = $control; - $this->settings[$this->getCurrentSectionId()][$identifier]['renderer'] = $renderer; + $this->panels[$this->getCurrentPanelId()]['sections'][$this->getCurrentSectionId()]['fields'][$identifier]['setting'] = $setting; + $this->panels[$this->getCurrentPanelId()]['sections'][$this->getCurrentSectionId()]['fields'][$identifier]['control'] = $control; + $this->panels[$this->getCurrentPanelId()]['sections'][$this->getCurrentSectionId()]['fields'][$identifier]['renderer'] = $renderer; return $this; } @@ -138,8 +154,7 @@ public function color( string $identifier, string $label, array $setting = [], a **/ public function getCurrentPanelId() { - end( $this->panels ); - return key( $this->panels ); + return $this->currentPanelId; } @@ -150,8 +165,7 @@ public function getCurrentPanelId() **/ public function getCurrentSectionId() { - end( $this->sections ); - return key( $this->sections ); + return $this->currentSectionId; } @@ -191,7 +205,7 @@ public function image( string $identifier, string $label, array $setting = [], a * @param WP_Customizer $customizer Customizer instance * @return void */ - public function init( WP_Customizer $customizer ) + public function init( \WP_Customize_Manager $customizer ) { foreach ( $this->panels as $panelId => $panel ) : @@ -200,16 +214,16 @@ public function init( WP_Customizer $customizer ) foreach ( $panel['sections'] as $sectionId => $section ) : - $customizer->add_section( $identifier, $section ); + $customizer->add_section( $sectionId, $section ); - foreach ( $section['settings'] as $identifier => $config ) : + foreach ( $section['fields'] as $field => $config ) : - $customizer->add_setting( $identifier, $config['setting'] ); + $customizer->add_setting( $field, $config['setting'] ); if ( $config['renderer'] ) : $customizer->add_control( new $config['renderer']( $customizer, - $identifier, + $field, $config['control'] ) ); continue; @@ -233,7 +247,7 @@ public function init( WP_Customizer $customizer ) */ public function register() { - add_action( 'customize_register', [$this, 'register'] ); + add_action( 'customize_register', [$this, 'init'] ); } @@ -261,14 +275,15 @@ public function page( string $identifier, $label, array $setting = [], array $co * * @return Manager **/ - public function panel(string $label, $args) + public function panel(string $label, array $args = []): Manager { $identifier = sanitize_title( $label ); + $this->currentPanelId = $identifier; + $this->panels[$identifier]['title'] = $label; $this->panels[$identifier]['priority'] = 200; $this->panels[$identifier]['sections'] = []; $this->panels[$identifier] = array_merge($this->panels[$identifier], $args); - return $this; } @@ -302,7 +317,10 @@ public function radio( string $identifier, string $label, array $choices = [], a public function section( string $label, $args = [] ) { $identifier = sanitize_title( $label ); + $this->currentSectionId = $identifier; + $args['title'] = $label; + $args['panel'] = $this->getCurrentPanelId(); $this->panels[$this->getCurrentPanelId()]['sections'][$identifier] = $args; return $this; From 9435db0e40d3ff2b437b530069588892f4db26a2 Mon Sep 17 00:00:00 2001 From: Ralf Hortt Date: Sat, 26 Jan 2019 23:40:33 +0100 Subject: [PATCH 3/4] Remove version from composer --- composer.json | 1 - 1 file changed, 1 deletion(-) diff --git a/composer.json b/composer.json index 2cb4fb0..27ec85f 100644 --- a/composer.json +++ b/composer.json @@ -2,7 +2,6 @@ "name": "horttcore/wp-customizer", "description": "A helper package for working with the WordPress Customizer", "license": "MIT", - "version": "1", "authors": [ { "name": "Ralf Hortt", From c2bfb0a4aeb8280fe0c004cdb76ab56458ca89ac Mon Sep 17 00:00:00 2001 From: Ralf Hortt Date: Sun, 27 Jan 2019 00:18:09 +0100 Subject: [PATCH 4/4] Update docs --- README.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 4544199..b6d3a04 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,9 @@ A helper package for working with the WordPress Customizer ### Basics +#### Configuration ```php +radio( 'my-radio', 'Radio', ['option1' => 'Option 1', 'option2' => 'Option 2'] ); ->select( 'my-select', 'Select', ['option1' => 'Option 1', 'option2' => 'Option 2'] ); ->text( 'my-text', 'Text' ) - ->textarea( 'my-textarea', 'Textare' ) - ->url( 'my-url', 'Url' ) + ->textarea( 'my-textarea', 'Textarea' ) + ->url( 'my-url', 'Url' ); +``` + +#### Retrieving data +```php +