Tworzenie widgetu WordPress

Widget to element na stronie, który nie stanowi głównej treści ale nie jest też ani nagłówkiem ani stopką ani nawigacją. Charakterystyczne dla widżetu jest to, że może być on widoczny na wszystkich lub w pewnej podgrupie podstron. Może być zwykłym banerem ale też dynamicznym elementem oferującym różne funkcjonalności (np. licznik, listę najnowszych artykułów, komentarzy lub jakiś formularz, który sami oprogramujemy).

WordPress pozwala nam wykorzystać gotowe widgety, które są wbudowane w rdzeń systemu lub te, które zostały dodane przy okazji instalowania wtyczki – na poniższym zrzucie można zauważyć dodany kk Star Ratings obok domyślnych widgetów WordPress:

Oczywiście najwięcej frajdy da nam stworzenie własnego widgetu WordPress od podstaw. Aby mieć rozeznanie jak to wszystko działa zarejestrujmy w stworzonym przez siebie motywie sidebar a potem stworzymy własny rodzaj widgetu.

Od wersji 5.8 widgety w systemie WordPress dysponują nowym edytorem blokowym. To bardzo dobra zmiana, bo od teraz w widgetach możemy użyć bloków Gutenberga. Dzięki temu edycja w systemie WordPress jest spójna i bardziej efektywna.

Właściciele przestarzałych stron, które są stworzone na bazie niektórych niekompatybilnych motywów będą zmuszeni skorzystać z wtyczki, która przywraca klasyczny edytor w widgetach np. Classic Widgets.

Dodawanie widgetu zazwyczaj jest możliwe w pasku bocznym (sidabarze) ale nie jest to jakaś sztywna reguła. Przy tworzeniu szablonu WordPress, możemy zarejestrować konkretny slot na widgety gdzie tylko nam się spodoba np. w menu, stopce czy pod główną treścią strony.

Krok 1: Rejestracja sidebara – miejsca na widgety

Aby w naszym szablonie dało się umieścić jakiekolwiek widgety, należy stworzyć osobny sidebar czyli taki jakby slot. Poniższy kod możemy dopisać do pliku functions.php

function pm_widgets_init() {
register_sidebar( array(
     'name'          => 'Test Widget',
     'id'            => 'testwidget',
     'before_widget' => ' ',
     'after_widget'  => ' ',
     'before_title'  => ' ',
     'after_title'   => ' ',
 ) );
}
 add_action( 'widgets_init', 'pm_widgets_init');

Każdy widget ma swój tytuł a sidebar może mieć dodatkowe opcje takie jak „before_widget” i „after_widget” które umożliwiają dodanie kodu otaczającego dla widgetów i ich tytułów umieszczanych w tym sidebarze. W nowym edytorze blokowym nie ma pola na tytuł dlatego nie trzeba już nim sobie zaprzątać głowy. Konkretny sidebar może przechowywać wiele widgetów:

Krok 2: Umieszczenie sidebara w szablonie

Teraz w miejscu szablonu, w którym chcemy wyświetlić zainstalowane w tym sidebarze widgety, należy wywołać funkcję dynamic_sidebar. W argumencie tej funkcji podajemy ID, które przypisaliśmy podczas rejestracji sidebara:

<?php dynamic_sidebar("testwidget"); ?>

To wszystko, wystarczy teraz w Wygląd >> Widgety dodać do naszego sidebara interesujące nas widgety i wszystko powinno działać.

Niestety nawet najprostszy widget z zawartością HTML lub tekstem i tak dodaje własny <div> otaczający go np:

<div class="textwidget">Jakiś tekst</div>

Aby mieć zatem 100% kontroli nad kodem i nie bawić się w edycje plików systemowych WordPressa (ani JavaScriptowe sztuczki usuwające je po stronie klienta) należy stworzyć swój własny rodzaj widgetu.

Krok 3: Programowanie własnego widgetu WordPress

