of 113/113
Discovering the capabilities of the Theme Customizer API Tomasz Dziuda WordCamp Praha 2015

WordCamp Praga 2015

  • View
    1.070

  • Download
    0

Embed Size (px)

Text of WordCamp Praga 2015

  • Discovering the capabilities of the Theme Customizer API

    Tomasz Dziuda

    WordCamp Praha 2015

  • Ahoj!

  • Tomasz Dziuda

    Lead Developer @

    Co-organizer of WordCamp Poland 2014

    Twitter: @dziudek

    http://dziudek.pl -> https://www.gavick.com/blog

    Mail: [email protected]

    http://dziudek.plhttps://www.gavick.com/blogmailto:[email protected]?subject=
  • Why's it worth using the Theme Customizer?

  • Live preview for setting changes

  • Easy theme-option implementation

  • Test configuration options easily without affecting the live website

  • A user doesnt have to learn how to use the theme settings page

  • 4 practical bits of advice from me to you

  • As the number of options grows, the potential number of users requesting assistance will grow exponentially too

    1

    0Number of options

  • Giving a user full control over colors, in most cases, ends with dramatic results

  • The Dashboard will accept everything, but the user won't

  • Solutions implemented in the official APIs generally work better

  • How does it work?

  • refreshor

    JavaScript data binding

  • is_preview()

    refreshor

    JavaScript data binding

  • is_preview()wp_head

    refreshor

    JavaScript data binding

  • is_preview()

    customize_register

    wp_head

    refreshor

    JavaScript data binding

  • is_preview()

    customize_register

    wp_head

    customize_preview_init

    refreshor

    JavaScript data binding

  • is_preview()

    customize_register

    wp_head

    customize_preview_init

    customize_controls_enqueue_scripts

    refreshor

    JavaScript data binding

  • Customize Manager

  • Customize Manager

    Panel

  • Customize Manager

    Panel

    Section

  • Customize Manager

    Panel

    Section

    Control

  • Customize Manager

    Panel

    Section

    Control

    Setting

  • Customize Manager

    Panel

    Section

    Control

    Setting

    Context

    Context

    Context

  • Syntax

  • function PREFIX_customize_register($wp_customizer){// Theme Customizer code

    }

  • function PREFIX_customize_register($wp_customizer){// Theme Customizer code

    }

    add_action('customize_register', PREFIX_customize_register

    );

  • function PREFIX_customize_register($wp_customizer){// Theme Customizer code

    }

    add_action('customize_register', PREFIX_customize_register

    );

  • $wp_customizer->add_X(

    );

  • $wp_customizer->add_X(

    );

    X = setting, panel, section, control

  • $wp_customizer->add_X(name,

    );

    X = setting, panel, section, control

  • $wp_customizer->add_X(name,array(

    setting_1 => value,setting_2 => value,setting_N => value

    ));

    X = setting, panel, section, control

  • $wp_customizer->get_X(name)

  • $wp_customizer->get_X(name)

    $wp_customizer->remove_X(name)

  • Available paramsparam / element panel section control setting

    type description

    priority capability

    theme_supports title

    panel section

    label choices

    input_attrs active_callback

    sanitize_callback sanitize_js_callback

    default transport

  • Types of controls

  • text

    radio

    checkbox

    textarea

    select

    dropdown-pages

  • WP_Customize_Color_ControlWP_Customize_Image_Control

  • More controls

  • $wp_customize->add_control( mytheme_layout_width, array(

    'type' => 'range', 'section' => 'layout', 'label' => Layout width', 'input_attrs' => array( 'min' => 720, 'max' => 1280, 'step' => 1, 'class' => layout-width-control ) ) );

  • $wp_customize->add_control( mytheme_layout_width, array(

    'type' => 'range', 'section' => 'layout', 'label' => Layout width', 'input_attrs' => array( 'min' => 720, 'max' => 1280, 'step' => 1, 'class' => layout-width-control ) ) );

  • $wp_customize->add_control( mytheme_layout_width, array(

    'type' => 'range', 'section' => 'layout', 'label' => Layout width', 'input_attrs' => array( 'min' => 720, 'max' => 1280, 'step' => 1, 'class' => layout-width-control ) ) );

  • But there is a small problem

  • Source: http://caniuse.com/#search=date

    http://caniuse.com/#search=date
  • Custom controls

  • class My_Customize_Textarea_Control extends WP_Customize_Control {

    }

  • class My_Customize_Textarea_Control extends WP_Customize_Control {public $type = 'textarea';

    }

  • class My_Customize_Textarea_Control extends WP_Customize_Control {public $type = 'textarea'; public function render_content() {?>

  • class My_Customize_Textarea_Control extends WP_Customize_Control {public $type = 'textarea'; public function render_content() {?>

  • class My_Customize_Textarea_Control extends WP_Customize_Control {public $type = 'textarea'; public function render_content() {?>

  • class My_Customize_Textarea_Control extends WP_Customize_Control {public $type = 'textarea'; public function render_content() {?>

  • class My_Customize_Textarea_Control extends WP_Customize_Control {public $type = 'textarea'; public function render_content() {?>

  • $wp_customize->add_control(

    );

  • $wp_customize->add_control( new My_Customize_Textarea_Control(

    ));

  • $wp_customize->add_control( new My_Customize_Textarea_Control( $wp_customize, theme_copyright_text,

    ));

  • $wp_customize->add_control( new My_Customize_Textarea_Control( $wp_customize, theme_copyright_text,

    array( 'label' => __(Copyright text', 'theme'), 'section' => 'features',

    'settings' => theme_copyright_text, 'priority' => 2

    ))

    );

  • How to use context?

  • Hiding unnecessary options

  • Hiding unnecessary options

    Options dedicated to specific subpages

  • Hiding unnecessary options

    Options dedicated to specific subpages

    Creating dependencies between options

  • $wp_customize->add_control('mytheme_google_font',array(

    'section' => 'mytheme_font_options','label' => __('Google Font URL', 'mytheme'),'type' => 'text','active_callback' => 'mytheme_show_font_field'

    ));

  • function mytheme_show_font_field($control) {

    }

  • function mytheme_show_font_field($control) {$option = $control->manager->get_setting(mytheme_font');

    }

  • function mytheme_show_font_field($control) {$option = $control->manager->get_setting(mytheme_font');

    return $option->value() == 'google';}

  • Problems with active_callback

    is_front_page will work fine as:

    active_callback => is_front_page

  • Problems with active_callback

    is_front_page will work fine as:

    active_callback => is_front_page

    but is_single or is_singular wont, because they take an argument which in this case is a handler to

    the panel/section/control

  • Problems with active_callback

    function PREFIX_is_single() {

    return is_single();

    }

  • Live preview

  • $wp_customize->add_setting( 'mytheme_primary_color', array(

    'default' => '#5cc1a9', 'capability' => 'edit_theme_options',

    'transport' => 'postMessage', 'sanitize_callback' => 'sanitize_hex_color'

    ));

  • $wp_customize->add_setting( 'mytheme_primary_color', array(

    'default' => '#5cc1a9', 'capability' => 'edit_theme_options',

    'transport' => 'postMessage', 'sanitize_callback' => 'sanitize_hex_color'

    ));

  • function mytheme_customize_preview_js() {wp_enqueue_script(

    'mytheme-customize-preview', get_template_directory_uri() . '/js/customize-preview.js', array(), 1.0', true

    );}

  • function mytheme_customize_preview_js() {wp_enqueue_script(

    'mytheme-customize-preview', get_template_directory_uri() . '/js/customize-preview.js', array(), 1.0', true

    );}

    add_action('customize_preview_init', mytheme_customize_preview_js'

    );

  • (function($){

    })(jQuery);

  • (function($){ wp.customize(

    'mytheme_primary_color', function(value) {

    } );})(jQuery);

  • (function($){ wp.customize(

    'mytheme_primary_color', function(value) {

    value.bind(function(to) { }); } );})(jQuery);

  • (function($){ wp.customize(

    'mytheme_primary_color', function(value) {

    value.bind(function(to) { jQuery('a').css('color', to || '#5cc1a9'); }); } );})(jQuery);

  • Optimisation

  • wp.customize('mytheme_primary_color', function(value) { value.bind( function( to ) {

    } );});

  • wp.customize('mytheme_primary_color', function(value) { value.bind( function( to ) { to = to || '#5cc1a9';

    } );});

  • wp.customize('mytheme_primary_color', function(value) { value.bind( function( to ) { to = to || '#5cc1a9'; var new_css = 'a { color: ' + to + '; }';

    } );});

  • wp.customize('mytheme_primary_color', function(value) { value.bind( function( to ) { to = to || '#5cc1a9'; var new_css = 'a { color: ' + to + '; }'; if($('#new-css').length) { $('#new-css').remove(); }

    } );});

  • wp.customize('mytheme_primary_color', function(value) { value.bind( function( to ) { to = to || '#5cc1a9'; var new_css = 'a { color: ' + to + '; }'; if($('#new-css').length) { $('#new-css').remove(); } $(document).find('head') .append($('' + new_css + '')); }

    );});

  • Results

    BEFORE

    potentially thousands of DOM operations

    manipulations with style attributes

    AFTER

    maximum 2 DOM operations

    no manipulations with style attributes

  • JavaScript API

  • Possibilities

    Access to all elements

  • Possibilities

    Access to all elements

    Re-render of existing elements

  • Possibilities

    Access to all elements

    Re-render of existing elements

    Modification of existing elements

  • Possibilities

    Access to all elements

    Re-render of existing elements

    Modification of existing elements

    Event tracking and control over the preview area

  • function PREFIX_theme_customizer_tooltips() { ?>

  • function PREFIX_theme_customizer_tooltips() { ?> jQuery(document).ready(function() {

    });

  • function PREFIX_theme_customizer_tooltips() { ?> jQuery(document).ready(function() { wp.customize.bind('ready', function() { // Your Theme Customizer Code }); });

  • Examples

  • wp.customize.section("colors").expand();

    Examples

  • wp.customize.section("colors").expand();

    wp.customize.control("blogname").priority(100);

    Examples

  • wp.customize.section("colors").expand();

    wp.customize.control("blogname").priority(100);

    wp.customize.control("blogname").section("colors");

    Examples

  • wp.customize.section("colors").expand();

    wp.customize.control("blogname").priority(100);

    wp.customize.control("blogname").section("colors");

    var ctrl = wp.customize.control("background_color");ctrl.params.label = "New label";ctrl.renderContent();ctrl.ready();

    Examples

  • Reading list https://www.gavick.com/blog/live-preview-themes-colors-changes-theme-

    customizer

    https://www.gavick.com/blog/contextual-controls-theme-customizer

    https://www.gavick.com/blog/theme-customization-controls

    https://www.gavick.com/blog/custom-control-wordpress-theme-customizer

    https://www.gavick.com/blog/custom-category-selection-controls

    https://www.gavick.com/blog/using-javascript-theme-customization-screen

    https://www.gavick.com/blog/using-tooltips-instead-option-descriptions-wordpress-theme-customizer

    https://www.gavick.com/blog/internal-linking-wordpress-theme-customizer

    https://www.gavick.com/blog/live-preview-themes-colors-changes-theme-customizerhttps://www.gavick.com/blog/contextual-controls-theme-customizerhttps://www.gavick.com/blog/theme-customization-controlshttps://www.gavick.com/blog/custom-control-wordpress-theme-customizerhttps://www.gavick.com/blog/custom-category-selection-controlshttps://www.gavick.com/blog/using-javascript-theme-customization-screenhttps://www.gavick.com/blog/using-tooltips-instead-option-descriptions-wordpress-theme-customizerhttps://www.gavick.com/blog/internal-linking-wordpress-theme-customizer
  • Dkuji!

  • Questions?

  • This presentation is available under the GPL license:

    http://www.gnu.org/copyleft/gpl.html

    http://www.gnu.org/copyleft/gpl.html