WordPress - motywy, wtyczki, informacje, programowanie

Admin Bar

Własne informacje i przyciski na pasku admina. Wykorzystanie AJAXa.

Kiedy jesteśmy zalogowani do serwisu opartego na WordPressie przy górnej krawędzi przeglądarki widzimy pasek administratora (Toolbar, dawniej Admin bar). Zawiera on linki, a czasem informacje, które warto zawsze mieć pod ręką, również wtedy kiedy przeglądamy strony serwisu, a nie strony administracyjne. Do tego paska łatwo możemy dodawać własne przyciski, a nawet całe menu, niektóre z nich możemy obsługiwać AJAXem.

Toolbar, czyli pasek admina, możemy wykorzystać na wiele sposobów. Możemy:

  • wyświetlić na nim jakąś informację, jeśli chcemy, żeby była dostępna na pierwszy rzut oka, zaraz gdy wejdziemy na serwis;
  • dodać przycisk, często taki, który wykonuje jakąś operację na stronie na której jesteśmy;
  • dodać całe podmenu z wieloma różnymi funkcjami;

Ponieważ funkcja add_node(), służąca do umieszczania rzeczy na toolbarze, pozwala na podanie dowolnego fragmentu HTMLa, możemy do toolbara dodawać obrazki, pola formularzowe, właściwie dowolne interaktywne elementy.

Bardzo elegancko pasek admina wykorzystuje na przykład wtyczka WordPress SEO by Yoast, która dodaje do niego menu ze wszystkimi ważnymi opcjami oraz ikonę diodki, która zmienia kolor w zależności od tego jak dobrze dany wpis został przygotowany pod względem SEO.

Dodawanie prostej informacji do paska admina

Najprostszym zastosowaniem toolbara jest wyświetlenie na nim jakiejś informacji o stanie systemu, na przykład o tym, że stała WP_DEBUG ustawiona jest na true, czyli WordPress działa w trybie developerskim. Jeśli WP_DEBUG jest ustawiona w instancji WordPressa, którą widzą nasi użytkownicy, to zdecydowanie niedobrze – serwis może działać wolniej, a na stronach mogą się pojawić informacje o błędach i ostrzeżenia, których użytkownicy widzieć nie powinni. Dlatego informacja o włączonym WP_DEBUG może być użyteczna w niektórych wypadkach.

add_action( 'admin_bar_menu', 'my_debug_info', 91);

function my_debug_info ( $wp_admin_bar ) {
    if (defined('WP_DEBUG') && WP_DEBUG) {
        $wp_admin_bar->add_node(array(
            'id'    =>  'id_my_debug_info_1',
            'title' =>  "WP_DEBUG",
        ));
    }
}

Do dodawania elementów na toolbar wykorzystujemy hak admin_bar_menu. Nasza funkcja jest zapięta z priorytetem 91, chodzi o to, żeby dodany przez nią element pojawił się jako ostatni. Wywołując ten hak WordPress podaje w parametrze $wp_admin_bar instancję klasy WP_Admin_Bar. Z całej klasy interesuje nas właściwie tylko funkcja (metoda) add_node().

W powyższym przykładzie widzimy, że przyjmuje ona tablicę parametrów. Parametr id określa unikatowy identyfikator danego elementu i musimy jakiś podać, nawet jeśli nie zamierzamy się do niego odwoływać. Parametr title pozwala na podanie tekstu, który ma być wypisany na toolbarze.

Efektem działania naszej funkcji jest nowy element toolbara

Admin Bar WP_DEBUG

Funkcja add_node()

Funkcja add_node() przyjmuje jako parametr tablice z parametrami:

id – unikatowy identyfikator dodawanego elementu;

title – tekst, który będzie widoczny na toolbarze;

parent – identyfikator elementu nadrzędnego jeśli dodajemy całe menu. Ten parametr możemy pominąć lub podać false, jeśli dodajemy element na pierwszym poziomie (głównej belce) toolbara;

href – adres url, do którego ma linkować title. Jak widać z naszego pierwszego przykładu ten parametr można pominąć jeśli podawane title jest tylko informacją i nie musi do niczego linkować;

