Aggiungere widget alle sidebar programmaticamente

Quando ho iniziato questa risposta doveva essere solo una piccola nota. Beh, ho fallito. Scusate! Seguitemi, c'è una sorpresa nascosta in fondo...

Come vengono memorizzati i widget di WordPress

L'elenco dei widget è memorizzato in un'opzione chiamata 'sidebars_widgets'. Un var_export() potrebbe restituire qualcosa come:

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

Ignorate 'wp_inactive_widgets' e 'array_version'. Non dobbiamo preoccuparci di questi.
Le altre chiavi sono identificatori per le sidebar registrate. In questo caso le sidebar potrebbero essere state registrate con questo codice:

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

Per impostazione predefinita le sidebar sono vuote dopo la registrazione. Ovviamente.

Per ogni classe di widget registrata viene creata un'opzione separata, contenente tutte le opzioni necessarie. L'opzione è prefissata dalla stringa widget_. Per ottenere le opzioni di tutti i widget RSS attivi dobbiamo guardare in...

get_option( 'widget_rss' );

Possibile output:

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

Notate il numero 2. Gli argomenti per più istanze sono tutti memorizzati in questa unica opzione ordinata per numeri.

Per vedere quali classi di widget sono già note a WordPress andate su wp-admin/options.php e scorrete fino a vedere qualcosa come:

Sì, dati serializzati. No, non potete leggerli qui. Non preoccupatevi, non è necessario.

Un widget dimostrativo

Per illustrare meglio il funzionamento interno ho scritto un widget dimostrativo molto semplice:

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

Notate il costruttore: 't5_demo_widget' è l'$id_base, l'identificatore per questo widget. Come potete vedere nello screenshot i suoi argomenti sono memorizzati nell'opzione widget_t5_demo_widget. Tutti i vostri widget personalizzati saranno trattati allo stesso modo. Non dovete indovinare il nome. E dato che voi avete scritto i vostri widget (probabilmente) conoscete tutti gli argomenti dai parametri $instance della vostra classe.

Basi del tema

Per prima cosa dovete registrare alcune sidebar e il widget personalizzato. L'azione corretta per questo è facile da ricordare: 'widgets_init'. Mettete tutto in un contenitore - una classe o una funzione. Per semplicità userò una funzione chiamata t5_default_widget_demo().

Tutto il codice seguente va nel functions.php. La classe T5_Demo_Widget dovrebbe essere già caricata. L'ho semplicemente messa nello stesso file...

add_action( 'widgets_init', 't5_default_widget_demo' );

