Программное добавление виджетов в сайдбары

Когда я начинал этот ответ, он должен был быть просто небольшой заметкой. Что ж, у меня не получилось! Извините! Оставайтесь со мной, в глубине текста спрятано кое-что интересное...

Как виджеты WordPress хранятся

Список виджетов хранится в опции с именем 'sidebars_widgets'. Результат var_export() может выглядеть примерно так:

array (
  'wp_inactive_widgets' => 
  array (
  ),
  'top-widget' => 
  array (
  ),
  'bottom-widget' => 
  array (
  ),
  'array_version' => 3,
)

Игнорируйте 'wp_inactive_widgets' и 'array_version'. Нам не нужно о них беспокоиться.
Остальные ключи — это идентификаторы зарегистрированных областей виджетов. В данном случае области могли быть зарегистрированы таким кодом:

// Регистрируем две области виджетов.
$sidebars = array ( 'a' => 'top-widget', 'b' => 'bottom-widget' );
foreach ( $sidebars as $sidebar )
{
    register_sidebar(
        array (
            'name'          => $sidebar,
            'id'            => $sidebar,
            'before_widget' => '',
            'after_widget'  => ''
        )
    );
}

По умолчанию после регистрации области виджетов пусты. Конечно же.

Для каждого зарегистрированного класса виджета создается отдельная опция, содержащая все необходимые настройки. Имя опции начинается с префикса widget_. Чтобы получить настройки всех активных RSS-виджетов, нужно обратиться к...

get_option( 'widget_rss' );

Возможный вывод:

array (
  2 => 
  array (
    'title' => 'WordPress Stack Exchange',
    'url' => 'http://wordpress.stackexchange.com/feeds',
    'link' => 'http://wordpress.stackexchange.com/questions',
    'items' => 5,
    'show_summary' => 1,
    'show_author' => 0,
    'show_date' => 0,
  ),
)

Обратите внимание на число 2. Параметры для нескольких экземпляров виджета хранятся в одной опции и упорядочены по номерам.

Чтобы увидеть, какие классы виджетов уже известны WordPress, перейдите в wp-admin/options.php и прокрутите вниз до раздела, похожего на этот:

Да, это сериализованные данные. Нет, вы не сможете их прочитать здесь. Но не беспокойтесь, вам и не нужно.

Демо-виджет

Чтобы лучше проиллюстрировать внутреннюю работу, я написал очень простой демо-виджет:

/**
 * Очень простой виджет.
 */
class T5_Demo_Widget extends WP_Widget
{
    public function __construct()
    {                      // id_base        ,  видимое имя
        parent::__construct( 't5_demo_widget', 'T5 Demo Widget' );
    }

    public function widget( $args, $instance )
    {
        echo $args['before_widget'], wpautop( $instance['text'] ), $args['after_widget'];
    }

    public function form( $instance )
    {
        $text = isset ( $instance['text'] )
            ? esc_textarea( $instance['text'] ) : '';
        printf(
            '<textarea class="widefat" rows="7" cols="20" id="%1$s" name="%2$s">%3$s</textarea>',
            $this->get_field_id( 'text' ),
            $this->get_field_name( 'text' ),
            $text
        );
    }
}

Обратите внимание на конструктор: 't5_demo_widget' — это $id_base, идентификатор этого виджета. Как видно на скриншоте, его параметры хранятся в опции widget_t5_demo_widget. Все ваши пользовательские виджеты будут обрабатываться аналогично. Вам не нужно угадывать имя. И поскольку вы написали свои виджеты (вероятно), вы знаете все аргументы из параметров $instance вашего класса.

Основы темы

Сначала нужно зарегистрировать области виджетов и пользовательский виджет. Подходящий экшен для этого легко запомнить: 'widgets_init'. Поместите всё в контейнер — класс или функцию. Для простоты я использую функцию с именем t5_default_widget_demo().

