When a user activates the TwentyEleven theme in the admin widgets area, the user already has the Main Sidebar populated with a few standard widgets. Could someone explain or point me in the right direction about how I could implement the same behavior for my widgets on another theme?
That's not actually installed by the theme. Those widgets are set up as soon as you install WordPress the first time. It's just that if your theme doesn't support widgets, you won't see them.
The part of WordPress that "installs" these widgets can be found in
wp-admin/includes/upgrade.php inside the function
wp_install_defaults. Here is the relevant part of the code. You should be able to retrofit to your own widgets:
// Set up default widgets for default theme. update_option( 'widget_search', array ( 2 => array ( 'title' => '' ), '_multiwidget' => 1 ) ); update_option( 'widget_recent-posts', array ( 2 => array ( 'title' => '', 'number' => 5 ), '_multiwidget' => 1 ) ); update_option( 'widget_recent-comments', array ( 2 => array ( 'title' => '', 'number' => 5 ), '_multiwidget' => 1 ) ); update_option( 'widget_archives', array ( 2 => array ( 'title' => '', 'count' => 0, 'dropdown' => 0 ), '_multiwidget' => 1 ) ); update_option( 'widget_categories', array ( 2 => array ( 'title' => '', 'count' => 0, 'hierarchical' => 0, 'dropdown' => 0 ), '_multiwidget' => 1 ) ); update_option( 'widget_meta', array ( 2 => array ( 'title' => '' ), '_multiwidget' => 1 ) ); update_option( 'sidebars_widgets', array ( 'wp_inactive_widgets' => array ( ), 'sidebar-1' => array ( 0 => 'search-2', 1 => 'recent-posts-2', 2 => 'recent-comments-2', 3 => 'archives-2', 4 => 'categories-2', 5 => 'meta-2', ), 'sidebar-2' => array ( ), 'sidebar-3' => array ( ), 'sidebar-4' => array ( ), 'sidebar-5' => array ( ), 'array_version' => 3 ) );
So what you (probably) want to do is run code similar to the stuff listed above upon first activation of your theme. I think this potentially causes some philosophical problems, if you are forcing certain widgets in certain areas. It definitely raises the question: "should these be widgets? Or should they be baked into your
siedbars.php file, if they're not really optional?" Widgets are designed to be added or removed by the admin, and should not be required for a theme to operate.
Anyway, that's the official stance, but if you are still set on it, take a look at the
'after_switch_theme' hook as a potential activation hook for your theme. You'll probably only want to run this once, so set an option on the database once you've "activated" your theme and check that option before registering the activation hook.
It should be noted, for anyone else stumbling upon this little snippet, that if you want to override what WordPress installs when it is run for the first time, you can:
- Create a file in
- Within that file, define a function called
wp_install_defaults(). This function will supplant the wp_install_defaults() function defined within upgrade.php
- It's a good idea to start by copying the entire
upgrade.phpand paste that into your
install.phpbootstrap, as a way to ensure that the good stuff you want to keep is still there, because if you define a wp_install_defaults() function, it completely replaces everything in the default function.