function t5_default_widget_demo()
{
    // Registra il nostro widget.
    register_widget( 'T5_Demo_Widget' );

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

Fin qui tutto semplice. Il nostro tema è ora pronto per i widget, il widget dimostrativo è noto. Ora il divertimento.

$active_widgets = get_option( 'sidebars_widgets' );

if ( ! empty ( $active_widgets[ $sidebars['a'] ] )
    or ! empty ( $active_widgets[ $sidebars['b'] ] )
)
{   // Ok, niente più divertimento. C'è già del contenuto.
    return;
}

Non volete davvero distruggere le impostazioni dell'utente. Se c'è già del contenuto nelle sidebar il vostro codice non dovrebbe sovrascriverlo. Ecco perché ci fermiamo in questo caso.

Ok, supponendo che le sidebar siano vuote... abbiamo bisogno di un contatore:

$counter = 1;

I widget sono numerati. Questi numeri sono secondi identificatori per WordPress.

Prendiamo l'array per modificarlo:

$active_widgets = get_option( 'sidebars_widgets' );

Abbiamo bisogno anche di un contatore (ne parleremo più avanti):

$counter = 1;

Ed ecco come usiamo il contatore, i nomi delle sidebar e gli argomenti del widget (beh, abbiamo solo un argomento: text).

// Aggiunge un widget 'demo' alla sidebar superiore...
$active_widgets[ $sidebars['a'] ][0] = 't5_demo_widget-' . $counter;
// ... e scrive del testo al suo interno:
$demo_widget_content[ $counter ] = array ( 'text' => "Funziona!\n\nIncredibile!" );

$counter++;

Notate come viene creato l'identificatore del widget: l'id_base, un trattino - e il contatore. Il contenuto del widget è memorizzato in un'altra variabile $demo_widget_content. Qui il contatore è la chiave e gli argomenti del widget sono memorizzati in un array.

Incrementiamo il contatore di uno quando abbiamo finito per evitare collisioni.

Era facile. Ora un widget RSS. Più campi, più divertimento!

$active_widgets[ $sidebars['a'] ][] = 'rss-' . $counter;
// Le ultime 15 domande da 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++;

Ecco qualcosa di nuovo: update_option() questo memorizzerà gli argomenti del widget RSS in un'opzione separata. WordPress li troverà automaticamente più tardi.
Non abbiamo salvato gli argomenti del widget dimostrativo perché aggiungiamo una seconda istanza alla nostra seconda sidebar ora...

// Ok, ora alla nostra seconda sidebar. Facciamola 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 seconda istanza del nostro fantastico widget dimostrativo.' );
update_option( 'widget_t5_demo_widget', $demo_widget_content );

... e salviamo tutti gli argomenti per t5_demo_widget in un colpo solo. Non è necessario aggiornare la stessa opzione due volte.

Bene, abbastanza widget per oggi, salviamo anche sidebars_widgets:

update_option( 'sidebars_widgets', $active_widgets );

Ora WordPress saprà che ci sono alcuni widget registrati e dove sono memorizzati gli argomenti per ogni widget. Un var_export() su sidebar_widgets apparirà così:

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

Ecco il codice completo di nuovo:

add_action( 'widgets_init', 't5_default_widget_demo' );

function t5_default_widget_demo()
{
    // Registra il nostro widget.
    register_widget( 'T5_Demo_Widget' );

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

    // Ok, ora la parte divertente.

    // Non vogliamo annullare le modifiche dell'utente, quindi cerchiamo prima le modifiche.
    $active_widgets = get_option( 'sidebars_widgets' );

    if ( ! empty ( $active_widgets[ $sidebars['a'] ] )
        or ! empty ( $active_widgets[ $sidebars['b'] ] )
    )
    {   // Ok, niente più divertimento. C'è già del contenuto.
        return;
    }

    // Le sidebar sono vuote, inseriamo qualcosa al loro interno.
    // Che ne dite di un widget RSS e due istanze del nostro widget dimostrativo?

    // Notate che i widget sono numerati. Abbiamo bisogno di un contatore:
    $counter = 1;

    // Aggiunge un widget 'demo' alla sidebar superiore...
    $active_widgets[ $sidebars['a'] ][0] = 't5_demo_widget-' . $counter;
    // ... e scrive del testo al suo interno:
    $demo_widget_content[ $counter ] = array ( 'text' => "Funziona!\n\nIncredibile!" );
    #update_option( 'widget_t5_demo_widget', $demo_widget_content );

    $counter++;

    // Era facile. Ora un widget RSS. Più campi, più divertimento!
    $active_widgets[ $sidebars['a'] ][] = 'rss-' . $counter;
    // Le ultime 15 domande da 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++;

    // Ok, ora alla nostra seconda sidebar. Facciamola 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 seconda istanza del nostro fantastico widget dimostrativo.' );
    update_option( 'widget_t5_demo_widget', $demo_widget_content );

    // Ora salva l'array $active_widgets.
    update_option( 'sidebars_widgets', $active_widgets );
}

Se andate su wp-admin/widgets.php ora vedrete tre widget preimpostati:

E questo è tutto. Usate...

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

... per visualizzare i widget.

C'è un piccolo problema: dovete caricare il front-end due volte per la registrazione iniziale. Se qualcuno può aiutare qui sarò molto grato.