WordPress widget tutorial – piszemy własny widget, witajcie w drugiej części kursu dla początkujących dotyczącego tworzenia widgetów dla WordPress zupełnie od zera.
Część 2 – WordPress widget tutorial – piszemy własny widget
W tej części zajmiemy się formularzem widget-u (backend-em), dzięki któremu możliwe będzie sterowanie widget-em z poziomu kokpitu. A przesłane opcje, walidować i zapisywać w bazie danych.
Produktem tego kursu będzie prosty widget wyświetlający najnowsze wpisy na blogu, zupełnie tak jak ten wbudowany w WordPress, ale nasz będzie miał trochę więcej opcji:
- możliwość wyboru kategorii
- opcja wyświetlenia wypisu
- ustawienie długości wypisu
- możliwość wyświetlania miniatur wpisu
Wstępne zapisywanie opcji widget-u w bazie WordPress
Dla ułatwienia sobie zadania, zanim zaczniemy pisać formularz z opcjami do widget-u możemy przedtem nieco zmodyfikować metodę klasy naszego widgetu, tak by od razu zapisywała wszystkie przesłane dane w bazie danych.
Otwieramy plik z ostatnio utworzoną klasą i przechodzimy do metody update() i zamieniamy ją na:
public function update( $new_instance, $old_instance ) {
return $new_instance;
}
Jak to działa? W skrócie mówiąc, funkcja powinna zwracać tablicę asocjacyjną zawierającą już sprawdzone dane (opcje widgetu), które następnie są przez WordPress serializowane i zapisywane w bazie pod identyfikatorem widget-u.
Jako developerzy widget-ów, wiemy jakie niebezpieczeństwa mogą wiązać się z brakiem walidacji danych pobranych od użytkowników, ale nam w tym momencie chodzi tylko o to, by sprawdzać, czy pola dodawane do formularza są dobrze skonstruowane i czy będą później zaznaczać zapisane opcje, a samą walidacją zajmiemy się na końcu tej części kursu.
Dodajemy pola do formularza widget-u
Przechodzimy teraz do funkcji form(), w której dodawać będziemy kolejne pola do formularza widget-u.
Zacznijmy od dodania pola nadającego nagłówek (nazwę) widget-u:
Na początku funkcji dodajemy linijkę:
$instance = wp_parse_args( (array) $instance, array( 'title' => 'Najnowsze Posty' ) );
Jak zapewne zauważyłeś metoda form() przyjmuje jeden argument $instance. W nim znajduje się tablica asocjacyjna z ustawieniami widgetu pobranymi z bazy danych. Teraz ta zmienna jest pusta.
Dodanie tej linijki sprawia, że w przypadku braku którejś opcji w bazie (jak teraz), do zmiennej $instance zostaną dodane opcje domyślne, które definiujemy właśnie w tym miejscu. Jeżeli mielibyśmy w bazie zapisane już jakieś informacje, to domyślne dane zostaną nadpisane tymi z bazy.
W tym przypadku ustawiamy title na Najnowsze Posty, czyli zawsze, gdy w bazie będzie brakowało tej zmiennej, wyświetlony zostanie ciąg Najnowsze Posty.
I wreszcie, dodajemy kod html, uzupełniony o specjalne funkcje WordPress-a, dzięki którym pole formularza będzie zapisywać wartość opcji pod właściwym identyfikatorem, i później uzupełniać te pole zapisaną wartością z bazy danych:
<p>
<!-- Widgets name -->
<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($instance['title']); ?>" />
</p>
O ile etykieta (label) nie jest tutaj bardzo ważna, to musimy dokładnie przyjrzeć się w jaki sposób mamy nazwać pole input, oraz jak nadać mu wartość.
Myślę, że w tym momencie jest już w miarę jasne o co chodzi, dlatego nie będę opisywał każdego pola z osobna, tylko pokaże jak teraz wygląda mój pełny formularz:
public function form( $instance ) {
//ustawiamy opcje domyslne
$my_defaults = array(
'number' => 5,
'title' => 'Najnowsze Posty',
'categories' => array(),
'show_excerpt' => false,
'excerpt_length' => 200,
'show_thumbnail' => false
);
//uzupelniamy opcje zapisane w bazie o opcje domyslne
$instance = wp_parse_args( (array) $instance, $my_defaults );
?>
<p>
<!-- Widgets name -->
<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($instance['title']); ?>" />
</p>
<p>
<!-- Number of posts to show -->
<label for="<?php echo $this->get_field_id( 'number' ); ?>"><?php _e( 'Number of posts to show:' ); ?></label>
<input id="<?php echo $this->get_field_id( 'number' ); ?>" name="<?php echo $this->get_field_name( 'number' ); ?>" type="text" value="<?php echo $instance['number']; ?>" size="3" />
</p>
<p>
<!-- Get and display Categories checkbox options -->
<label><?php _e('Categories:'); ?></label><br />
<?php
$categories_list = get_categories('hide_empty=0&orderby=name');
foreach ($categories_list as $cat ):
$cat_id = intval($cat->cat_ID);
$cat_name = $cat->cat_name;
$selected = '';
if(in_array($cat_id, $instance['categories']))
$selected=' checked="checked"'; ?>
<input value="<?php echo $cat_id; ?>" class="radio" type="checkbox"<?php echo $selected; ?> id="<?php echo $this->get_field_id('categories'); echo $cat_id; ?>" name="<?php echo $this->get_field_name('categories'); ?>[]" /> <label for="<?php echo $this->get_field_id('categories'); echo $cat_id; ?>"><?php echo $cat_name; ?></label><br />
<?php endforeach; ?>
</p>
<p>
<!-- Show excerpt -->
<input class="checkbox" type="checkbox" name="<?php echo $this->get_field_name('show_excerpt'); ?>" id="<?php echo $this->get_field_id('show_excerpt'); ?>" value="true" <?php checked(true, $instance['show_excerpt']);?> />
<label for="<?php echo $this->get_field_id('show_excerpt'); ?>"> <?php _e( 'Display post excerpt' ); ?></label><br />
</p>
<p>
<!-- Excerpt length -->
<label for="<?php echo $this->get_field_id( 'excerpt_length' ); ?>"><?php _e( 'Excerpt length:' ); ?></label>
<input id="<?php echo $this->get_field_id( 'excerpt_length' ); ?>" name="<?php echo $this->get_field_name( 'excerpt_length' ); ?>" type="text" value="<?php echo $instance['excerpt_length']; ?>" size="5" />
</p>
<p>
<!-- Show excerpt -->
<input class="checkbox" type="checkbox" name="<?php echo $this->get_field_name('show_thumbnail'); ?>" id="<?php echo $this->get_field_id('show_thumbnail'); ?>" value="true" <?php checked(true, $instance['show_thumbnail']);?> />
<label for="<?php echo $this->get_field_id('show_thumbnail'); ?>"> <?php _e( 'Display post thumbnail' ); ?></label><br />
</p>
<?php
}
Jeżeli brakuje wam jakiegoś pola i nie za bardzo wiecie jak ma wyglądać jego kod, czy jakie klasy dodać do tych pól, to bardzo dobrym źródłem wiedzy jest kod widgetów wbudowanych w WordPress. Plik z domyślnymi widgetami znajdziecie w katalogu wp-includes/default-widgets.php, albo tutaj online. Można też sprawdzić widgety dodawane do innych motywów, albo pobrać z repozytorium WordPress-a w postaci pluginów, jest tego mnóstwo.
Listę checkbox można łatwo zamienić na pola typu radio – wystarczy zmienić typ input-ów na radio – teraz zamiast listy wielokrotnego wyboru, otrzymamy listę z jedną opcją do wyboru.
Walidacja opcji widget-u i zapis w bazie WordPress
Ostatnią rzeczą, którą musimy się jeszcze zająć w tej części to walidacja przesłanych przez formularz opcji, ewentualna ich obróbka i zapis (uaktualnienie) w bazie danych. Spójrz na mój końcowy kod:
public function update( $new_instance, $old_instance ) {
$instance = $old_instance;
//tytul widgetu
$instance['title'] = strip_tags($new_instance['title']);
//ilosc wyswietlanych postow
$instance['number'] = absint($new_instance['number']);
//zaznaczone kategorie
$instance['categories'] = (array) $new_instance['categories'];
//czy pokazac wypis
$instance['show_excerpt'] = isset($new_instance['show_excerpt']);
//dlugosc wypisu
$instance['excerpt_length'] = absint($new_instance['excerpt_length']);
//czy pokazac miniaturke wpisu
$instance['show_thumbnail'] = isset($new_instance['show_thumbnail']);
return $instance;
}
Sposób działania tej metody jest dosyć prosty – w argumentach podawane są dwie tablice asocjacyjne:
$new_instance– jest to tablica nowych, właśnie przesłanych przez formularz opcji;$old_instance, to tablica opcji aktualnie zapisanych w bazie danych.
A sama metoda powinna zwrócić kombinację tych dwóch tablic – przede wszystkim nowo-przesłane opcje, uzupełnione o stare, jeżeli nowe opcje nie będą spełniały stawianych im wymagań.
Nawet dla tych kilku opcji, metoda walidująca wprowadzone dane wydaje się być strasznie krótka, prawda? Myślę, że wytłumaczyć to można w ten sposób, że administracja widgetami należy do administratora witryny i jest raczej mało prawdopodobne, aby admin próbował sabotować własną witrynę. Dlatego mamy tutaj taką prostą, podstawową walidację.
Nie ma tutaj dużej filozofii, z pól tekstowych czyścimy wszelkie tagi, dla liczb całkowitych używamy funkcji absint(), która zwróci 0, jeżeli liczba jest ujemna i/lub niecałkowita. Dla pól typu checkbox, sprawdzamy tylko czy pole jest ustawione.
Oczywiście można bawić się w dodatkowe „ify” i „regexy”, sprawdzać czy np. łańcuch jest pusty i ewentualnie wstawiać starą wartość, ale patrząc z przedstawionej wcześniej perspektywy nie ma to większego sensu.
Pełny kod:
<?php
class Najnowsze_Posty extends WP_Widget {
/**
* Sets up the widgets name etc
*/
public function __construct() {
$widget_id = 'najnowsze_posty';
$widget_name = __('Najnowsze Posty', 'NajnowszePosty');
$widget_opt = array('description'=>'Ten widget wyświetla najnowsze posty.');
parent::__construct($widget_id, $widget_name, $widget_opt);
}
/**
* Outputs the content of the widget
*
* @param array $args
* @param array $instance
*/
public function widget( $args, $instance ) {
// outputs the content of the widget
}
/**
* Outputs the options form on admin
*
* @param array $instance The widget options
*/
public function form( $instance ) {
//ustawiamy opcje domyslne
$my_defaults = array(
'number' => 5,
'title' => 'Najnowsze Posty',
'categories' => array(),
'show_excerpt' => false,
'excerpt_length' => 200,
'show_thumbnail' => false
);
//uzupelniamy opcje zapisane w bazie o opcje domyslne
$instance = wp_parse_args( (array) $instance, $my_defaults );
?>
<p>
<!-- Widgets name -->
<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($instance['title']); ?>" />
</p>
<p>
<!-- Number of posts to show -->
<label for="<?php echo $this->get_field_id( 'number' ); ?>"><?php _e( 'Number of posts to show:' ); ?></label>
<input id="<?php echo $this->get_field_id( 'number' ); ?>" name="<?php echo $this->get_field_name( 'number' ); ?>" type="text" value="<?php echo $instance['number']; ?>" size="3" />
</p>
<p>
<!-- Get and display Categories checkbox options -->
<label><?php _e('Categories:'); ?></label><br />
<?php
$categories_list = get_categories('hide_empty=0&orderby=name');
foreach ($categories_list as $cat ):
$cat_id = intval($cat->cat_ID);
$cat_name = $cat->cat_name;
$selected = '';
if(in_array($cat_id, $instance['categories']))
$selected=' checked="checked"'; ?>
<input value="<?php echo $cat_id; ?>" class="radio" type="checkbox"<?php echo $selected; ?> id="<?php echo $this->get_field_id('categories'); echo $cat_id; ?>" name="<?php echo $this->get_field_name('categories'); ?>[]" /> <label for="<?php echo $this->get_field_id('categories'); echo $cat_id; ?>"><?php echo $cat_name; ?></label><br />
<?php endforeach; ?>
</p>
<p>
<!-- Show excerpt -->
<input class="checkbox" type="checkbox" name="<?php echo $this->get_field_name('show_excerpt'); ?>" id="<?php echo $this->get_field_id('show_excerpt'); ?>" value="true" <?php checked(true, $instance['show_excerpt']);?> />
<label for="<?php echo $this->get_field_id('show_excerpt'); ?>"> <?php _e( 'Display post excerpt' ); ?></label><br />
</p>
<p>
<!-- Excerpt length -->
<label for="<?php echo $this->get_field_id( 'excerpt_length' ); ?>"><?php _e( 'Excerpt length:' ); ?></label>
<input id="<?php echo $this->get_field_id( 'excerpt_length' ); ?>" name="<?php echo $this->get_field_name( 'excerpt_length' ); ?>" type="text" value="<?php echo $instance['excerpt_length']; ?>" size="5" />
</p>
<p>
<!-- Show excerpt -->
<input class="checkbox" type="checkbox" name="<?php echo $this->get_field_name('show_thumbnail'); ?>" id="<?php echo $this->get_field_id('show_thumbnail'); ?>" value="true" <?php checked(true, $instance['show_thumbnail']);?> />
<label for="<?php echo $this->get_field_id('show_thumbnail'); ?>"> <?php _e( 'Display post thumbnail' ); ?></label><br />
</p>
<?php
}
/**
* Processing widget options on save
*
* @param array $new_instance The new options
* @param array $old_instance The previous options
*/
public function update( $new_instance, $old_instance ) {
$instance = $old_instance;
//tytul widgetu
$instance['title'] = strip_tags($new_instance['title']);
//ilosc wyswietlanych postow
$instance['number'] = absint($new_instance['number']);
//zaznaczone kategorie
$instance['categories'] = (array) $new_instance['categories'];
//czy pokazac wypis
$instance['show_excerpt'] = isset($new_instance['show_excerpt']);
//dlugosc wypisu
$instance['excerpt_length'] = absint($new_instance['excerpt_length']);
//czy pokazac miniaturke wpisu
$instance['show_thumbnail'] = isset($new_instance['show_thumbnail']);
return $instance;
}
}
Zakończenie
W kolejnej, ostatniej już części tego kursu, dowiecie się w jaki sposób pobrać z bazy danych posty, oraz jak je wyświetlić uwzględniając wszystkie zapisane opcje.
Już teraz zapraszam na kolejną część kursu WordPress widget tutorial – piszemy własny widget!
