Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Creating Customizer Options for Themes and Plugins

812 views

Published on

Presentation slides from WordCamp Toronto 2015 talk.

Published in: Technology
  • Be the first to comment

  • Be the first to like this

Creating Customizer Options for Themes and Plugins

  1. 1. r3df.com lumostech.training Rick Radko “Creating Customizer Options for Themes and Plugins” WordCamp Toronto October 4th, 2015 Slides at: slideshare.net/r3df
  2. 2. © 2015 Rick Radko, r3df.com What's this talk about?  An introduction to adding customizer options to your plugins and themes. Topics:  Introduction  Brief introduction to customizer  Creating customizer options  4 steps  Using the options  Beyond the Basics 1Slides at: slideshare.net/r3df
  3. 3. © 2015 Rick Radko, r3df.com Objectives of this talk:  Demonstrate that it is easy to add basic customizer options to plugins and themes.  Encourage you to start using the customizer for your options. For code examples for this presentation, I'm going to use a plugin I created recently:  wordpress.org/plugins/r3df-copyright-message  (Version 1.1.0) 2Slides at: slideshare.net/r3df
  4. 4. © 2015 Rick Radko, r3df.com About me  Rick Radko, @r3designforge Software, website and app designer/developer, trainer, speaker.  R-Cubed Design Forge: r3df.com  LumosTech Training: lumostech.training Creating custom web sites since 1996.  WordPress sites since 2008. An organizer of:  WordCamp Ottawa.  The Ottawa WordPress Group. 3Slides at: slideshare.net/r3df
  5. 5. © 2015 Rick Radko, r3df.com Theme Customizer - WordPress 3.4 4
  6. 6. © 2015 Rick Radko, r3df.com Customizer in 4.3 5
  7. 7. © 2015 Rick Radko, r3df.com Customizer in 4.3 - Menus 6
  8. 8. © 2015 Rick Radko, r3df.com Customizer in 4.3 - Site Icon 7
  9. 9. © 2015 Rick Radko, r3df.com Why use the Customizer for options? It provides a ready to use options framework:  Native to WordPress  No need to re-invent the wheel.  Lots of built in controls.  Can add custom controls.  Now required for themes in wordpress.org repo.  It’s the future for options. I'm using it for:  Custom theme & child theme options.  Small plugins. 8
  10. 10. © 2015 Rick Radko, r3df.com Plugin: Custom Login Page Customizer 9
  11. 11. © 2015 Rick Radko, r3df.com Example Plugin: R3DF Copyright Message 10 wordpress.org/plugins/r3df-copyright-message
  12. 12. © 2015 Rick Radko, r3df.com Adding a customizer option - 4 easy steps 1. Register your customizer set-up function. 2. Add a section. 3. Add settings. 4. Add controls to connect the settings to the section. 11
  13. 13. © 2015 Rick Radko, r3df.com Step 1. Register the customizer function 12
  14. 14. © 2015 Rick Radko, r3df.com A gotcha for the 'customize_register' hook From the codex: "Important: Do not conditionally load your Customizer code with an is_admin() check." 13
  15. 15. © 2015 Rick Radko, r3df.com Step 2. Add a section  $section_id - A unique ID for the section.  $args: array  title - the name of the section  priority - (optional) controls display order of the sections  description - (optional) add descriptive text to the section 14
  16. 16. © 2015 Rick Radko, r3df.com Priorities for top level items 15 Priority (Order) 20 40 60 80 100 110 120 160 (default)
  17. 17. © 2015 Rick Radko, r3df.com The section code for the plugin Note:  You will not be able to see the section until it contains at least one control. 16
  18. 18. © 2015 Rick Radko, r3df.com Step 3. Add setting(s)  $setting_id - A unique ID for the setting.  $args: array  default - default value for the setting  type - (optional) types are 'option' or 'theme_mod' type defaults to 'theme_mod' Note:  You will not be able to see the setting until it is registered with a control. 17
  19. 19. © 2015 Rick Radko, r3df.com Where are the values stored? By default:  Values are stored in the "wp_options" table.  The option key depends on setting type:  theme_mod: Option key: theme_mods_{theme-name} Array key (in the option): setting_id  option: Option key: setting_id 18
  20. 20. © 2015 Rick Radko, r3df.com The settings code for the plugin Note:  The pseudo array notation, for the setting id, stores the options as an array. 19
  21. 21. © 2015 Rick Radko, r3df.com Step 4. Add control(s)  $control_id - A unique ID for the control.  If you set it to the value of a setting id, it will control that setting. (instead of setting the settings arg)  $args: array  label - a label for the control  description - a description below the label  section - the section for the control  type - basic types include: text, checkbox, radio, select, dropdown-pages, textarea… 20
  22. 22. © 2015 Rick Radko, r3df.com The controls code for the plugin 21
  23. 23. © 2015 Rick Radko, r3df.com The controls code for the plugin 22
  24. 24. © 2015 Rick Radko, r3df.com The plugin display so far in customizer 23
  25. 25. © 2015 Rick Radko, r3df.com The plugin - expanded 24
  26. 26. © 2015 Rick Radko, r3df.com Where’s the copyright message? 25
  27. 27. © 2015 Rick Radko, r3df.com Using saved option values Setting type:  theme_mod:  option:  Can use with standard WordPress options. ie: convert existing plugin 26
  28. 28. © 2015 Rick Radko, r3df.com The plugin's output code 27
  29. 29. © 2015 Rick Radko, r3df.com The complete result in the customizer 28
  30. 30. © 2015 Rick Radko, r3df.com The result on the frontend 29
  31. 31. © 2015 Rick Radko, r3df.com Beyond the basics - Conditional actions Conditional display – dependent on radio button 30
  32. 32. © 2015 Rick Radko, r3df.com Beyond the basics - Transport By default, when a customizer setting is changed:  The preview is updated with a page refresh.  This has a notable lag… But, we can fix that… 31
  33. 33. © 2015 Rick Radko, r3df.com Beyond the basics - Transport Add some javascript… …and the page will update “instantly”. Note:  Preview javascript is loaded on the "customize_preview_init" action 32
  34. 34. © 2015 Rick Radko, r3df.com Beyond the basics - Sanitizing values Input data can be sanitized by adding callbacks to the add_setting() definition:  Built in WordPress functions can often be used.  sanitize_key() checks that the data looks like an internal identifier (key). 33
  35. 35. © 2015 Rick Radko, r3df.com Beyond the basics - Panels 34 2 Items
  36. 36. © 2015 Rick Radko, r3df.com Beyond the basics - Panels 35 New top level
  37. 37. © 2015 Rick Radko, r3df.com Beyond the basics - Panels 36
  38. 38. © 2015 Rick Radko, r3df.com Beyond the basics - Panels  Panel with 2 sections 37
  39. 39. © 2015 Rick Radko, r3df.com Beyond the basics - Modifying existing sections  get_panel() for panels, get_setting() for settings, and get_control() for controls 38 Section Id title_tagline colors header_image background_image nav_menus widgets static_front_page r3df_copyright_message_settings
  40. 40. © 2015 Rick Radko, r3df.com Beyond the basics - Advanced controls Advanced Controls:  Color picker: WP_Customize_Color_Control()  Media uploader: WP_Customize_Upload_Control()  Image uploader: WP_Customize_Image_Control()  Background image control: WP_Customize_Background_Image_Control()  Header image control: WP_Customize_Header_Image_Control() Custom controls:  ottopress.com/2012/making-a-custom-control-for- the-theme-customizer/ 39
  41. 41. © 2015 Rick Radko, r3df.com How does preview update without saving? The customizer preview intercepts calls to:  get_theme_mod  get_option Replaces them with the "live" content from the customizer controls. Note:  This only seems to work on or after the action "parse_request". 40
  42. 42. © 2015 Rick Radko, r3df.com Learn More…  codex.wordpress.org/Theme_Customization_API  developer.wordpress.org/themes/advanced-topics/customizer-api/  developer.wordpress.org/reference/classes/wp_customize_manager/  ottopress.com/2012/how-to-leverage-the-theme-customizer-in-your-own- themes/  ottopress.com/2012/theme-customizer-part-deux-getting-rid-of-options- pages/  ottopress.com/2012/making-a-custom-control-for-the-theme-customizer/  ottopress.com/2015/whats-new-with-the-customizer/  gavick.com/blog/contextual-controls-theme-customizer  gavick.com/blog/using-javascript-theme-customization-screen  make.wordpress.org/core/2014/10/27/toward-a-complete-javascript-api- for-the-customizer/  make.wordpress.org/core/2015/07/27/site-icon/ 41
  43. 43. © 2015 Rick Radko, r3df.com Contact Rick Radko  email: wpinfo@r3df.com  twitter: @r3designforge Websites:  r3df.com  lumostech.training Slides at:  www.slideshare.net/r3df 42

×