Your theme may have a particular purpose, or serve a certain niche group. You may bundle a number of different widgets with your theme that provide the best possible experience when using it. If so, you'll likely want to have these widgets inserted into your sidebars when the theme is activated.
Getting ready
You need to have a theme with a sidebar.php template, and at least one of your main theme files must use the get_sidebar function to include the sidebar. In addition, your sidebar must be dynamic. Finally, you must know the unique IDs of your sidebars and of the widgets that you wish to pre-set in those sidebars. To make your sidebar dynamic, see the earlier recipes in this chapter. Back up your current theme, and be aware that using this recipe will reset the widgets of the active theme.
How to do it...
Open or create your theme's functions.php file. In this example, we will be inserting default widgets for default search, pages, categories, and recent comments. Insert the following block of code immediately before the closing ?> tag within the file:
$current_theme = get_option( 'template' );
$target_theme = 'Widgety_Theme';
if ( is_admin() &&
current_user_can( 'switch_themes' ) &&
isset( $_GET['activated'] ) &&
$current_theme == $target_theme ){
$preset_widgets = array ( 'sidebar-one' => array(
'widget-search-2', 'widget-pages-3' ),
'sidebar-two'=> array('widget-categories-4', 'widget-recent-comments-3'));
update_option( 'sidebars_widgets', $preset_widgets );}
You will need to substitute the correct values for the following variables before the code will work with your theme:
$target_theme—replace Widgety_Theme with the name of the folder in which your theme resides
$preset_widgets—replace the array with a multidimensional array in which each of your sidebar IDs is a key to an array of widget IDs that you wish to have in the sidebar, as shown in the example above
Save the functions.php file. Remember, this code only works when a theme is activated; so deactivate this theme if it is your current theme, then upload the updated functions.php file and reactivate your theme, or install it on a test site to see the changes to the sidebars in the Widgets area of the admin panel as seen in the next screenshot:
Now that you have the basic idea down, you can create your sets of default widgets for the sidebars of your theme.
How it works...
You accomplished a lot in this example! Let's take a closer look at what happened. First, the name of the currently-active template is stored in a variable. Then, the name of the target template (the name of the folder that your theme is stored in) is stored in another variable.
Following this, a comparison is made. A check is performed to confirm that an administrative interface page is being displayed. Next, the code confirms that the currently logged-in user has the ability to switch themes and manage widgets. Without these two checks, any anonymous user would be able to reset all of your widgets.
The next two parts of the conditional are equally important. The third condition checks that a new theme is being activated. Obviously, the widget reset should only happen when the theme has been switched to. The final condition checks that the currently-active theme is the same as the target theme (your theme, in this case).
If all of these conditions hold true, then it is time for the real work of setting the predefined widgets. First, an associative array is defined. Looking at this in more detail may be helpful:
$preset_widgets = array
( 'sidebar-one' => array( 'widget-search-2', 'widget-pages-3' ),'sidebar-two'=> array('widget-categories-4', 'widget-recent-comments-3'));
In this example, the assumption is made that a sidebar with the ID sidebar-one exists in your theme and that there are at least two widgets present, one with the ID search-2 and one with the ID pages-3. This array basically says that the sidebar sidebar-one should have the widget search-2 and pages-3 inside of it, and that the sidebar sidebar-two should have the widgets categories-4 and recent-comments-3 without any further configuration from the user.
The next line updates the sidebars_widgets option in the WordPress database, where information regarding the content of dynamic sidebars is stored. After that is done, the widgets will be set appropriately.
There's more...
Widget IDs can be found in several ways. Read on for two options on how to discover the IDs of your widgets.
Widget IDs
To find the ID of a particular widget, you have a few options. The first option is to look at the code of the plugin that provides the widget (if it comes from a plugin) or examine the WordPress source for plugins that come with the default distribution.
The second option may be easier. Install a test blog and use the WordPress Classic theme, adding the widgets that you want to know the IDs for, to the only sidebar available. Then, view the source of the front page of the blog and look for the sidebar HTML. Each widget's ID will be displayed as the id attribute of a list item in the sidebar, as follows:
<li id="widget-id">
Make a note of the IDs of the widgets that you want to use and you're all set.