Agregar widgets a las barras laterales programáticamente

Cuando comencé esta respuesta debería ser solo una pequeña nota. Bueno, fallé. ¡Lo siento! Quédate conmigo, hay un regalo escondido en lo profundo...

Cómo se almacenan los widgets de WordPress

La lista de widgets se almacena en una opción llamada 'sidebars_widgets'. Un var_export() puede dar algo como lo siguiente:

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

Ignora 'wp_inactive_widgets' y 'array_version'. No tenemos que preocuparnos por esos.
Las otras claves son identificadores para las barras laterales registradas. En este caso, las barras laterales pueden haberse registrado con este código:

// Registrar dos barras laterales.
$sidebars = array ( 'a' => 'top-widget', 'b' => 'bottom-widget' );
foreach ( $sidebars as $sidebar )
{
    register_sidebar(
        array (
            'name'          => $sidebar,
            'id'            => $sidebar,
            'before_widget' => '',
            'after_widget'  => ''
        )
    );
}

Por defecto, las barras laterales están vacías después del registro. Por supuesto.

Para cada clase de widget registrada se crea una opción separada, que contiene todas las opciones necesarias. La opción tiene el prefijo de la cadena widget_. Para obtener las opciones de todos los widgets RSS activos tenemos que mirar en...

get_option( 'widget_rss' );

Posible salida:

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,
  ),
)

Observa el número 2. Los argumentos para múltiples instancias se almacenan todos en esta opción ordenados por números.

Para ver qué clases de widget ya son conocidas por WordPress ve a wp-admin/options.php y desplázate hacia abajo hasta que veas algo como esto:

Sí, datos serializados. No, no puedes leerlos aquí. No te preocupes, no tienes que hacerlo.

Un widget de demostración

Para ilustrar mejor el funcionamiento interno he escrito un widget de demostración muy simple:

/**
 * Widget super simple.
 */
class T5_Demo_Widget extends WP_Widget
{
    public function __construct()
    {                      // id_base        ,  nombre visible
        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
        );
    }
}

Observa el constructor: 't5_demo_widget' es el $id_base, el identificador para este widget. Como puedes ver en la captura de pantalla, sus argumentos se almacenan en la opción widget_t5_demo_widget. Todos tus widgets personalizados serán tratados así. No tienes que adivinar el nombre. Y dado que tú has escrito tus widgets (probablemente) conoces todos los argumentos de los parámetros $instance de tu clase.

Conceptos básicos del tema

Primero tienes que registrar algunas barras laterales y el widget personalizado. La acción adecuada para esto es fácil de recordar: 'widgets_init'. Pon todo en un contenedor: una clase o una función. Por simplicidad usaré una función llamada t5_default_widget_demo().

Todo el siguiente código va en el functions.php. La clase T5_Demo_Widget debería estar cargada ya. Simplemente la pongo en el mismo archivo...

add_action( 'widgets_init', 't5_default_widget_demo' );

