Come aggiungere impostazioni personalizzate a un widget esistente in WordPress

In questo post impareremo come aggiungere il tuo HTML personalizzato e le impostazioni a qualsiasi widget standard di WordPress o altri. Usando queste impostazioni impareremo diversi trucchi su come manipolare il comportamento dei widget di conseguenza.

La prima parte; aggiungere e salvare le impostazioni personalizzate è abbastanza semplice. La seconda parte dipende da cosa si vuole fare nello specifico e da quale widget si sta manipolando. In questo post ho incluso due esempi; saltare un widget in base a un’impostazione (per aggiungere impostazioni per controllare la visibilità del widget in determinati casi) e manipolare gli argomenti del menu del widget di navigazione di WordPress. L’esempio fornito per la seconda parte dovrebbe darti un buon indizio su come puoi gestire ciò che vuoi fare.

Aggiunta di impostazioni personalizzate a qualsiasi widget

Per aggiungere impostazioni personalizzate ai widget esistenti utilizziamo un’azione chiamata [in_widget_form](https://developer.wordpress.org/reference/hooks/in_widget_form/). Questa azione viene applicata alla funzione di tutti i widget form(), che è la funzione responsabile del rendering della parte amministrativa del widget.

Con quel filtro otteniamo tre parametri ma in realtà ci interessano solo il primo e il terzo. La prima è l’istanza del widget che useremo per recuperare i nomi e gli ID dei campi appropriati e (facoltativamente) verificare a quale tipo di widget siamo agganciati. Il terzo parametro è un array delle impostazioni salvate del widget, che dobbiamo usare per controllare lo stato salvato in precedenza delle nostre impostazioni.

Il codice seguente aggiungerà una casella di controllo con il nome dell’impostazione ‘ awp-custom-setting‘. Regola il nome e l’HTML in base all’input di cui hai bisogno. Ciò che è importante è utilizzare $widget->get_field_name()per aggiungere ID e attributi appropriati namea tutti i tuoi input. Il valore dei tuoi input dovrebbe essere popolato con ciò che è stato salvato in precedenza, e questo è qualcosa che troverai nel parametro $instance. Per le caselle di controllo puoi utilizzare la funzione di WordPress [checked](https://developer.wordpress.org/reference/functions/checked/)()per generare l’attributo selezionato.

Dopo averlo aggiunto al functions.phpcodice del tuo tema o del plug-in, tutti i widget dovrebbero ora ottenere una casella di controllo alla fine del loro modulo in admin.

Scegli come target widget specifici

Se vuoi applicare le tue impostazioni solo a uno o ad alcuni widget specifici puoi confrontare la proprietà id_basenell’oggetto $widget. Avrai bisogno di sapere che l’ID di base è: se non sei sicuro, fai semplicemente un var_dump($widget->id_base)inside the hook, salva e controlla l’output per ogni widget in admin. Ad esempio, il widget di navigazione ha la base ID nav_menue il widget Archivi ha archives.

Nell’esempio seguente controlliamo se il widget è un widget di navigazione. In caso contrario, la funzione viene annullata con un return. Solo i widget di navigazione riceveranno la casella di controllo personalizzata:

Dovresti ottenere l’impostazione in admin in questo modo:

Quindi l’impostazione è stata aggiunta, tuttavia al momento le tue impostazioni non vengono salvate. Risolviamolo.

Salvataggio delle impostazioni personalizzate

Dobbiamo collegarci alla update()funzione del widget per aggiornare le nostre impostazioni personalizzate.

Per questo utilizziamo il filtro [widget_update_callback](https://developer.wordpress.org/reference/hooks/widget_update_callback/). Il processo di salvataggio delle nostre impostazioni è esattamente come faresti quando scrivi una classe widget. Il filtro fornisce tre parametri; il primo è l’array di istanza che verrà salvato. Il secondo parametro è lo stato che è stato inviato al salvataggio del widget e il terzo è il vecchio stato. Dobbiamo assicurarci di recuperare i nostri nuovi valori dal secondo parametro e aggiungerli al primo.

Questo è il modo in cui aggiorneremmo lo stato della nostra casella di controllo; come vogliamo salvare un valore trueo false:

add_filter('widget_update_callback', function($instance, $new_instance, $old_instance) {
    $instance['awp-custom-setting'] = isset($new_instance['awp-custom-setting']);
    return $instance;
}, 10, 3);

Ricordarsi di adattare i nomi di input ai propri nomi di impostazione. Se stai aggiungendo più input, devi ripetere l’operazione per ciascuno.

Ora dovresti vedere che le tue impostazioni personalizzate vengono salvate in admin!

Utilizzo delle impostazioni del widget personalizzate salvate

Come accennato in precedenza, questa parte dipende davvero da cosa vuoi che facciano le tue impostazioni. Sfortunatamente non è così semplice perché la maggior parte dei widget non aggiunge filtri o hook nei loro output. Cominciamo con qualcosa di semplice; evitare di eseguire il rendering del widget a seconda delle impostazioni.

Impedisci il rendering del widget in base all’impostazione personalizzata

Supponi di aggiungere impostazioni per quando il widget dovrebbe essere visibile; ad esempio nascondendolo in determinati modelli (nascondi nel modello dei risultati di ricerca, ma mostra in prima pagina e singolo) o reagisci ad altri stati di WordPress.

Per questo possiamo usare il filtro [widget_display_callback](https://developer.wordpress.org/reference/hooks/widget_display_callback/). Tutto quello che dobbiamo fare è controllare il parametro di istanza fornito per la nostra impostazione e tornare falsese non vogliamo eseguire il rendering del widget.

Questo semplice codice eviterà il rendering del widget se la casella di controllo personalizzata che abbiamo aggiunto sopra è selezionata:

add_filter('widget_display_callback', function($instance, $widget, $args) {
    if ($instance['awp-custom-setting']) {
        return false;
    }
    return $instance;
}, 10, 3);

Probabilmente vuoi confrontare altri stati. Questo è un semplice esempio in cui la nostra casella di controllo è una casella di controllo per "Nascondi nelle visualizzazioni di post singoli". Verifichiamo semplicemente se ci troviamo attualmente in una visualizzazione di un singolo post con [is_singular](https://developer.wordpress.org/reference/functions/is_singular/)()e se la casella di controllo è selezionata, restituiamo false.

add_filter('widget_display_callback', function($instance, $widget, $args) {
    if (is_singular() && $instance['awp-custom-setting']) {
        return false;
    }
    return $instance;
}, 10, 3);

Modifica delle impostazioni o dell’output del widget esistente

Un potente filtro da utilizzare per giocare con i widget esistenti è [dynamic_sidebar_params](https://developer.wordpress.org/reference/hooks/dynamic_sidebar_params/). Dai un’occhiata alla pagina della documentazione per vedere quali parametri puoi modificare. Ad esempio puoi aggiungere classi personalizzate, puoi modificare le stringhe before_widgetHTML o after_widget. Tuttavia questo vale per tutti i widget, anche admin e frontend. E con questo filtro non hai accesso all’istanza del widget (impostazioni salvate) o alle impostazioni del widget (es. tipo di widget).before_title``after_title

Ovviamente dobbiamo almeno controllare le nostre impostazioni personalizzate. Quindi abbiamo bisogno di fare un po’ di codice per recuperare i valori di cui abbiamo bisogno.

La prima cosa che possiamo fare è accedere a una variabile globale $wp_registered_widgets. Questo è un array che contiene tutti i widget disponibili e registrati. Usando quel registro possiamo usare il parametro del filtro per trovare il widget specifico in cui ci troviamo attualmente. Una volta trovato il widget corrente, abbiamo accesso ai parametri del widget, come id_base– che come abbiamo visto prima ci dice il tipo di widget.

Come puoi vedere in linea #9possiamo finalmente verificare a quale tipo di widget ci troviamo attualmente. Nel codice sopra torno se il tipo di widget non è un widget di navigazione poiché la nostra impostazione personalizzata è stata aggiunta solo per quei widget.

Recupero delle impostazioni del widget salvate

Ma dobbiamo anche recuperare le impostazioni salvate per widget (inclusa la nostra impostazione personalizzata). Tutte le impostazioni salvate dei widget vengono archiviate nel database delle opzioni raggruppate per tipo di widget. Utilizzando una proprietà nel registro dei widget possiamo utilizzare [get_option](https://developer.wordpress.org/reference/functions/get_option/)()per recuperare le impostazioni salvate per il tipo di widget corrente. Il ritorno sarà un array indicizzato in cui è necessario utilizzare un altro parametro del filtro per trovare l’indice corrente (perché è possibile aggiungere più widget dello stesso tipo nella stessa barra laterale o in diverse barre laterali). È più facile mostrarlo con il codice che spiegarlo:

Finalmente otteniamo le impostazioni salvate del widget! Nel codice di esempio sopra, alla riga #9, controlliamo se la nostra casella di controllo personalizzata è selezionata o meno.

Esempi

A questo punto, sta a te cosa vuoi fare. Ad esempio, puoi eseguire il rendering di un output dopo il titolo del widget, ma prima del contenuto del widget:

Per casi d’uso più reali, normalmente risolveresti la maggior parte aggiungendo determinati filtri a questo punto, chiamando add_filter()a questo punto.

Di seguito è riportato un esempio di modifica degli argomenti del menu di navigazione aggiungendo un filtro se la nostra impostazione è stata selezionata. Se era deselezionato, ci assicuriamo che il filtro sia stato rimosso. Il filtro per modificare gli argomenti per il rendering di un menu di navigazione è widget_nav_menu_args. Nel codice seguente ho definito una funzione da applicare a questo filtro che aggiunge un nuovo argomento agli argomenti del menu; un camminatore:

    ...
    if ($saved_settings['my-custom-thing']) {
        add_filter('widget_nav_menu_args', 'awp_add_menu_walker', 10, 3);
    } else {
        remove_filter('widget_nav_menu_args', 'awp_add_menu_walker', 10);
    }
    return $params;
});
function awp_add_menu_walker($nav_menu_args, $nav_menu, $args) {
    $nav_menu_args['walker'] = new AWP_Custom_Walker();
    return $nav_menu_args;
}

Il codice sopra è un esempio di un caso d’uso in cui la casella di controllo personalizzata controlla se applicare o meno un menu walker al menu. Eccellente se si desidera che tutti i menu vengano visualizzati normalmente ma si desidera che l’opzione per widget di menu specifici venga visualizzata in modo diverso. Quello che fa il walker con l’output del menu dipende da te.

Vedi sotto per il codice completo per aggiungere un’impostazione personalizzata a tutti i menu di navigazione, aggiornarla e applicare un menu walker.

Si spera che questo sia sufficiente per capire come programmare ciò che si desidera fare. Dipende davvero da cosa vuoi fare e dal tipo di widget con cui stai lavorando. Come accennato in precedenza, di solito la maggior parte delle modifiche può essere risolta aggiungendo filtri per fare le tue cose in dynamic_sidebar_params.

Esempio completo: impostazione della casella di controllo personalizzata sui widget di navigazione per l’applicazione di un menu walker

Ecco il codice completo per aggiungere una casella di controllo personalizzata a tutti i widget del menu di navigazione di WordPress per l’utilizzo di un menu walker registrato. (Codice Walker non incluso)

Conclusione

Spero che questo post sia stato utile per risolvere le tue esigenze o darti alcuni suggerimenti su come puoi fare ciò che devi fare!