API pentru piese (widget) în WordPress

În termeni tehnici: un widget WordPress este un obiect PHP care afișează date ale șirurilor la STDOUT când este apelată metoda widget(). Este situată în wp-includes/widgets.php.

Referință despre funcții

Funcții widget: is_active_widget(), the_widget(), register_widget(), unregister_widget()
Funcții interne: wp_register_widget_control(), wp_unregister_widget_control(), wp_convert_widget_settings(), wp_get_widget_defaults(), wp_widget_description()

Dezvoltarea widget-urilor

Pentru a crea un widget, trebuie doar să se extindă clasa WP_Widget standard și unele dintre funcțiile sale.

Această clasă de bază conține de asemenea informații despre funcțiile care trebuiesc extinse pentru a obține un widget funcțional.

Clasa WP_Widget este situată în wp-includes/widgets.php.

Utilizare implicită

class My_Widget extends WP_Widget {

/**
* Setează numele widget-ului, etc
*/
public function __construct() {
// procesele actuale widget
}

/**
* Afișarea conținutului widget-ului
*
* @param array $args
* @param array $instance
*/
public function widget( $args, $instance ) {
// afișarea conținutului widget-ului
}

/**
* Afișarea formularului de opțiuni pe admin
*
* @param array $instance The widget options
*/
public function form( $instance ) {
// afișarea formularului de opțiuni pe admin
}

/**
* Procesarea opțiunilor widget-ului pentru salvare
*
* @param array $new_instance The new options
* @param array $old_instance The previous options
*/
public function update( $new_instance, $old_instance ) {
// procesează opțiunile widget-ului pentru salvare
}
}

Widget-ul poate fi apoi înregistrate folosind cârligul widgets_init:

Doar PHP 5.3+:

add_action( ‘widgets_init’, function(){
register_widget( ‘My_Widget’ );
});

PHP 5.2+:

add_action(‘widgets_init’,
create_function(”, ‘return register_widget(„My_Widget”);’)
);

Exemplu

Acest cod creează un widget pe nume Foo_Widget care are un formular de setări pentru a modifica titlul de afișare.

/**
* Adaugă widget-ul Foo_Widget.
*/
class Foo_Widget extends WP_Widget {

/**
* Înregistrează widget-ul în WordPress.
*/
function __construct() {
parent::__construct(
‘foo_widget’, // Base ID
__( ‘Widget Title’, ‘text_domain’ ), // Nume
array( ‘description’ => __( ‘A Foo Widget’, ‘text_domain’ ), ) // Argumente
);
}

/**
* Afișare widget-ului pentru utilizatori.
*
* @see WP_Widget::widget()
*
* @param array $args Widget arguments.
* @param array $instance Saved values from database.
*/
public function widget( $args, $instance ) {
echo $args[‘before_widget’];
if ( ! empty( $instance[‘title’] ) ) {
echo $args[‘before_title’] . apply_filters( ‘widget_title’, $instance[‘title’] ). $args[‘after_title’];
}
echo __( ‘Hello, World!’, ‘text_domain’ );
echo $args[‘after_widget’];
}

/**
* Formular widget în zona de administrare.
*
* @see WP_Widget::form()
*
* @param array $instance Previously saved values from database.
*/
public function form( $instance ) {
$title = ! empty( $instance[‘title’] ) ? $instance[‘title’] : __( ‘New title’, ‘text_domain’ );
?>
<p>
<label for=”<?php echo $this->get_field_id( ‘title’ ); ?>”><?php _e( ‘Title:’ ); ?></label>
<input class=”widefat” id=”<?php echo $this->get_field_id( ‘title’ ); ?>” name=”<?php echo $this->get_field_name( ‘title’ ); ?>” type=”text” value=”<?php echo esc_attr( $title ); ?>”>
</p>
<?php
}

/**
* Curățirea valorilor formularului widget-ului pe măsură ce sunt salvate.
*
* @see WP_Widget::update()
*
* @param array $new_instance Values just sent to be saved.
* @param array $old_instance Previously saved values from database.
*
* @return array Updated safe values to be saved.
*/
public function update( $new_instance, $old_instance ) {
$instance = array();
$instance[‘title’] = ( ! empty( $new_instance[‘title’] ) ) ? strip_tags( $new_instance[‘title’] ) : ”;

return $instance;
}

} // clasa Foo_Widget

Acest widget de model poate fi apoi înregistrat în cârligul „widgets_init„:

// înregistrează widget-ul Foo_Widget
function register_foo_widget() {
register_widget( ‘Foo_Widget’ );
}
add_action( ‘widgets_init’, ‘register_foo_widget’ );

Notă: Trebuie să utilizați funcția get_field_name() și get_field_id() pentru a genera numele și ID-ul elementului de formular.

Exemplu cu spații de nume

Dacă utilizați PHP 5.3. cu spațiile de nume trebuie să apelați constructorul direct ca în exemplul următor:

namespace abc;

class My_Widget_Class extends WP_Widget {
function __construct() {
parent::__construct( ‘baseID’, ‘name’ );
}
// … restul funcțiilor
}

și apelați register_widget() cu:

add_action( ‘widgets_init’, function(){
register_widget( ‘abcMy_Widget_Class’ );
});

Asta e tot. Veți obține automat un multi-widget. Nu mai sunt necesare trucuri speciale pentru asta.

Afișarea widget-urilor și a zonelor pentru widget-uri

Există cel puțin 3 moduri in care widget-urile pot fi afișate:

Zonele widget

Prima, și cea mai comună, este prin adăugarea widget-ului dorit unei zone de widget prin meniul Aspect > Piese în Panoul control.

WordPressare unele zone pentru widget predefinite, care au fiecare identificatori unici (vezi sursa paginii cu widget-uri pentru a-i vedea), pe care va trebuie să îi știți pentru a afișa în Zona Widget. În cazul în care zonele widget predefinite sunt insuficiente pentru nevoile dumneavoastra puteți înregistra o zonă widget personalizată.

Când sunteți gata, puteți afișa această zonă widget prin introducerea codului de mai jos în oricare fișier dorit al temei:

<?php if ( dynamic_sidebar(‘example_widget_area_name’) ) : else : endif; ?>

Acest cod afișează toate widget-urile adăugate în Zona Widget.

Afișarea zonei widget numai dacă este activă

Iată codul utilizat în fișierul sidebar.php în tema Twenty Fourteen.

<?php if ( is_active_sidebar( ‘sidebar-1’ ) ) : ?>
<div id=”primary-sidebar” class=”primary-sidebar widget-area” role=”complementary”>
<?php dynamic_sidebar( ‘sidebar-1’ ); ?>
</div><!– #primary-sidebar –>
<?php endif; ?>

Acest cod verifică dacă noua zonă widget este populată, în caz contrar nu se execută.