Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Real-time editing with the Customize API

Luca Ricci
September 15, 2018

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.

Luca Ricci

September 15, 2018
Tweet

More Decks by Luca Ricci

Other Decks in Technology

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