WordPress Tutorial Lezioni 6.5. Le Dashboard Widget API

Vediamo adesso come sia semplice con le Widget API manipolare direttamente dal dashboard.
Aggiungere un Dashboard Widget è realmente molto semplice la funzione da utilizzare è la seguente

wp_add_dashboard_widget ($ WIDGET_ID, $ WIDGET_NAME, $ callback, $ control_callback = null)

dove

• $widget_id identifica lo slug per il widget ed è la chiave che lo identifica.
• $widget_name questo è il nome del tuo widget che sarà visulizzato nella sua testata.
• $callback il nome della funzione che verrà creata e che visualizzerà il contenuto del widget.
• $control_callback rappresenta il nome di una funzione per la gestione delle opzioni del form widget e del suo contenuto.

Per attivare la dashboard widget bisogna utilizzare il gancio “wp_dashboard_setup” , vediamo subito come fare con questo semplice esempio.

/**
 * Aggiungere un Widget Esempio
 *
 * This function is hooked into the 'wp_dashboard_setup' action below.
 */
function esempio_aggiungi_dashboard_widgets() {

wp_add_dashboard_widget(
 'esempio_dashboard_widget', // Widget slug.
 'Esempio Dashboard Widget', // Titolo.
 'esempio_dashboard_widget_funzione' // Visualizza la funzione
 ); 
}
add_action( 'wp_dashboard_setup', 'esempio_aggiungi_dashboard_widgets' );

/**
* Crea la funzione per visualizzare l'output
*/

function esempio_dashboard_widget_funzione() {


 echo "Ciao benvenuto nella mia nuova Widget";
}

Ma volendo con le Widget Api è anche possibile rimuovere per fare wiesto basterà utilizzare la funzione remove_meta_box() ecco una panoramica abbastanza esaustiva da utilizzare sia nei temi che nei plugins. che evidenzia ogni dashboard che volete togliere o aggiungere.

function remove_dashboard_meta() {
 remove_meta_box( 'dashboard_incoming_links', 'dashboard', 'normal' );
 remove_meta_box( 'dashboard_plugins', 'dashboard', 'normal' );
 remove_meta_box( 'dashboard_primary', 'dashboard', 'side' );
 remove_meta_box( 'dashboard_secondary', 'dashboard', 'normal' );
 remove_meta_box( 'dashboard_quick_press', 'dashboard', 'side' );
 remove_meta_box( 'dashboard_recent_drafts', 'dashboard', 'side' );
 remove_meta_box( 'dashboard_recent_comments', 'dashboard', 'normal' );
 remove_meta_box( 'dashboard_right_now', 'dashboard', 'normal' );
 remove_meta_box( 'dashboard_activity', 'dashboard', 'normal');//since 3.8
}
add_action( 'admin_init', 'remove_dashboard_meta' );

Per la precisione se volete è anche possibile utilizzare add_meta_box al posto della funzione wp_add_dashboard_widget nel seguente modo

add_meta_box( 'id', 'Dashboard Widget Title', 'dash_widget', 'dashboard', 'side', 'high' );

dove il parametro da mettere obbligatoriamente è dasboard.

Ci sono anche altri metodi particolari che vengono utilizzati per la creazione di una Widget Dashboard ma i principali comunque sono quelli elencati.

Ecco un elenco abbastanza esaustivo dei meta boxes e di come accedervi

// Main column (left):
$wp_meta_boxes['dashboard']['normal']['high']['dashboard_browser_nag']
$wp_meta_boxes['dashboard']['normal']['core']['dashboard_right_now']
$wp_meta_boxes['dashboard']['normal']['core']['dashboard_activity']

// Side Column (right):
$wp_meta_boxes['dashboard']['side']['core']['dashboard_quick_press']
$wp_meta_boxes['dashboard']['side']['core']['dashboard_primary']

E oer esempio per rimuovere il metabox quickpress dovremmo fare.

// Create the function to use in the action hook
function example_remove_dashboard_widget() {
 	remove_meta_box( 'dashboard_quick_press', 'dashboard', 'side' );
} 
 
// Hook into the 'wp_dashboard_setup' action to register our function
add_action('wp_dashboard_setup', 'example_remove_dashboard_widget' );

————————————————————————————

 
Vediamo adesso quindi alcuni esempi. Nel prossimo vedremo come ottenere opzioni a seconda di alcuni settaggi

/**
 * Ottiene tutte le opzioni sui widget o soltato di alcuni selezionatiGets all widget options, or only options *for a specified widget if a widget id is provided.
*/


public static function get_dashboard_widget_options( $widget_id='' )
{
 //prendi tutte le opzioni di widget di Dashboard dal db ...
 $opts = get_option( 'dashboard_widget_options' );

//Se nessun widget è specificato non prendere nulla
 if ( empty( $widget_id ) )
 return $opts;

//Se la richiesta esiste prendi essa
 if ( isset( $opts[$widget_id] ) )
 return $opts[$widget_id];

//Something went wrong...
 return false;
}

Mentre per portare unicamente singole opzioni questa è la funzione da utilizzare

/**
 * Gets one specific option for the specified widget.
 * @param $widget_id
 * @param $option
 * @param null $default
 *
 * @return string
 */
public static function get_dashboard_widget_option( $widget_id, $option, $default=NULL ) {

$opts = get_dashboard_widget_options($widget_id);

//If widget opts dont exist, return false
 if ( ! $opts )
 return false;

//Otherwise fetch the option or use default
 if ( isset( $opts[$option] ) && ! empty($opts[$option]) )
 return $opts[$option];
 else
 return ( isset($default) ) ? $default : false;

}

Opzioni di Aggiornamento del Widget API

Questa funzione può essere utilizzata per aggiornare facilmente tutte le opzioni di un Widget. Può anche essere usato per aggiungere un widget opzione non distruttivo. È sufficiente impostare l’argomento $ add_option al vero, e questo non cancella tutte le opzioni esistenti (anche se sarà aggiungere qualsiasi quelli mancanti).

/**
 * Saves an array of options for a single dashboard widget to the database.
 * Can also be used to define default values for a widget.
 *
 * @param string $widget_id The name of the widget being updated
 * @param array $args An associative array of options being saved.
 * @param bool $add_only Set to true if you don't want to override any existing options.
 */
public static function update_dashboard_widget_options( $widget_id , $args=array(), $add_only=false )
{
 //Fetch ALL dashboard widget options from the db...
 $opts = get_option( 'dashboard_widget_options' );

//Get just our widget's options, or set empty array
 $w_opts = ( isset( $opts[$widget_id] ) ) ? $opts[$widget_id] : array();

if ( $add_only ) {
 //Flesh out any missing options (existing ones overwrite new ones)
 $opts[$widget_id] = array_merge($args,$w_opts);
 }
 else {
 //Merge new options with existing ones, and add it back to the widgets array
 $opts[$widget_id] = array_merge($w_opts,$args);
 }

//Save the entire widgets array back to the db
 return update_option('dashboard_widget_options', $opts);
}