group – identyfikator grupy, do której ma być dodany element. Grupowanie ma tylko znaczenie wizualne. Zgrupowane razem elementy, odpowiednio stylując  możemy odsunąć nieco od innych albo na przykład nadać im inny kolor. W naszych przykładach ten parametr pomijamy.

meta – tablica z bardziej zaawansowanymi parametrami, którymi możemy bardziej zaingerować w wygląd i zachowanie danego elementu toolbara.

class – klasa CSS która zostanie dodana do danego elementu pozwalając nam na nadanie mu innych styli niż ma reszta toolbara.

onclick – atrybut onclick linku podanego w parametrze href

title – atrybut title linku podanego w parametrze href (tekst, który pojawia się kiedy najedziemy kursorem myszki na dany element toolbara)

target – możemy otworzyć link podany w href w nowej karcie przeglądarki

tabindex – określa pozycję w kolejności wszystkich elementów toolbara kiedy poruszamy się po nim bez myszki (klawiszem TAB)

html – pozwala nam podać dowolny HTML, który zostanie wstawiony na toolbar. Ponieważ struktura HTML toolbara oparta jest na listach < ul> , podany przez nas kod zostanie umieszczony wewnątrz odpowiedniego taga < li>

Jak widać mechanizm jest bardzo elastyczny, daje praktycznie nieograniczone możliwości, w granicach zdrowego rozsądku.

Zmiana wyglądu dodawanego elementu

Teraz kiedy znamy już wszystkie parametry funkcji add_node()  możemy poprawić nieco wygląd dodanego przez nas elementu. Jeśli informacja jest krytyczna, możemy chcieć wyświetlić ją w sposób bardziej krzykliwy. Poza tym możemy ustawić kursor myszki  na normalną strzałkę oraz zadbać o to, aby po wskazaniu kursorem myszki element się nie zmieniał (tak się dzieje domyślnie), ponieważ nie jest to element klikalny.

W tym celu zmodyfikujemy nieco wywołanie funkcji add_node() dodając klasę .red-alert, którą wykorzystamy do stylowania elementu. Musimy też dodać do strony odpowiednie style. Ponieważ jest to dosłownie kilka linii najwygodniej jest wykorzystać do tego haki  admin_print_styles, który pozwala na dodanie styli do sekcji < head> admina WordPressa oraz wp_print_styles, który dodaje style do sekcji < head> frontu serwisu.

W tym wypadku możemy wszystkie te operacje zamknąć w warunek, który ograniczy ich wykonanie tylko do sytuacji kiedy toolbar jest wyświetlany (funkcja is_admin_bar_showing()) oraz WP_DEBUG jest zdefiniowane i ma wartość true. Kod nie będzie wykonywany gdy serwis jest oglądany przez użytkowników.

if (defined('WP_DEBUG') && WP_DEBUG  && is_admin_bar_showing()) {
    add_action( 'admin_bar_menu', 'my_better_debug_info', 92);

    function my_better_debug_info ( $wp_admin_bar ) {
        $wp_admin_bar->add_node(array(
            'id'    =>  'id_my_debug_info_2',
            'title' =>  "WP_DEBUG",
            'meta'  =>  array (
                'class'  => 'red-alert'
            )));
    }

    add_action('admin_print_styles','my_print_admin_styles');
    add_action('wp_print_styles','my_print_admin_styles');

    function my_print_admin_styles () {
        ?>
        <style type='text/css'>
            .red-alert div, .red-alert div:hover {
                color: white !important;
                font-weight: bold !important;
                background-color: #ff0000 !important;
                cursor: default;
            }
        </style>
    <?php
    }
}

Teraz nasz element jest czerwony i na pewno nikt go nie przegapi.

Admin Bar WP_DEBUG2

Dodawanie przycisku

Dodawanie statycznej informacji może się przydać czasem, ale znacznie bardziej użyteczne są aktywne przyciski, które robią coś użytecznego. Na przykład mogą linkować do serwisu WPinternals.pl żebyśmy nie zapomnieli o tym, aby regularnie go odwiedzać 🙂

add_action( 'admin_bar_menu', 'my_usefull_link', 93);

function my_usefull_link ( $wp_admin_bar ) {
    $wp_admin_bar->add_node( array(
        'id'    =>  'id_link_wpinternals',
        'title' =>  'WPinternals',
        'href'  =>  'https://wpinternals.pl/',
        'meta'  =>  array (
            'target'    => '_blank',
        ),
    ) );
}

