WordPress 3.3 Field Guide for Developers: Unpacking the "Sonny" Release

Introduction

Released on December 12, 2011, WordPress 3.3—codenamed “Sonny” in honor of jazz saxophonist Sonny Rollins—marked a pivotal minor update focused on refining the admin experience, enhancing developer tools, and modernizing underlying technologies. While not as revolutionary as major releases, 3.3 introduced critical changes that streamlined workflows for developers building themes, plugins, and custom solutions.

This guide dives deep into the developer-centric features of WordPress 3.3, from admin UI overhauls to JavaScript/PHP API improvements, deprecations, and migration best practices. Whether you’re maintaining legacy code or building new projects, understanding these changes is key to ensuring compatibility and leveraging the platform’s new capabilities.

Table of Contents

  1. Overview of WordPress 3.3
  2. Admin UI Enhancements for Developers
    • 2.1 The Refined Admin Bar
    • 2.2 The New wpColorPicker Widget
    • 2.3 Admin Color Schemes & Customization
    • 2.4 Screen Options & Meta Box Improvements
  3. Script & Style Loading: Modernizing Dependencies
    • 3.1 jQuery 1.7 Upgrade: Embracing .on() and .off()
    • 3.2 Improved wp_enqueue_script() Workflows
    • 3.3 Registering Scripts/Styles: Best Practices
  4. New JavaScript APIs
    • 4.1 wpColorPicker: A Native Color Picker
    • 4.2 Admin Bar JavaScript Hooks
  5. PHP API Additions & Refinements
    • 5.1 admin_enqueue_scripts: Formalizing Admin Asset Loading
    • 5.2 after_setup_theme: Theme Initialization Best Practices
    • 5.3 admin_color_schemes Filter: Custom Color Schemes
  6. Deprecations & Breaking Changes
    • 6.1 Deprecated jQuery Methods: .live() and .die()
    • 6.2 Legacy Widget APIs: Moving to WP_Widget Class
    • 6.3 Thickbox: The Beginning of the End
  7. Migration Tips: Upgrading to 3.3
  8. Conclusion
  9. References

Overview of WordPress 3.3

WordPress 3.3 prioritized developer experience and admin usability over radical new features. Key goals included:

  • Modernizing JavaScript dependencies (e.g., jQuery 1.7).
  • Simplifying admin interactions (e.g., the refined admin bar).
  • Providing native tools for common developer tasks (e.g., wpColorPicker).
  • Deprecating outdated APIs to encourage best practices.

These changes laid groundwork for future releases (like 3.5’s media modal overhaul) and set a precedent for WordPress’s shift toward more modular, JavaScript-driven admin interfaces.

Admin UI Enhancements for Developers

The admin dashboard received significant polish in 3.3, with updates that directly impact how developers build plugins and themes.

2.1 The Refined Admin Bar

First introduced in WordPress 3.1, the admin bar (formerly “toolbar”) was revamped in 3.3 for better usability and extensibility:

  • Sticky Positioning: The bar now stays fixed at the top of the screen, even when scrolling—a change that required developers to adjust theme CSS to avoid content clipping (e.g., adding padding-top: 28px to body.admin-bar).
  • Simplified API for Adding Items: The wp_admin_bar_add_menu() function became more robust, allowing plugins/themes to inject custom links, dropdowns, and icons.

Example: Adding a Custom Admin Bar Item

function my_custom_admin_bar_item() {
    global $wp_admin_bar;
    if ( !is_admin_bar_showing() ) return;

    $wp_admin_bar->add_menu( array(
        'id'    => 'my-custom-item',
        'title' => 'My Custom Link',
        'href'  => admin_url( 'admin.php?page=my-plugin-settings' ),
        'meta'  => array( 'class' => 'my-custom-class' )
    ) );
}
add_action( 'admin_bar_menu', 'my_custom_admin_bar_item', 999 );

2.2 The New wpColorPicker Widget

Gone were the days of hacking together custom color pickers: WordPress 3.3 introduced wpColorPicker, a jQuery UI-based widget that provided a consistent, native color selection experience. Built on jQuery UI’s slider and autocomplete, it supported hex values, transparency, and inline previews.

2.3 Admin Color Schemes & Customization

3.3 shipped with 8 built-in admin color schemes (e.g., “Fresh,” “Light,” “Blue”), accessible via Users → Your Profile. For developers, this unlocked the ability to register custom schemes using the admin_color_schemes filter, allowing brands or user groups to personalize the admin.

2.4 Screen Options & Meta Box Improvements

The “Screen Options” tab (top-right of admin pages) was refined to better manage meta boxes, columns, and layout preferences. Developers gained more control over meta box visibility, with improved support for register_meta_box_cb in register_post_type().

Script & Style Loading: Modernizing Dependencies

WordPress 3.3 made significant strides in how scripts and styles are managed, emphasizing best practices and modern JavaScript.

3.1 jQuery 1.7 Upgrade: Embracing .on() and .off()

The biggest change was upgrading to jQuery 1.7.1, which introduced the .on() and .off() methods to unify event handling (replacing .bind(), .live(), and .delegate()). This forced developers to update legacy code:

Before (Deprecated .live()):

$('.my-plugin-button').live('click', function() {
    // Action
});

After (Modern .on()):

$(document).on('click', '.my-plugin-button', function() {
    // Action
});

.live() was officially deprecated in jQuery 1.7, and WordPress 3.3 log warnings for its use, urging migration to .on().

3.2 Improved wp_enqueue_script() Workflows

