API pentru piese (widget) în tabloul de bord WordPress

API pentru piese în tabloul de bord (adăugat în WP 2.7) simplifică adăugarea de noi piese la tabloul de bord de administrare. Pentru aceasta este nevoie de cunoștințe de PHP și API pentru module WordPress, dar pentru a implementa un modul sau temă autorii familiarizați cu cârlige și filtre au nevoie doar câteva minute și poate fi o modalitate foarte bună de a face modulul chiar mai util.

Prezentare generală

Funcția

Principalul instrument necesar pentru a adăuga piese la tabloul de bord este funcția wp_add_dashboard_widget().

Utilizare:

wp_add_dashboard_widget( $widget_id, $widget_name, $callback, $control_callback = null )

• $widget_id – un slug de identificare pentru widget. Acesta va fi utilizat drept clasa CSS și cheia în matriceA de widget-uri.
• $widget_name – acesta este numele widget-ului care va fi afișat în poziția specifică.
• $callback – numele unei funcții pe care o veți crea, care va afișa conținutul real al widget-ului.
• $control_callback – (opțional) numele unei funcții pe care o veți crea care se va ocupa de transmiterea formularelor de opțiuni ale widget-ului, și va afișa, de asemenea elementele de formular.

Actiunea

Pentru a rula funcția va trebui să o includeți în cârlig în acșiunea „wp_dashboard_setup” via add_action(). Pentrul tabloul de bord al administratorului de rețea, utilizați cârligul „wp_network_dashboard_setup„.

Exemple

/**
* Adauga un widget la tabloul de bord.
*
* Această funcție este în cârlig în acțiunea „wp_dashboard_setup” de mai jos.
*/
function example_add_dashboard_widgets() {

wp_add_dashboard_widget(
‘example_dashboard_widget’,         // Slug widget.
‘Example Dashboard Widget’,         // Titlu.
‘example_dashboard_widget_function’ // Afișează funcția.
);
}
add_action( ‘wp_dashboard_setup’, ‘example_add_dashboard_widgets’ );

/**
* Crează funcția pentru a obține conținutul widget-ului ecranului de start.
*/
function example_dashboard_widget_function() {

// Afșează ce dorești să se vadă.
echo „Hello World, I’m a great Dashboard Widget”;
}

Avansat: Forțarea widget-ului în partea de sus

În mod normal, ar trebui să lăsați doar utilizatorii modulului să plaseze widget-ul ecranului de start oriunde doresc prin glisarea acestuia. Momentan nu este un API ușor de pre-sortat widget-urile implicite, ceea ce înseamnă că noul widget se va găsi întotdeauna în partea de jos a listei. Până când sortarea este adăugată la API este un pic complicat să se rezolve această problemă.

Mai jos este un exemplu funcție de cârlig, care va încerca să plaseze widget-ul tău înaintea celor implicite. Funcția face acest lucru prin modificarea manuală a matricei interne de metaboxelor (în care sunt incluse ca tipologie widget-urile ecranului de start) și pune widget-ul în partea de sus a listei, astfel se afișează primul.

function example_add_dashboard_widgets() {
wp_add_dashboard_widget( ‘example_dashboard_widget’, ‘Example Dashboard Widget’, ‘example_dashboard_widget_function’ );

// Globalizează matricea metaboxelor, aceasta ține toate widget-urilr pentru wp-admin

global $wp_meta_boxes;

// Obține matricea obișnuită a widget-urilor pentru tabloul de bord
// (care include deja widget-ul nostru dar în partea de jos)

$normal_dashboard = $wp_meta_boxes[‘dashboard’][‘normal’][‘core’];

// Arhivează și șterge noul widget pentru tabloul de bord din partea de jos a matricei

$example_widget_backup = array( ‘example_dashboard_widget’ => $normal_dashboard[‘example_dashboard_widget’] );
unset( $normal_dashboard[‘example_dashboard_widget’] );

// Îmbină cele două matrice astfel încât widget-ul nostru este la început

$sorted_dashboard = array_merge( $example_widget_backup, $normal_dashboard );

// Salvează matricea sortată înapoi în metaboxele originale

$wp_meta_boxes[‘dashboard’][‘normal’][‘core’] = $sorted_dashboard;
}

 

Din păcate, acest lucru funcționează doar pentru persoanele care nu au re-ordonat niciodată widget-urile lor. Odată ce un utilizator a făcut acest lucru preferințele lor existente vor rescrie această nouă ordonare și vor trebui să mute noul widget în partea de sus pentru ca acesta să rămână acolo.

Avansat: Eliminarea widget-urilor ecranului de start

În unele situații, în special pe blog-urile multi-utilizator, poate fi util să se elimine complet widget-urile din interfață. Fiecare utilizator individual poate, în mod implicit, opri orice widget anume, utilizând fila Opțiuni ecran din partea de sus, astfel încât dacă aveți o mulțime de utilizatorii non-tehnici ar putea fi mai bine pentru ei să nu le vadă deloc.

Pentru a elimina widget-ul ecranului de start, utilizați funcția remove_meta_box(). Vezi codul de exemplul de mai jos pentru parametrii necesari.

Acestea sunt numele widget-urilor implicite pe tabloul de bord:

// Coloana principală (stânga):
$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’]

// Coloana laterală (dreapta):
$wp_meta_boxes[‘dashboard’][‘side’][‘core’][‘dashboard_quick_press’] $wp_meta_boxes[‘dashboard’][‘side’][‘core’][‘dashboard_primary’]

Aici este un exemplu de funcție care elimină widget-ul QuickPress.

// Crează funcția care folosește cârligul de acțiune
function example_remove_dashboard_widget() {
remove_meta_box( ‘dashboard_quick_press’, ‘dashboard’, ‘side’ );
}