function t5_default_widget_demo()
{
    // Registrar nuestro propio widget.
    register_widget( 'T5_Demo_Widget' );

    // Registrar dos barras laterales.
    $sidebars = array ( 'a' => 'top-widget', 'b' => 'bottom-widget' );
    foreach ( $sidebars as $sidebar )
    {
        register_sidebar(
            array (
                'name'          => $sidebar,
                'id'            => $sidebar,
                'before_widget' => '',
                'after_widget'  => ''
            )
        );
    }

Hasta aquí, todo simple. Nuestro tema ahora está listo para widgets, el widget de demostración es conocido. Ahora la diversión.

$active_widgets = get_option( 'sidebars_widgets' );

if ( ! empty ( $active_widgets[ $sidebars['a'] ] )
    or ! empty ( $active_widgets[ $sidebars['b'] ] )
)
{   // Vale, no más diversión. Ya hay algún contenido.
    return;
}

Realmente no quieres destruir la configuración del usuario. Si ya hay algún contenido en las barras laterales, tu código no debería sobrescribirlo. Por eso nos detenemos en este caso.

Vale, asumiendo que las barras laterales están vacías... necesitamos un contador:

$counter = 1;

Los widgets están numerados. Estos números son segundos identificadores para WordPress.

Obtenemos el array para cambiarlo:

$active_widgets = get_option( 'sidebars_widgets' );

También necesitamos un contador (más sobre esto más adelante):

$counter = 1;

Y así es como usamos el contador, los nombres de las barras laterales y los argumentos del widget (bueno, solo tenemos un argumento: text).

// Añadir un widget 'demo' a la barra lateral superior...
$active_widgets[ $sidebars['a'] ][0] = 't5_demo_widget-' . $counter;
// ... y escribir algo de texto en él:
$demo_widget_content[ $counter ] = array ( 'text' => "¡Esto funciona!\n\n¡Increíble!" );

$counter++;

Observa cómo se crea el identificador del widget: el id_base, un guión - y el contador. El contenido del widget se almacena en otra variable $demo_widget_content. Aquí el contador es la clave y los argumentos del widget se almacenan en un array.

Incrementamos el contador en uno cuando terminamos para evitar colisiones.

Eso fue fácil. Ahora un widget RSS. ¡Más campos, más diversión!

$active_widgets[ $sidebars['a'] ][] = 'rss-' . $counter;
// Las últimas 15 preguntas de 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++;

Aquí hay algo nuevo: update_option() esto almacenará los argumentos del widget RSS en una opción separada. WordPress encontrará estos automáticamente más tarde.
No guardamos los argumentos del widget de demostración porque añadimos una segunda instancia a nuestra segunda barra lateral ahora...

// Vale, ahora a nuestra segunda barra lateral. Lo hacemos breve.
$active_widgets[ $sidebars['b'] ][] = 't5_demo_widget-' . $counter;
#$demo_widget_content = get_option( 'widget_t5_demo_widget', array() );
$demo_widget_content[ $counter ] = array ( 'text' => 'La segunda instancia de nuestro increíble widget de demostración.' );
update_option( 'widget_t5_demo_widget', $demo_widget_content );

... y guardamos todos los argumentos para el t5_demo_widget de una vez. No hay necesidad de actualizar la misma opción dos veces.

Bueno, suficientes widgets por hoy, guardemos también sidebars_widgets:

update_option( 'sidebars_widgets', $active_widgets );

Ahora WordPress sabrá que hay algunos widgets registrados y dónde se almacenan los argumentos para cada widget. Un var_export() en los sidebar_widgets se verá así:

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,
)

El código completo de nuevo:

add_action( 'widgets_init', 't5_default_widget_demo' );

function t5_default_widget_demo()
{
    // Registrar nuestro propio widget.
    register_widget( 'T5_Demo_Widget' );

    // Registrar dos barras laterales.
    $sidebars = array ( 'a' => 'top-widget', 'b' => 'bottom-widget' );
    foreach ( $sidebars as $sidebar )
    {
        register_sidebar(
            array (
                'name'          => $sidebar,
                'id'            => $sidebar,
                'before_widget' => '',
                'after_widget'  => ''
            )
        );
    }

    // Vale, ahora la parte divertida.

    // No queremos deshacer los cambios del usuario, así que buscamos cambios primero.
    $active_widgets = get_option( 'sidebars_widgets' );

    if ( ! empty ( $active_widgets[ $sidebars['a'] ] )
        or ! empty ( $active_widgets[ $sidebars['b'] ] )
    )
    {   // Vale, no más diversión. Ya hay algún contenido.
        return;
    }

    // Las barras laterales están vacías, pongamos algo en ellas.
    // ¿Qué tal un widget RSS y dos instancias de nuestro widget de demostración?

    // Nota que los widgets están numerados. Necesitamos un contador:
    $counter = 1;

    // Añadir un widget 'demo' a la barra lateral superior...
    $active_widgets[ $sidebars['a'] ][0] = 't5_demo_widget-' . $counter;
    // ... y escribir algo de texto en él:
    $demo_widget_content[ $counter ] = array ( 'text' => "¡Esto funciona!\n\n¡Increíble!" );
    #update_option( 'widget_t5_demo_widget', $demo_widget_content );

    $counter++;

    // Eso fue fácil. Ahora un widget RSS. ¡Más campos, más diversión!
    $active_widgets[ $sidebars['a'] ][] = 'rss-' . $counter;
    // Las últimas 15 preguntas de 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++;

    // Vale, ahora a nuestra segunda barra lateral. Lo hacemos breve.
    $active_widgets[ $sidebars['b'] ][] = 't5_demo_widget-' . $counter;
    #$demo_widget_content = get_option( 'widget_t5_demo_widget', array() );
    $demo_widget_content[ $counter ] = array ( 'text' => 'La segunda instancia de nuestro increíble widget de demostración.' );
    update_option( 'widget_t5_demo_widget', $demo_widget_content );

    // Ahora guardamos el array $active_widgets.
    update_option( 'sidebars_widgets', $active_widgets );
}

Si vas a wp-admin/widgets.php ahora verás tres widgets preestablecidos:

Y eso es todo. Usa...

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

... para mostrar los widgets.

Hay un pequeño problema: Tienes que cargar el front-end dos veces para el registro inicial. Si alguien puede ayudar aquí estaré muy agradecido.