Admin Bar WPinternals

Statyczny link do WPinternals.pl jest fajny, ale możemy go równie dobrze umieścić na pasku linków przeglądarki. Zróbmy coś ciekawszego:

add_action( 'admin_bar_menu', 'my_facebook_debug', 94);

function my_facebook_debug ( $wp_admin_bar ) {
    if (is_singular()) {
        $wp_admin_bar->add_node( array(
            'id'    =>  'id_link_facebook_dt',
            'title' =>  'Facebook Debug',
            'href'  =>  'https://developers.facebook.com/tools/debug/og/object?q='.urlencode($_SERVER["HTTP_HOST"] . $_SERVER["REQUEST_URI"]),
            'meta'  =>  array (
                'target'    => '_blank',
            ),
        ) );
    }
}

Powyższy kawałek kodu dodaje na pasek admina przycisk, który pojawia się tylko na stronie pojedynczego wpisu lub strony (sprawdzamy to funkcją is_singular()). Dzięki niemu możemy jednym klikiem sprawdzić dany wpis w narzędziu developerskim Facebooka. Powie nam ono, jak dobrze nasza strona jest przygotowana do dzielenia się nią na Facebooku i innych serwisach społecznościowych. Sprawdzane są tagi OpenGraph, wielkość obrazków, itd. Możemy podglądnąć tytuł i opis strony tak, jak widzi go Facebook. Dobrze jest zawsze korzystać z tego narzędzia przed udostępnieniem wpisu, unikamy wtedy głupich pomyłek. Z narzędzia możemy skorzystać też ręcznie wklepując: https://developers.facebook.com/tools/debug/ i podając adres linku do wpisu, ale wygodniej jest zrobić to jednym klikiem.

Admin Bar Facebook Debug

Dodawanie całego menu

Jeśli chcemy dodać do paska admina więcej elementów nierozsądne jest upychanie ich na głównym poziomie paska. Znacznie lepiej jest dodać własne menu , które po rozwinięciu będzie prezentowało wszystkie dodane przez nas elementy.

jeśli chcemy dodać całe menu, najpierw dodajemy jego główną opcję (tę która rozwija menu) a następnie pozostałe opcje, podając opcję główną w parametrze parent.

add_action( 'admin_bar_menu', 'my_toolbar_menu', 95);

function my_toolbar_menu ($wp_admin_bar ){
    $wp_admin_bar->add_node(array(
        'id'    =>  'id_my_menu',
        'title' =>  "My menu",
        'href'  => '#',
    ));
    $wp_admin_bar->add_node(array(
        'id'     =>  'id_faceboook',
        'title'  =>  'My Facebook fanage',
        'href'   =>  'https://www.facebook.com/wpinternals',
        'parent' =>  'id_my_menu',
    ));
    $wp_admin_bar->add_node(array(
        'id'     =>  'id_google',
        'title'  =>  'My Google page',
        'href'   =>  'https://plus.google.com/+WpinternalsPl/',
        'parent' =>  'id_my_menu',
    ));
    $wp_admin_bar->add_node(array(
        'id'     =>  'id_wpinternals',
        'title'  =>  'Google Webmaster Tools',
        'href'   =>  'https://www.google.com/webmasters/tools/dashboard?siteUrl='.urlencode($_SERVER["HTTP_HOST"]),
        'parent' =>  'id_my_menu',
    ));
}

Powyższy przykład dodaje na pasek admina menu, w którym znajdują się linki do stron powiązanych z witryną – do fanpage na Facebooku, strony na Google+ oraz Sekcji w Google Webmaster Tools.

Admin Bar Menu

Obsługa przycisku admin menu w AJAXie

Czasem możemy chcieć, żeby przycisk dodany na pasek admina robił coś bez przeładowania strony. Wtedy oczywiście wykorzystujemy AJAX.

Wyobraźmy sobie, że na własną rękę lub korzystając z WP_Object_Cache, cachujemy jakieś elementy strony na serwerze memcached, aby zwiększyć wydajność serwisu. Z różnych powodów możemy chcieć w jakimś momencie opróżnić cache, po to, aby mieć pewność, że kolejno otwierane strony będą świeżo wygenerowane. W tym celu dodamy na pasek admina przycisk Wyczyść cache.