Poniższy kod też można dodać do pliku functions.php:

 class clear_widget extends WP_Widget {
     function __construct() {
          parent::__construct(false, $name = 'Czysty widget');    
     }
     function widget($args, $instance) {    
         extract( $args );
         $title         = apply_filters('widget_title', $instance['title']);
         $message     = $instance['message'];
         ?>
               <?php echo $before_widget; ?>
                   <?php if ( $title )
                         echo $before_title . $title . $after_title; ?> 
<?php echo $message; ?>
       <?php echo $after_widget; ?>
<?php }
 function form($instance) {
     $title         = esc_attr($instance['title']);
     $message    = esc_attr($instance['message']);
     ?>
     <p>
       <label for="<?php echo $this->get_field_id('title'); ?>">Tytuł</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 $title; ?>" />
     </p>
     <p>
       <label for="<?php echo $this->get_field_id('message'); ?>">Zawartość</label> 
       <input class="widefat" id="<?php echo $this->get_field_id('message'); ?>" name="<?php echo $this->get_field_name('message'); ?>" type="text" value="<?php echo $message; ?>" />
     </p>
<?php 
 } 
}
function clear_widget_init(){
   return register_widget('clear_widget');
}
add_action ('widgets_init', 'clear_widget_init');

Nazwę widgetu, w tym przypadku „clear_widget” należy powtórzyć w konstruktorze i w ostatniej linii przy inicjalizacji. Następnie obsługujemy wspomniane parametry „before_widget” i „after_widget”.

Funkcja form odpowiada za edycję zawartości widgetu w panelu administracyjnym. Wykorzystujemy ją tylko wtedy, kiedy chcemy dać możliwość edycji jego zawartości.

Jeżeli nie rozumiesz dlaczego w kodzie są strzałki i np. co oznacza $this zerknij do mojego tutorialu programowanie obiektowe PHP.

Krok 4: Wykorzystanie stworzonego widgetu

Teraz możemy dodać widget o nazwie „Czysty Widget” do naszego sidebara „Test Widget”:

Ciąg „Testowa zawartość” Pojawiła się bez dodatkowego kodu HTML w dokładnie tym miejscu które ustaliliśmy w kroku 2.

Dodatek 1: Własne pole ACF w Widgetach

W kursie ACF, wspominałem (a nawet pokazywałem), że widgety mogą mieć własne pola. Przykładem takiego pola może być obrazek w tle lub kolor tła. Dodawania potrzebnych pól w funkcji form może się stać po jakimś czasie męczące, tym bardziej jeżeli chcielibyśmy uploadować obrazek, stworzyć pole powtarzalne lub listę rozwijalną.

Tworzymy grupę i przypisujemy ją do naszego własnego widżetu. W tym przykładzie stworzyłem własną wersję widgetu „Własny HTML”.

Dodatkowe pole od razu pojawi się w trybie edycji:

Jeżeli chcemy teraz wyprowadzić wartości w kodzie nasze czystego widgetu wystarczy uzyć poniższego kodu:

the_field( 'tlo', "widget_".$widget_id );

ACF wymaga w drugim argumencie podania widget_id z przedrostkiem widget_ Zmienna $widget_id już istnieje i posiada przypisaną wartość, ponieważ w funkcji widget (Krok 3.) używamy instrukcji extract($args). To stamtąd jest brany unikalny identyfikator widgetów.

Dodatek 2: Wyłączenie podglądu Widżetów starego typu w edytorze blokowym

Edytując widżety w nowym edytorze blokowym zauważymy, że WordPress stara się wyświetlić podgląd tego widgetu w taki sposób jaki miałby się prezentować finalnie na stronie internetowej użytkownika. W przypadku rozbudowanych widżetów może to być mało wygodne, bo edytor taki będzie zajmował zbyt dużo miejsca. Można wyłączyć podgląd dodając taką instrukcję na samym początku funkcji widget():

if ( defined( 'REST_REQUEST' ) && REST_REQUEST ) {
   return false;
}

Dzięki temu łatwiej będzie zapanować nad edycją widżetów starego typu oraz ułatwi to ich organizację w sidebarach:

Zamiast niedokładnego podglądu widżetu WordPress wyświetli: Brak podglądu.

Podsumowanie

Jak widać tworzenie własnego widżetu w WordPress nie jest skomplikowane, choć na pierwszy rzut oka kod może się wydawać złożony. Jest to pewnego rodzaju szablon wymagany przy tworzeniu nowych widżetów. Jeżeli chcemy dać możliwość szerszej ich personalizacji możemy dodać dodatkowe pola do formularza lub wykorzystać wtyczkę ACF Pro, która dołączy dodatkowe pola automatycznie.

Źródła

• https://developer.wordpress.org/reference/functions/register_sidebar/