Весь следующий код добавляется в functions.php. Класс T5_Demo_Widget должен быть уже загружен. Я просто поместил его в тот же файл...

add_action( 'widgets_init', 't5_default_widget_demo' );

function t5_default_widget_demo()
{
    // Регистрируем наш виджет.
    register_widget( 'T5_Demo_Widget' );

    // Регистрируем две области виджетов.
    $sidebars = array ( 'a' => 'top-widget', 'b' => 'bottom-widget' );
    foreach ( $sidebars as $sidebar )
    {
        register_sidebar(
            array (
                'name'          => $sidebar,
                'id'            => $sidebar,
                'before_widget' => '',
                'after_widget'  => ''
            )
        );
    }

Пока всё просто. Наша тема теперь готова для виджетов, демо-виджет зарегистрирован. Теперь самое интересное.

$active_widgets = get_option( 'sidebars_widgets' );

if ( ! empty ( $active_widgets[ $sidebars['a'] ] )
    or ! empty ( $active_widgets[ $sidebars['b'] ] )
)
{   // Окей, веселье закончилось. Здесь уже есть контент.
    return;
}

Вы действительно не хотите уничтожить пользовательские настройки. Если в областях виджетов уже есть контент, ваш код не должен его перезаписывать. Поэтому мы останавливаемся в этом случае.

Хорошо, предположим, что области виджетов пусты... нам нужен счётчик:

$counter = 1;

Виджеты нумеруются. Эти номера являются вторыми идентификаторами для WordPress.

Получим массив для изменения:

$active_widgets = get_option( 'sidebars_widgets' );

Нам также нужен счётчик (подробнее об этом позже):

$counter = 1;

Вот как мы используем счётчик, имена областей и аргументы виджета (ну, у нас только один аргумент: text).

// Добавляем демо-виджет в верхнюю область...
$active_widgets[ $sidebars['a'] ][0] = 't5_demo_widget-' . $counter;
// ... и записываем в него текст:
$demo_widget_content[ $counter ] = array ( 'text' => "Это работает!\n\nУдивительно!" );

$counter++;

Обратите внимание, как создаётся идентификатор виджета: id_base, минус - и счётчик. Содержимое виджета хранится в другой переменной $demo_widget_content. Здесь счётчик является ключом, а аргументы виджета хранятся в массиве.

Мы увеличиваем счётчик на единицу после завершения, чтобы избежать коллизий.

Это было легко. Теперь RSS-виджет. Больше полей, больше веселья!

$active_widgets[ $sidebars['a'] ][] = 'rss-' . $counter;
// Последние 15 вопросов с WordPress Stack Exchange.
$rss_content[ $counter ] = array (
    'title'        => 'WordPress Stack Exchange',
    'url'          => 'http://wordpress.stackexchange.com/feeds',
    'link'         => 'http://wordpress.stackexchange.com/questions',
    'items'        => 15,
    'show_summary' => 0,
    'show_author'  => 1,
    'show_date'    => 1,
);
update_option( 'widget_rss', $rss_content );

$counter++;

Здесь кое-что новое: update_option() сохранит аргументы RSS-виджета в отдельной опции. WordPress автоматически найдёт их позже.
Мы не сохраняли аргументы демо-виджета, потому что добавляем второй экземпляр во вторую область...

// Хорошо, теперь наша вторая область. Сделаем это кратко.
$active_widgets[ $sidebars['b'] ][] = 't5_demo_widget-' . $counter;
#$demo_widget_content = get_option( 'widget_t5_demo_widget', array() );
$demo_widget_content[ $counter ] = array ( 'text' => 'Второй экземпляр нашего удивительного демо-виджета.' );
update_option( 'widget_t5_demo_widget', $demo_widget_content );

... и сохраняем все аргументы для t5_demo_widget за один раз. Нет необходимости обновлять одну и ту же опцию дважды.

Ну, хватит виджетов на сегодня, давайте сохраним и sidebars_widgets:

update_option( 'sidebars_widgets', $active_widgets );

Теперь WordPress будет знать, что есть зарегистрированные виджеты и где хранятся аргументы для каждого виджета. Результат var_export() для sidebar_widgets будет выглядеть так:

array (
  'wp_inactive_widgets' => 
  array (
  ),
  'top-widget' => 
  array (
    0 => 't5_demo_widget-1',
    1 => 'rss-2',
  ),
  'bottom-widget' => 
  array (
    0 => 't5_demo_widget-3',
  ),
  'array_version' => 3,
)

Полный код снова:

add_action( 'widgets_init', 't5_default_widget_demo' );

function t5_default_widget_demo()
{
    // Регистрируем наш виджет.
    register_widget( 'T5_Demo_Widget' );

    // Регистрируем две области виджетов.
    $sidebars = array ( 'a' => 'top-widget', 'b' => 'bottom-widget' );
    foreach ( $sidebars as $sidebar )
    {
        register_sidebar(
            array (
                'name'          => $sidebar,
                'id'            => $sidebar,
                'before_widget' => '',
                'after_widget'  => ''
            )
        );
    }

    // Хорошо, теперь самое интересное.

    // Мы не хотим отменять пользовательские изменения, поэтому сначала проверим их.
    $active_widgets = get_option( 'sidebars_widgets' );

    if ( ! empty ( $active_widgets[ $sidebars['a'] ] )
        or ! empty ( $active_widgets[ $sidebars['b'] ] )
    )
    {   // Окей, веселье закончилось. Здесь уже есть контент.
        return;
    }

    // Области виджетов пусты, давайте добавим в них что-нибудь.
    // Например, RSS-виджет и два экземпляра нашего демо-виджета?

    // Виджеты нумеруются. Нам нужен счётчик:
    $counter = 1;

    // Добавляем демо-виджет в верхнюю область...
    $active_widgets[ $sidebars['a'] ][0] = 't5_demo_widget-' . $counter;
    // ... и записываем в него текст:
    $demo_widget_content[ $counter ] = array ( 'text' => "Это работает!\n\nУдивительно!" );
    #update_option( 'widget_t5_demo_widget', $demo_widget_content );

    $counter++;

    // Это было легко. Теперь RSS-виджет. Больше полей, больше веселья!
    $active_widgets[ $sidebars['a'] ][] = 'rss-' . $counter;
    // Последние 15 вопросов с WordPress Stack Exchange.
    $rss_content[ $counter ] = array (
        'title'        => 'WordPress Stack Exchange',
        'url'          => 'http://wordpress.stackexchange.com/feeds',
        'link'         => 'http://wordpress.stackexchange.com/questions',
        'items'        => 15,
        'show_summary' => 0,
        'show_author'  => 1,
        'show_date'    => 1,
    );
    update_option( 'widget_rss', $rss_content );

    $counter++;

    // Хорошо, теперь наша вторая область. Сделаем это кратко.
    $active_widgets[ $sidebars['b'] ][] = 't5_demo_widget-' . $counter;
    #$demo_widget_content = get_option( 'widget_t5_demo_widget', array() );
    $demo_widget_content[ $counter ] = array ( 'text' => 'Второй экземпляр нашего удивительного демо-виджета.' );
    update_option( 'widget_t5_demo_widget', $demo_widget_content );

    // Теперь сохраняем массив $active_widgets.
    update_option( 'sidebars_widgets', $active_widgets );
}

Если вы перейдёте в wp-admin/widgets.php, то увидите три предустановленных виджета:

И это всё. Используйте...

dynamic_sidebar( 'top-widget' );
dynamic_sidebar( 'bottom-widget' );

... чтобы вывести виджеты на экран.

Есть небольшой нюанс: для первоначальной регистрации нужно загрузить фронтенд дважды. Если кто-то может помочь с этим, я буду очень благодарен.