add_action( 'admin_bar_menu', 'evp_ct_cache_flush', 100);

function evp_ct_cache_flush( $wp_admin_bar ) {
    global $wp_admin_bar;
    $wp_admin_bar->add_node(array(
        'id'    => 'id_flush_cache',
        'title' => 'Wyczyść cache',
        'href'  => '#',
    ));
}

Następnie piszemy funkcję, która dokonuje faktycznego czyszczenia cache. Będzie ona wywoływana przez AJAX, zatem jej działanie powinno się zakończyć przez exit. Przy okazji będziemy zwracać rezultat w formie odpowiedniego komunikatu tekstowego.

function my_ajax_cache_flush_all () {
    if ( !extension_loaded('memcache') )
        exit ('Rozszerzenie memcached dla PHP nie zostało załadowane');
    $cache = new Memcache();
    if ( !$cache->connect('localhost',11211) )
        exit ('Nie mogę się połaczyć z lokalnym serwerem memcached');
    $cache->flush();
    exit ("Cache opróżniony pomyślnie");
}

Mamy więc funkcję, która czyści cache i guzik, który to ma wywołać. Piszemy krótki skrypt JS z wykorzystaniem jQuery, które jest zawsze dostępne w WordPressie:

jQuery(document).ready(function($){
    $('#wp-admin-bar-id_flush_cache').on('click',function () {
        $.ajax({
            type : "post",
            url  : ajax_par.ajaxurl,
            data : { action: "cache_flush_all" },
            success: function(data, status) {
                alert(data);
            },
            error: function(errorThrown){
                console.log(errorThrown);
            }
        });
    })
});

W linii 6 widzimy parametr action, któremu przypisana jest wartość cache_flush_all

Aby spowodowało to wywołanie naszej funkcji czyszczącej cache ( my_ajax_cache_flush_all()) musimy ją „podpiąć” na haka o nazwie

wp_ajax_cache_flush_all

czyli złożonej z przedrostka wp_ajax_ i tego co jest podane w polu action w javascripcie.

add_action('wp_ajax_cache_flush_all', 'my_ajax_cache_flush_all');

Pozostaje tylko sprawić, że plik JS zostanie dołączony do strony (zarówno w adminie jak i po frontowej stronie serwisu). Załóżmy, że będzie miał nazwę cache.js i będzie się znajdował w podkatalogu js/ w naszym motywie:

if (is_admin_bar_showing()) {
    add_action( 'admin_enqueue_scripts', 'my_enqueue_js' );
    add_action( 'wp_enqueue_scripts', 'my_enqueue_js' );
    
    function my_enqueue_js () {
            wp_enqueue_script ( 'mycache', get_template_directory_uri().'/js/cache.js', array('jquery'));
            wp_localize_script( 'mycache', 'ajax_par', array( 'ajaxurl' => admin_url( 'admin-ajax.php' ) ) );
        }
}

Powyższy przykład zadziała  niezależnie od tego czy mamy serwer memcached, czy mamy zainstalowane rozszerzenie PHP do jego obsługi czy nie – w zależności od sytuacji otrzymamy różne komunikaty.

Admin Bar Ajax Button

Powyższa implementacja AJAXa jest najprostsza możliwa, wykład na ten temat wykracza poza ramy tego poradnika. Akurat kiedy powstawał ten tekst, fajny poradnik wprowadzający do AJAXa pojawił się na blogu dev.wpzlecenia.

Wtyczki do manipulowania paskiem admina

Jeśli ktoś nie potrafi lub nie chce programować, może skorzystać z jednej z całej masy wtyczek, przy pomocy których można manipulować paskiem admina, kolorować go, dodawać elementy, menu, kasować, zmieniać ich kolejność itd. Wyróżniają się:

Enhanced Admin Bar with Codex Search

Custom Admin Bar

Toolbar Remixed – Free

Admin Toolbar Menus

Powiadomimy Cię o nowych artykułach

Komentarzy: 2

  1. A znasz jakiś plugin który by umożliwiał zwijanie i rozwijanie (chowanie i pokazywanie) tego paska administracyjnego?