WordPress shortcode szybki tutorial

Wyobraźmy sobie, że mamy już gotowy zupełnie nowy szablon WordPress. Powymyślaliśmy różne, ładne ozdóbki i gotowe style do elementów treści. Mamy piękny „oddzielacz” treści pomiędzy sekcjami sekcji datą, komentarzami itp. albo utworzyliśmy specjalną klasę dla komunikatów, które szczególnie, albo w jakiś inny sposób, chcieliśmy wyróżnić. Jeszcze lepszy przykład – kod bloku reklamy – czy nie lepiej wstawiać w treści artykułu krótkie jednowyrazowe odwołanie, które automatycznie wstawi za nas cały długi kod JavaScript/HTML?

Jeżeli lubicie ułatwiać sobie życie i pracować mądrze a nie ciężko, to ten wpis jest dla Was!

Ważne tutaj jest to, że utworzyliśmy jakąś ilość dodatkowych klas, lub mamy fragment kodu, którego często używamy. Wiadome jest, że częste przełączanie w edytorze między trybem wizualnym a tekstowym jest dosyć uciążliwe – musimy oderwać ręce od klawiatury, sięgnąć po mysz i przełączyć się na drugą zakładkę, następnie znaleźć odpowiednią linijkę tekstu, wpisać HTMLowski tag, dodać do niego odpowiednią klasę, zakończyć owy tag, znów sięgnąć po mysz, przełączyć się z powrotem na tryb tekstowy. Teraz wystarczy już tylko wrócić do poprzedniej myśli i wznowić pisanie… Zabawne, prawda?

WordPress shortcodes zostały wprowadzone wraz z wersją 2.5 WordPress i od tamtej pory nieprzerwanie, pozwalają na zapisywanie powtarzających się bloków kodu, które często stosujemy w treści postu jako prostego „skrótowca”, który będzie naszym lekarstwem na problemy poprzedniego akapitu.

WordPress Shortcode – co to takiego

Shortcode (nie wiem czy mamy na to jakiś polski odpowiednik) to prosta funkcja, dzięki której możemy w sprytny sposób uprościć skomplikowane struktury kodu, których jesteśmy zmuszeni używać w treści wpisów. Najprostszy przykład shortcode, jaki w tej chwili przychodzi mi do głowy, to umieszczanie kodu reklamy w treści wpisu. Łatwiej jest wpisać w tekście shortcode – [[reklama]], niż przełączać się w tryb tekstowy i za każdym razem, gdy zachodzi potrzeba wstawienia reklamy, wklejania tam jej kodu.

Shortcode  może przyjmować parametry i zwraca wartość.

Po tym zacnym wstępie kilka przykładów z życia.

Załóżmy że mamy zdefiniowany jakiś piękny, oddzielający nagłówek od treści, paseczek (na obrazku obok, podkreślenie tuż pod głównym tytułem). Wspomniany „oddzielacz” składa się z dwóch pustych bloków div i kilku reguł CSS:

 

<div class="fancy-divider"><div></div</div>

Reguły CSS:

.fancy-divider{
    background: #ebebeb;
    margin-bottom:10px;
}
.fancy-divider div{
    width:40px;
    border-top: solid #601f17 1px;
}

Po wstawieniu w trybie tekstowym dwóch pustych divów i przełączeniu się z powrotem, edytor zawsze usuwa mi wewnętrzny pusty blok bez klasy. Może nie jest to najlepszy przykład i rozwiązanie na 'znikające bloki’ z edytora, więc może przedstawię problem w innym świetle. Załóżmy, że nie chce mi się pisać pod każdym nagłówkiem H1 całego kodu HTML, więc prościej będzie jeżeli pod nagłówkiem, bez żadnego przełączania się, napiszę tak:

<h1>To jest nagłówek</h1>
[fancy_divider]

 

Po opublikowaniu wpisu, albo w podglądzie, mój shortcode zostanie zastąpiony zdefiniowanym przeze mnie fragmentem kodu HTML. Jest to jeden z prostszych przykładów zastosowania shortcode. Nie przekazujemy żadnych dodatkowych parametrów. Następuje prosta podmiana shortcode na zdefiniowany wcześniej kod HTML.