wp_enqueue_script() and wp_enqueue_style() became more robust, with better dependency resolution. Plugins/themes could now explicitly declare dependencies (e.g., array('jquery')), ensuring scripts loaded in the correct order.

3.3 Registering Scripts/Styles: Best Practices

3.3 reinforced the “register-then-enqueue” pattern: first register assets with wp_register_script()/wp_register_style(), then enqueue them conditionally. This reduced redundant code and improved performance.

Example: Enqueuing a Script with Dependencies

function my_plugin_enqueue_scripts() {
    // Register script (optional but recommended)
    wp_register_script(
        'my-plugin-script',
        plugins_url( 'js/my-script.js', __FILE__ ),
        array( 'jquery' ), // Depends on jQuery
        '1.0.0',
        true // Load in footer
    );

    // Enqueue only on the plugin's settings page
    if ( isset( $_GET['page'] ) && $_GET['page'] === 'my-plugin-settings' ) {
        wp_enqueue_script( 'my-plugin-script' );
    }
}
add_action( 'admin_enqueue_scripts', 'my_plugin_enqueue_scripts' );

New JavaScript APIs

4.1 wpColorPicker: A Native Color Picker

To use wpColorPicker, developers enqueued its dependencies (jquery, jquery-ui-core, jquery-ui-slider) and initialized the widget on an input field:

Example: Using wpColorPicker in a Plugin

// Enqueue dependencies
function my_color_picker_scripts() {
    wp_enqueue_style( 'wp-color-picker' );
    wp_enqueue_script(
        'my-color-picker-script',
        plugins_url( 'js/color-picker.js', __FILE__ ),
        array( 'wp-color-picker' ), // Depends on wpColorPicker
        '1.0.0',
        true
    );
}
add_action( 'admin_enqueue_scripts', 'my_color_picker_scripts' );

JavaScript (color-picker.js):

jQuery(document).ready(function($) {
    $('#my-color-field').wpColorPicker({
        defaultColor: '#ff0000',
        change: function(event, ui) {
            console.log('New color:', ui.color.toString());
        }
    });
});

HTML Input:

<input type="text" id="my-color-field" name="my_color" value="#ff0000">

4.2 Admin Bar JavaScript Hooks

The admin bar exposed a JavaScript API (wp.adminBar) for dynamic interactions, such as adding/removing items or updating labels without reloading the page.

PHP API Additions & Refinements

5.1 admin_enqueue_scripts: Formalizing Admin Asset Loading

While introduced earlier, 3.3 solidified admin_enqueue_scripts as the canonical hook for enqueuing admin-specific scripts/styles (replacing init or wp_head). It passes a $hook_suffix parameter, enabling context-aware loading (e.g., only enqueue on post.php).

5.2 after_setup_theme: Theme Initialization Best Practices

The after_setup_theme hook became the standard for theme setup tasks (e.g., registering menus, post thumbnails, or theme supports like title-tag). It fires after the theme is loaded but before any template files, ensuring consistency.

5.3 admin_color_schemes Filter: Custom Color Schemes

Developers could register custom admin color schemes by filtering admin_color_schemes, defining CSS files, colors, and labels.

Example: Registering a Custom Color Scheme

function my_custom_color_scheme() {
    wp_admin_css_color(
        'my-scheme',
        'My Brand Scheme',
        plugins_url( 'css/my-scheme.css', __FILE__ ),
        array( '#222', '#333', '#444', '#555' ), // Base colors for UI elements
        array( 'base' => '#fff', 'focus' => '#ccc' ) // Text colors
    );
}
add_action( 'admin_init', 'my_custom_color_scheme' );

Deprecations & Breaking Changes

To modernize the codebase, 3.3 deprecated several legacy features, requiring developers to update their plugins/themes.

6.1 Deprecated jQuery Methods: .live() and .die()

As noted earlier, jQuery 1.7 deprecated .live() (event delegation) and .die() (removing delegated events) in favor of .on() and .off(). WordPress 3.3 logged warnings for these methods, pushing developers to refactor.

6.2 Legacy Widget APIs: Moving to WP_Widget Class

The old procedural widget APIs (register_sidebar_widget(), register_widget_control()) were deprecated in favor of the object-oriented WP_Widget class. Plugins using the old APIs would throw _deprecated_function() warnings.

6.3 Thickbox: The Beginning of the End

While still included, Thickbox (a modal library) began showing signs of obsolescence. WordPress 3.3 encouraged developers to use wpColorPicker and other native widgets instead, foreshadowing its removal in 3.5.

Migration Tips: Upgrading to 3.3

For developers upgrading from 3.2 to 3.3:

  1. Update jQuery Code: Replace .live()/.die() with .on()/.off().
  2. Enqueue Responsibly: Use admin_enqueue_scripts for admin assets and declare dependencies.
  3. Adopt wpColorPicker: Replace custom color pickers with the native widget.
  4. Check Deprecations: Scan for _deprecated_function() warnings and update legacy widget code to WP_Widget.
  5. Adjust CSS for Admin Bar: Add padding-top: 28px to body.admin-bar to prevent content clipping.

Conclusion

WordPress 3.3 may not have been a headline-grabbing release, but its focus on developer experience laid critical groundwork for future innovation. By modernizing JavaScript, refining the admin UI, and introducing native tools like wpColorPicker, it empowered developers to build more consistent, maintainable solutions.

Whether you’re maintaining a legacy plugin or building a new theme, understanding these changes ensures compatibility and unlocks the full potential of WordPress’s evolving ecosystem.

References