// Cârlig în acțiunea ‘wp_dashboard_setup’ pentru a înregistra funcția noastră
add_action(‘wp_dashboard_setup’, ‘example_remove_dashboard_widget’ );

Exemplul de mai jos elimină toate widgets -urile ecranului de start:

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’ );

Avansat: Adăugarea widget-urilor într-o parte

Funcția nu vă permite să alegeți unde doriți să plasați widget-ul și îl va adăuga automat la „nucleul” din partea stângă. Dar puteti să-l plasați și pe partea dreaptă, foarte ușor.

Puteți folosi funcția add_meta_box() în loc de wp_add_dashboard_widget. Pur și simplu specificați ‘dashboard‘ în loc de $post_type. De exemplu:

add_meta_box( ‘id’, ‘Titlu widget ecran de start’, ‘dash_widget’, ‘dashboard’, ‘side’, ‘high’ );

Sau, după crearea widget-ului puteți folosi:

// Globalizeazî variabila $wp_meta_boxes (aceasta va permite modificarea matricei).
global $wp_meta_boxes;

// Apoi va crea o arhivă a widget-ului tău.
$my_widget = $wp_meta_boxes[‘dashboard’][‘normal’][‘core’][‘{widget id here}’];

// Apoi se va elimina acea parte a matricei.
unset($wp_meta_boxes[‘dashboard’][‘normal’][‘core’][‘{widget id here}’]);

// Acum se adaugă înapoi widget-ul.
$wp_meta_boxes[‘dashboard’][‘side’][‘core’][‘{widget id here}’] = $my_widget;

Agregarea fluxurilor RSS în tabloul de bord

Dacă aveți nevoie să agregați RSS în widget, aceasta se poate face cu cache în /wp-admin/includes/dashboard.php.

Opțiuni widget

WordPress nu oferă o modalitate implementată pentru a prelua opțiuni pentru un anumit widget. În mod implicit, va trebui să utilizați get_option(”dashboard_widget_options’) pentru a prelua toate opțiunile widget-ului și apoi se filtrează manual matricea returnată. Această secțiune prezintă unele funcții care pot fi ușor adăugate la o temă sau plugin pentru a ajuta la obținerea și setarea opțiunilor widget.

Obținerea opțiunilor widget-urilor

Această funcție va prelua toate opțiunile widget-urilor, sau doar opțiuni pentru un anumit widget.

/**
* Obține toate opțiunile widget-urilor, sau doar opțiunile pentru un anumit widget dacă este spcific un anume widget.
*
* @param string $widget_id Opțional. Dacă este dat, va prelua opțiuni doar pentru acel widget.
* @return array O matrice asociativă
*/
public static function get_dashboard_widget_options( $widget_id=” )
{
//Preia TOATE opțiunile widget-ului pentru tabloul de bord din baza de date…
$opts = get_option( ‘dashboard_widget_options’ );

//Dacă nu este niciun widget specificat, returnează totul
if ( empty( $widget_id ) )
return $opts;

//Dacă se solicită un widget și acesta există, îl returnează
if ( isset( $opts[$widget_id] ) )
return $opts[$widget_id];

//Ceva nu a mers bine…
return false;
}

Obținerea opțiunilor uni singur widget

Dacă doriți să preluați cu ușurință o singură opțiune (pentru a o include într-o temă), următoarea funcție va face asta mai ușor.

Acest exemplu ar trebui să fie utilizat cu funcția exemplu anterioară pentru „Obținerea opțiunilor widget-urilor”.

/**
* Obține o opțiune specifică pentru widget-ul specificat.
* @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);

//Dacă opțiunile widget-ului nu există, returnează fals
if ( ! $opts )
return false;

//Altfel preia opțiunea sau o folosește pe cea implicită
if ( isset( $opts[$option] ) && ! empty($opts[$option]) )
return $opts[$option];
else
return ( isset($default) ) ? $default : false;

}

Actualizarea opțiunilor widget-ului

Această funcție poate fi utilizată pentru a actualiza cu ușurință toate opțiunile unui widget. Aceasta poate fi de asemenea utilizată pentru a adăuga o opțiune widget-ului în mod nedistructiv. Pur și simplu setați argumentul $add_option la true, astfel nu se va suprascrie nicio opțiune existentă (deși va adăuga pe cele care lipsesc).

/**
* Salvează o matrice de opțiuni pentru un singur widget pentru tabloul de bord în baza de date.
* Poate fi de asemenea utilizat pentru a defini valorile implicite pentru un widget.
*
* @param string $widget_id Numele widget-ului care va fi actualizat
* @param array $args O matrice asociativă de opțiuni care va fi salvată.
* @param bool $add_only Seteaza la true dacă nu dorești să se suprascrie nicio opțiune existentă.
*/
public static function update_dashboard_widget_options( $widget_id , $args=array(), $add_only=false )
{
//Preia TOATE opțiunile widget-ului tablului de bord din baza de date…
$opts = get_option( ‘dashboard_widget_options’ );

//Obține doar opțiunile widget-ului nostru, sau setează o matrice goală
$w_opts = ( isset( $opts[$widget_id] ) ) ? $opts[$widget_id] : array();

if ( $add_only ) {
//Adaugă orice opțiune care lipsește (cele existente le vor suprascrie pe cele noi)
$opts[$widget_id] = array_merge($args,$w_opts);
}
else {
//Combină noile opțiuni cu cele existente, și le adaugă înapoi la matricea widget-urilor
$opts[$widget_id] = array_merge($w_opts,$args);
}

//Salvează matricea completă a widget-urilor înapoi în baza de date
return update_option(‘dashboard_widget_options’, $opts);
}