WordPress Shortcodes. Jak to zrobić?

Otwieramy w edytorze plik motywu functions.php. Musimy do niego dodać funkcję, która „obsłuży” shortcode i powie WordPressowi, co z nim zrobić, a następnie ją 'zarejestrować’. Tek wygląda pełny kod mojego shortcode:

function css_fancy_divider(){
  return '<div class="fancy-divider"><div></div></div>';
}

add_shortcode('fancy_divider', 'css_fancy_divider');

Jedynym zadaniem funkcji css_fancy_divider() jest zwrócenie fragmentu kodu HTML, który wyświetli moją poziomą linię.

Druga funkcja add_shortcode(), rejestruje shortcode dla WP. Ta funkcja przyjmuje dwa argumenty – pierwszy, to nazwa shortocode, której będziemy używać w treści wpisów, drugi to nazwa funkcji, która obsłuży shortcode.

Zapisujemy i testujemy! U mnie działa, jak to mawiają najstarsi informatycy. 🙂

Teraz coś trudniejszego. Powiedzmy, że chcemy wstawić fragment tekstu w blok z wybraną klasą. – ot jakiś komunikat, albo ważna notka, którą chcemy wyróżnić. Ja mam aktualnie w szablonie zdefiniowaną klasę, której czasem używam w moich wpisach. tak:

HTML:

<div class="y_note">Przykładowy komunikat w wyróżnionym bloku</div>

CSS:

 .y_note{
    margin-top: 10px;
    background: #fdfccc;
    border:solid #ffdb55 1px;
    padding:10px;
    color: #2c2c2c;
    text-align:justify;
    line-height:18px;
}

Funkcje w pliku functions.php:

function css_y_note( $atts, $content = null )
{
  return '<div>'.$content.'</div>';
}
add_shortcode('y_note', 'css_y_note');

I użycie:

[y_note]Przykładowy komunikat w wyróżnionym bloku[/y_note]

AdSense w treści wpisu

Na koniec przykład, o którym wspominałem we wstępie – jak zrobić shortcode do reklam i jak umieszczać go w treści wpisu. W przykładzie wykorzystam reklamy Google AdSense. Zakładam, że wiesz już jak wygląda umieszczanie reklam na zwykłych stronach – rejestrujesz konto, tworzysz nową jednostkę reklamową, generujesz kod, który potem wklejasz do kodu strony. Tutaj również moglibyśmy dodać reklamy do któregoś z plików motywu, ale nie o to nam tutaj chodzi. Planowany efekt, to wplatanie małych reklam w treść wpisu, aby użytkownik zawsze, albo prawie zawsze je zauważył podczas czytania lub przeglądania treści wpisu.

Dla mojego przykładu wybrałem dwa typy reklam

• Mały kwadrat (200 x 200)
• Kwadrat (250 x 250)

Więc będę chciał stworzyć shortcode z możliwością wybrania rozmiaru reklamy (możliwością bo domyślnie chcę, aby pokazywał mi większy Kwadrat 250×250).

W tym miejscu należy zaznaczyć, że będziemy przekazywać parametr(y) do funkcji shortcode w taki sposób (przykład pochodzi z Kodeksu WOrdPress):

[myshortcode foo="bar" bar="bing"]

oraz, że zostaną przekonwertowane do postaci tablicy asocjacyjnej, jak poniżej:

array( 'foo' => 'bar', 'bar' => 'bing' )

Wracając do tematu. Wygenerowałem sobie kody reklam, które są gotowe do umieszczenia na stronę. Teraz otwieram plik functions.php i zaczynam od napisania funkcji:

