Xây dựng Custom Widget toàn tập

Hãy bắt đầu với những bước đầu tiên:

Đăng ký Custom Widget

Đầu tiên, ta cần tạo 1 PHP function để register widget và load vào trong list widget của WordPress:

function load_widgets() {
 register_widget( 'ebook_cat_menu' );
}

add_action( 'widgets_init', 'load_widgets' );

// Creating the widget
class ebook_cat_menu extends WP_Widget {}

Xây dựng cấu trúc function custom widget

Tiếp đến, trong class ebook_cat_menu là nơi ta sẽ bắt đầu các thao tác build frontend, add custom option trong backend.

Hãy bắt đầu từ main structure với các thông số cơ bản nhất nhé:

  function __construct() {
  parent::__construct(
// Đây là Custom Widget ID
   'ebook_cat_menu',
// Đây là tên sẽ hiển thị trong Backend khi add widget vào Sidebar
   __('Ebook Categories', 'your-theme-name'),
// Giới thiệu nhỏ sẽ hiển thị bên dưới tên trong Backend
   array( 'description' => __( 'Widget to display Ebook Categories as menu', 'your-theme-name' ), )
  );
 }

Tiếp theo, ta gọi đến cấu trúc sau để hiển thị ngoài frontend:

public function widget( $args, $instance ) {}

Lưu ý, biến $args sẽ là các thông số đăng ký cơ bản của widget, còn biến $instance sẽ là nơi chứa các custom option của bạn.

Chẳng hạn, như mình tạo 1 option text thì có thể call $instance['custom_text]; để gọi và output ra nhé.

Debug: Cách tốt nhất nếu bạn chưa hiểu thì cứ var_dump( $instance); bên trong function này để xem có các info gì đã được lưu nhé.

Dòng đầu tiên sẽ là output phần before_widget ra nhé:

echo $args['before_widget'];

Tiếp theo, chúng ta sẽ bắt đầu định nghĩa các biến cần truy xuất vào:

// Biến này thì đơn giản là gán widget_title sang sử dụng option của field custom title
$title = apply_filters( 'widget_title', $instance['title'] );
// Biến này lấy giá trị tax_name từ 1 custom option trong backend
$tax_name = !empty( $instance['tax_name'] ) ? $instance['tax_name'] : '';

Sau đó mình bắt đầu output dữ liệu. Nếu có dữ liệu thì hiển ra. Lưu ý là check này là text field thì cần checkout có rỗng không, chứ không phải true/false, nên không sử dụng if( $title ) nhé.

if ( ! empty( $title ) ) {
 echo $args['before_title'] . $title . $args['after_title'];
}

Giải thích cụ thể

Biến $title thì đã rõ, vậy còn $args['before_title] và $args['after_title] là gì? before_title và after_title là các biến khi theme bạn `register_sidebar` đấy nhé. Thực chất nó sẽ output các thẻ Heading tag. Đây là code lúc bạn đăng ký sidebar chẳng hạn:

register_sidebar(array(
 'name'          => __('Main Sidebar', 'your-theme-name'),
 'id'            => 'main',
 'before_widget' => '<div class="widget widget--main %1$s %2$s">',
 'after_widget'  => '</div>',
 'before_title'  => '<h3>',
 'after_title'   => '</h3>',
));

Bước tiếp theo khó hơn, là nếu như bạn cần làm 1 option select trong backend, sau đó dùng dữ liệu này để output ra frontend.

Cụ thể, ta cần thực hiện việc đăng ký 1 widget mà backend chỉ chọn taxonomy thì ở frontend sẽ hiển thị list term của taxonomy này.

Vậy code trong function widget để hiển thị ra sẽ như sau:

if( !empty( $tax_name ) ) {
 // Lấy danh sách term list từ taxonomy name $tax_name
 $term_list = get_terms( array(
  'taxonomy' => $tax_name,
  'hide_empty' => false
 ) );
 if( $term_list ) {
  echo '<ul class="widget-menu">';
  // Giờ đơn giản rồi, cần loop và tạo 1 markup Frontend thôi
  foreach( $term_list as $term ) {
   echo '<li class="menu-item">';
   echo '<a href="' . get_term_link( $term ) . '" class="menu-link">';
   echo $term->name;
   echo '</a>';
   echo '</li>';
  }
  echo '</ul>';
 }
}

Cuối cùng, ta cần output after_widget:

echo $args['after_widget'];

Chưa xong đâu, bạn mới xử lý code ngoài frontend thôi, giờ ta cần đăng ký backend để hiển thị các field option ta cần nữa đấy.

Đăng ký custom option trong Backend WordPress

Tất cả đều được thực hiện qua public function form( $instance ) { nhé. Mỗi 1 dòng là 1 thẻ <p>, trong đó có chứa:

1. Label của field
2. Input/select của field

Cách thức generate ra field name và field id đều cần thực hiện bắt buộc qua function get_field_name và get_field_id chứ không phải nhập tay đâu nhé.

Đọc hiểu code một chút thì bạn sẽ thấy:

Option đầu tiên chỉ đơn giản là 1 Text field như bình thường.

Option thứ hai phức tạp hơn, ta query bằng function get_taxonomies để lấy ra danh sách taxonomy, sau đó cho output như 1 select option thôi.

Class widefat sẽ cho input nằm full 1 dòng riêng nhé.

<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>
<p>
 <label for="<?php echo $this->get_field_id( 'tax_name' ); ?>"><?php _e('Select taxonomy:'); ?></label>
 <select class="widefat" id="<?php echo $this->get_field_id( 'tax_name' ); ?>" name="<?php echo $this-> get_field_name( 'tax_name' ); ?>">
 <?php $taxonomies = get_taxonomies(); foreach( $taxonomies as $taxonomy ) : ?>
  <option <?php selected( $instance['tax_name'], $taxonomy); ?> value="<?php echo $taxonomy; ?>"><?php echo $taxonomy; ?></option>
 <?php endforeach; ?>
 </select>
</p>

Giờ gộp lại tất cả, ta được như sau: