Real-time editing with the Customize API

The Customizer was introduced with WordPress 3.4, nonetheless it is a very underestimated feature.
In this talk we will discover what it is and which tools we have at our disposal and how to extend its functionalities with Customize API.
At the end of the speech you will have all the information needed to start integrating it in your themes and plugins.

Transcript

1. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
   Real-time editing with the
   Customize API
   Luca Ricci | Full stack developer | @theskinnyghost | @pragmaticweb | WordCamp Rome 2018 | #WCRM
   

   View Slide

2. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
   GOT A QUESTION?
   TWEET IT WITH
   #WCRM-CUSTOMIZEAPI
   

   View Slide

3. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
   ONCE UPON A TIME...
   

   View Slide

4. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
   

   View Slide

5. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
   

   View Slide

6. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
   Disadvantages of theme options pages
   ● Users get confused by different UIs
   ● Settings are not updated in real-time
   ● Some changes need a developer
   

   View Slide

7. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
   INTRODUCING THE CUSTOMIZER
   

   View Slide

8. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
   “The Customize API (Customizer) is a framework for
   live-previewing any change to WordPress. It
   provides a unified interface for users to customize
   various aspects of their theme and their site, from
   colors and layouts to widgets, menus, and more.
   Themes and plugins alike can add options to the
   Customizer. The Customizer is the canonical way to
   add options to your theme.”
   https://developer.wordpress.org/themes/customize-api/
   

   View Slide

9. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
   PRO
   ● Live preview for settings
   changes
   ● Draft, schedule, publish
   changes
   ● Consistent UI/UX
   ● Hide unnecessary options
   ● Easy to implement
   

   View Slide

10. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    “Themes are now required to utilize the
    Customizer API if the theme has custom theme
    settings. This means no custom settings
    screens”
    Justin Tadlock, theme review team
    

    View Slide

11. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    COMPONENTS
    

    View Slide

12. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    Panels
    Sections
    Controls
    Settings
    

    View Slide

13. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    Bootstraps the Customize experience on the server-side.
    Sets up the theme-switching process if a theme other than
    the active one is being previewed and customized.
    Serves as a factory for Customize Controls and Settings, and
    instantiates default Customize Controls and Settings.
    WP_CUSTOMIZE_MANAGER
    

    View Slide

14. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    WP_CUSTOMIZE_MANAGER
    function myprefix_customize_register( WP_Customize_Manager $wp_customize ) {
    // Do stuff with settings. // Do stuff with controls.
    $wp_customize->add_setting(); $wp_customize->add_control();
    $wp_customize->get_setting(); $wp_customize->get_control();
    $wp_customize->remove_setting(); $wp_customize->remove_control();
    // Do stuff with sections. // Do stuff with panels.
    $wp_customize->add_section(); $wp_customize->add_panel();
    $wp_customize->get_section(); $wp_customize->get_panel();
    $wp_customize->remove_section(); $wp_customize->remove_panel();
    }
    add_action( 'customize_register', 'myprefix_customize_register' );
    

    View Slide

15. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    Settings handle live-previewing, saving, and
    sanitization of your customizer objects. Each
    setting is managed by a control object.
    class: WP_CUSTOMIZE_SETTING
    SETTINGS
    

    View Slide

16. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    ADD SETTING
    

    View Slide

17. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    widget_*
    sidebars_widgets[*]
    nav_menu[*]
    nav_menu_item[*]
    KEEP IN MIND
    

    View Slide

18. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    SETTING TYPES
    option
    ● Options API
    ● Use with any themes and plugins
    ● Saved into unique options
    theme_mod
    ● Theme Modification API
    ● Specific to theme
    ● Saved into single option
    ● Serialized array
    Custom settings types
    customize_preview_$setting->type
    customize_update_$setting->type
    

    View Slide

19. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    HOW TO RETRIEVE DATA?
    

    View Slide

20. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    Controls are the primary Customizer object
    for creating UI. Must be associated with a
    setting.
    class: WP_CUSTOMIZE_CONTROL
    CONTROLS
    

    View Slide

21. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    ADD CONTROL
    

    View Slide

22. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    url
    datetime
    week
    tel
    checkbox
    text
    email
    textarea
    hidden
    search
    radio
    TYPES
    number
    time
    select
    range
    date
    * use the "allow_addition" argument to allow
    users to add new pages from the control
    dropdown-pages*
    

    View Slide

23. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    WP_Customize_Background_Image_Control
    WP_Customize_Color_Control
    WP_Customize_Cropped_Image_Control
    WP_Customize_Date_Time_Control
    WP_Customize_Image_Control
    WP_Customize_Media_Control
    There are more...
    https://goo.gl/SBbTu3
    CORE CUSTOM
    CONTROLS
    

    View Slide

24. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    ADD CUSTOM CONTROL
    

    View Slide

25. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    

    View Slide

26. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    UI containers for controls
    class: WP_CUSTOMIZE_SECTION
    SECTIONS
    

    View Slide

27. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    ADD SECTION
    

    View Slide

28. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    PANELS
    UI containers for multiple sections or
    different functionality
    class: WP_CUSTOMIZE_PANEL
    

    View Slide

29. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    ADD PANEL
    

    View Slide

30. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    TRANSPORT METHODS
    

    View Slide

31. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    REFRESH
    

    View Slide

32. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    

    View Slide

33. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    postMessage
    

    View Slide

34. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    

    View Slide

35. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    PHP
    

    View Slide

36. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    JS
    

    View Slide

37. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    PHP
    

    View Slide

38. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    SELECTIVE REFRESH
    

    View Slide

39. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    Advantages
    ● Cleaner code base
    ● Accurate preview update
    ● Association between parts of the preview and associated
    settings and controls
    

    View Slide

40. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    

    View Slide

41. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    REGISTERING PARTIALS
    

    View Slide

42. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    WIDGETS
    

    View Slide

43. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    CUSTOM WIDGETS?
    

    View Slide

44. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    

    View Slide

45. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    CONTEXTUAL CONTROLS, SECTIONS, AND
    PANELS
    

    View Slide

46. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    

    View Slide

47. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    Tip
    

    View Slide

48. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    VALIDATION
    

    View Slide

49. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    VALIDATION
    ● Settings validated before saving.
    ● If invalid, save request rejected.
    ● User has clear understanding of what is wrong.
    

    View Slide

50. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    

    View Slide

51. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    The customizer also has a robust JavaScript API
    https://developer.wordpress.org/themes/customize-api/the-customizer-javascript-api/
    https://github.com/WordPress/WordPress/tree/4.6.1/wp-admin/js/
    https://wordpress.tv/2017/12/10/weston-ruter-building-with-javascript-in-the-customizer/
    JavaScript API
    

    View Slide

52. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    CUSTOMIZER
    

    View Slide

53. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    Resources
    Theme Handbook - The Customize API
    XWP Customizer blog archive
    XWP GitHub
    Make WordPress - Dev notes
    Make WordPress - Customize Component
    Kirki - Framework for Customizer
    Customize Posts
    Customizer Browser History
    Collection of custom controls by Anthony Hortin
    WordPresent by Csaba Varszegi
    Rich Tabor blog archive
    

    View Slide

54. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    Settings API vs Customize API
    

    View Slide

55. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    USE BOTH!
    If it does not affect the frontend go with Settings API.
    Otherwise, always use the customizer!
    

    View Slide

56. Luca Ricci - @theskinnyghost - @pragmaticweb #WCRM - Questions? Tweet it at #WCRM-CUSTOMIZEAPI
    Luca Ricci | @theskinnyghost | @pragmaticweb
    

    View Slide