function post_content_adsense( $atts ){
    $ads_mkwadrat = '<script type="text/javascript"><!--
    google_ad_client = "ca-pub-6983738891419313";
    /* NewDivide m kwadrat */
    google_ad_slot = "2267220148";
    google_ad_width = 200;
    google_ad_height = 200;
    //-->
    </script>
    <script type="text/javascript" src="http://pagead2.googlesyndication.com/pagead/show_ads.js"></script>';
    $ads_kwadrat = '<script type="text/javascript"><!--
    google_ad_client = "ca-pub-6983738891419313";
    /* NewDivide kwadrat */
    google_ad_slot = "3743953344";
    google_ad_width = 250;
    google_ad_height = 250;
    //-->
    </script>
    <script type="text/javascript" src="http://pagead2.googlesyndication.com/pagead/show_ads.js"></script>';

    extract(shortcode_atts(array(
    'format' => 'kwadrat',
    ), $atts));

    switch($format)
    {
        case 'kwadrat':
        return $ads_kwadrat;
        case 'mkwadrat':
        return $ads_mkwadrat;
        default:
        return $ads_kwadrat;
    }
}

W zmiennych $ads_mkwadrat i $ads_kwadrat przechowuję odpowiednie kody reklam. Następna konstrukcja ma za zadanie określić domyślne ustawienia. Funkcja extract() „wypakowuje” zmienne z tablicy do oddzielnych zmiennych. Dlatego później możemy odwołać się do $format w taki sposób, jak na listingu.

Na podstawie przesłanej zmiennej $format, konstrukcja switch decyduje, który kod reklamy zwrócić. Pozostało zarejestrowanie nowego shortcode w WP –

add_shortcode('adsense', 'post_content_adsense');

I tym sposobem stworzyliśmy bardzo fajną funkcjonalność do motywu. Do takiej funkcji można łatwo dodać inne rodzaje reklam – wystarczy dodać kolejny kod reklamy, i kolejnego CASEa w SWITCHu.

Przykłady użycia w edytorze:

[adsense]

[adsense format=kwadrat]

[adsense format=mkwadrat]

Opcjonalnie, kod reklamy można zamknąć w bloku i dodać do niego jakieś klasy CSS, np. np opływanie, aby treść wpisu ładnie opływała blok reklamy. Można to zrobić na „sztywno” tj z góry nadać klasę, której zawsze będziemy się trzymać, lub przekazywać kolejny parametr do funkcji shortcode, który będzie „doklejał” klasę CSS. Ja zrobiłem to na sztywno, i dodałem tę samą klasę, którą wykorzystuje przy np obrazkach, bo reklama z prawej strony wpisu raczej kiepsko się tutaj prezentuje. Kody reklam poprawiłem w następujący sposób:

    $ads_mkwadrat = '<div class="alignleft"><script type="text/javascript"><!--
    google_ad_client = "ca-pub-6983738891419313";
    /* NewDivide m kwadrat */
    google_ad_slot = "2267220148";
    google_ad_width = 200;
    google_ad_height = 200;
    //-->
    </script>
    <script type="text/javascript" src="http://pagead2.googlesyndication.com/pagead/show_ads.js"></script></div>';

Na koniec ciekawostka:

Jeżeli nie chcesz, aby shortcode był interpretowany przez WordPress, a jedynie wyświetlony jego prawidłowy kod w poście, np.:

[moj_shortcode]

Wystarczy umieścić nazwę shortcode-u w podwójnych nawiasach kwadratowych, o tak:

[[moj_shortcode]]

Albo 'zamknąć’ nazwę shortcode-u w dodatkowym tagu (w edytorze tekstowym), np. tak:

[<span>moj_shortcode</span>]

Jeżeli shortcode składa się z dwóch części – otwierającej i zamykającej, a chcemy wyświetlić przykładowy kod pokazujący jego użycie, możemy to zrobić tak:

[[moj_shortcode]Przykładowy komunikat w wyróżnionym bloku[/moj_shortcode]]

Czyli wystarczy umieścić kwadratowy nawias otwierający przed pierwszym shortcode-m, oraz dodatkowy, zamykający nawias kwadratowy za tagiem zamykającym shortcode.

I to na dzisiaj wszystko,

Aktualizacja 2017-07-10

Aktualizacja wpisu. Dodałem nowy obrazek wyróżniający. Zamieniłem, zaktualizowałem i dodałem nowe wyjaśnienia. Mam nadzieję, że na bardziej trafne i bardziej zrozumiałe.