WordPress.org recently announced that all new themes will be required to use the Customize API as an interface for theme options.
All new themes must immediately adhere to the requirement, and all existing themes will be required to convert on the first update after October 21st (6 months from now).
Theme Customizer is a great interface and I totally support the decision. It is much simpler then developing a custom panel system as was done in the past. Once you have been through setting up theme options using the Customize interface, you will feel much more in control of your options system.
The Panache WordPress Theme, recently approved at WordPress.org, uses the Customize System to create a multi-panel multi-section system in the Customize interface. I have taken that system and adapted it so you can use to set up your options for your theme.
- one panel/one section to multi panel/multi section
- data sanitization
- use theme_mods table or separate table or both
- controls offered
- image upload
- file upload
- media upload
- select list
- radio list
- range slider
- category list
- tag list
- color picker
- All options collected in a single array variable for use throughout the theme
- The option system also allows you to attach an html script to the first panel, ideal when offering theme links and a PayPal button
Options saved to the theme_mods table will allow you to create different looks for your site, as they will be setup for the theme and will also need to be setup in each child theme. Options saved to the separate options table will carry through to the child themes as well.
The system does not include any code for the Customize Live preview panel. All options will load on page refresh. However you can set up your options using ‘transport’=>’postMessage’ and then provide the code to make the CSS changes live. See Codex Customize API
Set up – New options system
- Download the file and unzip it.
- Put the kha-customizer.php file in a folder within your theme folder, this is usually /themes/YourTheme/includes/ or something like that
- Add the following to the top of your functions file
1234/*** Customizer additions.*/require get_template_directory() . '/inc/kha-customizer.php';
- Do a search and replace themeslug with yourthemeslug 🙂
- If your theme slug is hyphenated, such as your-themeslug, make sure all text domains are your-themeslug, and all function and variable prefixes are your_themeslug
- Setup your panels and sections
- Setup your options
Default SettingsI would advise against saving any options at this time because you will be changing setup options.
KA WordPress Customize Setup is initially setup with three panels to get you started. If you went into “Appearance=>Customize” at this time you would see the following :
Add HTML block to Customize Panel
This function allows you to add a block of HTML script to the top of the first panel you create. It allows you as a developer to add the theme links and even a PayPal button if you want.
add_action( 'customize_render_panel_themeslug_intro', 'themeslug_customizer_intro' );
echo '<li id="accordion-panel-general" class="themeslug-intro accordion-section control-section control-panel control-panel-default">'.
__('themeslug Theme Links','themeslug').
'<span class="screen-reader-text">Press return or enter to expand</span>'.
'<a class="themeslug-intro-author button" href="//yoursite.com/" title="//yoursite.com/" target="_blank" >'.
'<a class="themeslug-intro-demo button" href="//yoursite.com/demo3/" title="//yoursite.com/demo3/" target="_blank" >'.
//User Documentation Page for your theme
'<a class="themeslug-intro-docs button" href="//yoursite.com/demo3/introduction/" title="//yoursite.com/demo3/introduction/" target="_blank" >'.
// Donate Link
- make sure that panel1 in the add_action() is replaced with the id/name of your first panel
- eplace themeslug with yourthemeslug
- modify the links to the links you want
- add your PayPal link if you want
Set Up your Panels
The first panel is shown below, with two sections
'panel1' => array( //you must have at least one panel
'name' => 'panel1',// id of the panel keep the same as the panel key above
'title' => __( 'themeslug Panel 1','themeslug'),//title for the panel, for ex themeslug General Options
'description' => 'Description of panel, you could author, demo, docs, or paypal html here',
'priority' => 1,//priority where the panels will go in the display
'sections' => array(//must have at least one section
'panel1_section1' => array( //good practice to keep the array key the same as the name
'name' => 'panel1_section1',//name of the section that will be used where the options are set up
'title' => __( 'Section 1 Options','themeslug'),//title that will appear for the section
'description' => '',//you can add a description of what is in the section if you want
'priority' => 1//priority where the section will list within the panel
'panel1_section2' => array(//repeat sections as you want
'name' => 'panel1_section2',
'title' => __( 'Section 2 Options','themeslug'),
'description' => '',
'priority' => 2
- replace themeslug with yourthemeslug
- Fill in the panel and section information as shown by the comments
- Add sections and panels
- delete any of the panel/section code that you do not require
Set up your options
Example code for the first select option is shown below.
'themeslug_select1' => array(
'name' => 'themeslug_select1',//keep the name the same as the option key. ALL OPTION NAMES MUST BE UNIQUE
'title' => __('Select box 1 Option','themeslug'),//title to show in option
'option_type' => 'select',//text, textarea, checkbox, radio, select, range, image, color, upload, scat, stag
'setting_type' => 'option',//option->saves to separate table called themeslug_customize_options
// ->will not be changed in child theme
//theme-mod->saves to theme options table called theme_mods_themeslug
// ->will have to be re-entered for child theme
'choices' => array( //only for the select and radio lists and the range slider
'option 1' => __( 'Option 1' , 'themeslug' ),
'option 2' => __( 'Option 2' , 'themeslug' ),
'option 3' => __( 'Option 3' , 'themeslug' )
'description' => __('Option description','themeslug'),//additional documentation for option
'section' => 'panel1_section1',//section you want the option to appear under
'priority' => 5,// order within the section that the option is displayed
'default' => 'option 1',//sane default, what default do you want to use if the user does not update this option
'transport' => 'refresh', // refresh-> page must be reloaded to use the option
'sanitize' => 'sanitize_text_field'// sanitize callback function you want to use, see recommended below
// text(email) => is_email,text(nohtml)=>sanitize_text_field,
// text(html allowed)=>wp_kses_post,text(link) => esc_url_raw,
// textarea(no html allowed)=>esc_html,textarea(html allowed)=> wp_kses_post
- replace themeslug with yourthemeslug
- Fill out the option info as per the comments
- repeat for the options you want
- Delete any options you do not want
Users who are updating existing optionsBe very careful wen you are switching to the Customize API with an existing set of options.
- Make sure the save option corresponds to the table you are using
- ‘save’=>’theme_mods’ to use the theme_mods table
- ‘save’=>’save’=>’option’ to use the separate table
- Make sure your options have exactly the same name or you will not be able to access them
- If using a separate table make sure you are using exactly the table name you are saving your existing options under
- search and replace ‘themeslug_customize_options’ with your table name
- Deactivate your settings API by commenting out (initially) the file loads for your options
- Make sure you have gone through your theme and are using your options with the appropriate setup function
- After successful testing delete all the replaced options setup files and references