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.

WordPress customizer: for themes and more

559 views

Published on

Presentation slides from WordCamp Montreal 2015 talk.

In WordPress 4.1 the “Theme Customizer” was changed to the “Customizer” with the intent that it could be used as the interface for any WordPress settings. Very few plugin authors, or even custom theme authors, are taking advantage of this built in options panel. Through some examples, we see how easy it is to use the Customizer API to add settings/options to WordPress for themes, plugins (or anything).

Published in: Technology
  • Be the first to comment

  • Be the first to like this

WordPress customizer: for themes and more

  1. 1. r3df.com lumostech.training Rick Radko “WordPress Customizer: For Themes and More” WordCamp Montreal July 4th, 2015 Slides at: slideshare.net/r3df
  2. 2. © 2015 Rick Radko, r3df.com What's this talk about? This talk:  Is an overview to the using the customizer function in WordPress plugins or themes.  Goals:  Demonstrate that it is easy to code an option.  Encourage you to try it. For code examples, I'm going to use a plugin I created: wordpress.org/plugins/r3df-copyright-message 1Slides at: slideshare.net/r3df
  3. 3. © 2015 Rick Radko, r3df.com A little bit about me Rick Radko 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.  Lead organizer of:  WordCamp Ottawa 2013, 2014, 2015.  The Ottawa WordPress Group. 2Slides at: slideshare.net/r3df
  4. 4. © 2015 Rick Radko, r3df.com Introduced as Theme Customizer in 3.4 3
  5. 5. © 2015 Rick Radko, r3df.com Theme Customizer - WordPress 3.4 4
  6. 6. © 2015 Rick Radko, r3df.com Theme Customizer - Evolution 5
  7. 7. © 2015 Rick Radko, r3df.com Theme Customizer - Widgets & Panels 6
  8. 8. © 2015 Rick Radko, r3df.com Customizer in 4.2 7
  9. 9. © 2015 Rick Radko, r3df.com Customizer - Change themes 8
  10. 10. © 2015 Rick Radko, r3df.com Customizer - Future 9
  11. 11. © 2015 Rick Radko, r3df.com Custom Login Page Customizer 10
  12. 12. © 2015 Rick Radko, r3df.com Why use the Customizer? It provides a ready to use options framework:  No need to re-invent the wheel.  Lots of built in "controls".  Color pickers, image & files uploads, page lists.  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. 11
  13. 13. © 2015 Rick Radko, r3df.com Example Plugin: R3DF Copyright Message 12 wordpress.org/plugins/r3df-copyright-message
  14. 14. © 2015 Rick Radko, r3df.com Example Plugin - Detail 13
  15. 15. © 2015 Rick Radko, r3df.com Lets see how to do it - 4 easy steps 1. Register your customizer set-up function.  A place to put all the customizer stuff. 2. Add sections to the registered function.  Sections hold the settings. 3. Add settings to the registered function.  Settings define how the options will be saved. 4. Add controls to the registered function.  Controls change the settings. 14
  16. 16. © 2015 Rick Radko, r3df.com 1. Register the customizer function  The function is passed an object, $wp_customize, which is used to create sections, settings and controls.  This function and add_action can be placed in functions.php or your main plugin file. 15
  17. 17. © 2015 Rick Radko, r3df.com The register code for the example plugin 16
  18. 18. © 2015 Rick Radko, r3df.com A 4.1+ gotcha for the 'customize_register' hook From the codex: "Important: Do not conditionally load your Customizer code with an is_admin() check."  Your customizer options won't display properly!!! 17
  19. 19. © 2015 Rick Radko, r3df.com 2. Add section(s) for your settings  $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 18
  20. 20. © 2015 Rick Radko, r3df.com The section code for the example plugin  You will not be able to see the section until it contains at least one setting. 19
  21. 21. © 2015 Rick Radko, r3df.com Sections in 4.2 vs 4.3 20
  22. 22. © 2015 Rick Radko, r3df.com 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'  You will not be able to see the setting until it contains at least one control. 21
  23. 23. © 2015 Rick Radko, r3df.com Where are the values stored? Options 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 22
  24. 24. © 2015 Rick Radko, r3df.com The settings code for the example plugin  The pseudo array notation, for the setting id, allows the options to be stored as an array. 23
  25. 25. © 2015 Rick Radko, r3df.com 4. Add control(s)  $control_id - A unique ID for the setting.  $args: array  section - the section for the control  settings - the setting that the control changes  label - a label for the control  type - basic types include: text, checkbox, radio, select, dropdown-pages, textarea  priority - sets the display order of the controls 24
  26. 26. © 2015 Rick Radko, r3df.com The controls code for the example plugin 25
  27. 27. © 2015 Rick Radko, r3df.com The customizer options 26
  28. 28. © 2015 Rick Radko, r3df.com Using saved option values Accessing the values depends on your setting type:  theme_mod:  option:  can use with existing options ie: to use with existing plugin 27
  29. 29. © 2015 Rick Radko, r3df.com Another potential gotcha! User may not get the settings behaviour they expect:  If, for example, you have a checkbox which defaults to checked:  Users will see the setting working with the default when they view the preview. (so they don't change any settings)  BUT if they don't change your settings, They may NOT be saved!! (unless they make changes to other settings and save)  Need to make sure your code handles defaults if settings are not saved. 28
  30. 30. © 2015 Rick Radko, r3df.com The example plugin's output code 29
  31. 31. © 2015 Rick Radko, r3df.com The output hooks in code 30
  32. 32. © 2015 Rick Radko, r3df.com The result 31
  33. 33. © 2015 Rick Radko, r3df.com Beyond the basics - Conditional actions 32
  34. 34. © 2015 Rick Radko, r3df.com Beyond the basics - Conditional actions  active_callback example 33
  35. 35. © 2015 Rick Radko, r3df.com Beyond the basics - Modifying existing sections You can of course modify existing customizer options.  Built-in section id’s:  Site Title & Tagline: title_tagline  Colors: colors  Header Image: header_image  Background Image: background_image  Navigation: nav  Static Front Page: static_front_page  Also get_setting() and get_control() 34
  36. 36. © 2015 Rick Radko, r3df.com Beyond the basics - Transport By default, when a customizer setting is updated, the preview is updated with a page reload.  This has a notable lag If you add the transport argument to the add_setting call: (and add all the needed javascript) The page will update “instantly”. 35
  37. 37. © 2015 Rick Radko, r3df.com Beyond the basics - Sanitizing values Input data can be sanitized by adding callbacks to the setting definition:  The argument “sanitize_callback” adds a callback to sanitize the input values for the setting.  The argument “sanitize_js_callback” adds a callback to sanitize the output to the javascript code for the preview. Should only be needed in special cases. 36
  38. 38. © 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/ 37
  39. 39. © 2015 Rick Radko, r3df.com Learn More…  codex.wordpress.org/Theme_Customization_API  developer.wordpress.org/themes/advanced-topics/customizer-api/  ottopress.com/2012/how-to-leverage-the-theme-customizer-in-your-own- themes/  http://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/  www.gavick.com/blog/contextual-controls-theme-customizer 38
  40. 40. © 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 39

×