WordPress: ShortCode

SchortCode to proste funkcje udostępniane w formie mini-kodu, bardzo podobnego do BBCode. Co dają nam te małe stworzenia? Dzięki nim, możemy z powodzeniem wywołać jakąś funkcję PHP w naszym poście, co domyślnie jest niemożliwe, lub za pomocą jednego znacznika wstawić w dowolnym miejscu artykułu kod HTML. Więc, gdy będziemy chcieli umieści np. obrazek z podpisem w jakiejś ramce, to zamiast kilku linijek wystarczy jedna. Jak zatem wygląda taki ShortCode?

Składnia

Istnieją 4 typy ShortCode:
Pierwszy z nich ma postać pojedynczego tagu. Najczęściej stosuje się go do wstawienia jakiegoś z góry określonego kody, w który nie mamy możliwości ingerencji pisząc nasz post.

[nazwa_shortcode]

Istnieje jednak odmiana takiego sposobu, w której przekazując atrybuty, możemy wpływać na efekt działania funkcji, otrzymując dzięki temu inny wynik.

[nazwa_shortcode atrybut="wartość"]

Trzecim typem są shortcody przypominające BBCode. Otaczają one fragment teksu który chcemy w dowolny sposób sformatować.

[nazwa_shortcode]Fragment tekstu[/nazwa_shortcode]

Tak jak w pierwszym przypadku, tak i tu możemy skorzystać z pomocy parametrów, w celu większej kontroli.

[nazwa_shortcode atrybut="wartosc"]
   Fragment tekstu
[/nazwa_shortcode]

Skoro wiemy już jak wyglądają shortcode, postarajmy się samemu napisać jeden przykładowy.

Nasz pierwszy ShortCode

ShortCode od strony technicznej składa się z dwóch elementów. Pierwszy z nich, a zarazem najważniejszy to funkcja generująca potrzebny kod. Dla przykłady, chcemy wyświetlić na stronie napis „Hello Word”. Potrzebny kod może wyglądać tak:

function hello_word(){
  echo "Hello word";
}

Następnym krokiem będzie rejestracja shortcode. Tu korzystamy z drugiego elementu, jakim jest funkcja add_shortcode. Przyjmuje ona dwa parametry: nazwę shortcode używaną w postach oraz dopasowaną do niego funkcję, wywoływaną podczas parsowania. Po niżej zamieszczam przykład:

add_shortcode('hello_word', 'hello_word');

Caly kod który umieszczamy w pliku functions.php naszej skórki:

function hello_word(){
  echo "Hello word";
}

add_shortcode('hello_word', 'hello_word');

Teraz wystarczy, że w poście, w dowolnym miejscu umieścimy taki fragment:

[hello_word]

… a zamiast niego ujrzymy tekst „Hello word”.

Co z dynamiką?

Udało nam się napisać swój pierwszy shortcode. Zmodyfikujmy go teraz tak, by wyświetlał tekst w wybranym przez nas kolorze. Wywołanie następować będzie w taki sposób:

[hello_word color="red"]

Zanim pokaże jak powinien wyglądać zmodyfikowany kod, wyjaśnię działanie następnej ważnej funkcji jaką jest shortcode_atts

shortcode_atts($default_array, $atts);

Parametr $default_array jest tablicą asocjacyjną, zawierającą akceptowane atrybuty wraz z ich domyślnymi wartościami. Drugi parametr różni się od pierwszego tym, że zawiera te parametry które sami przekazaliśmy, np. tablica $atts dla tego shortcode:

[hello_word color="red"]

będzie wyglądać tak:

array('color' => 'red');

Wynikiem funkcji będzie następna tablica, w której kluczom z tablicy $default_array zostaną dopasowane wartości przekazane przez nas, lub wartości domyślne, jeżeli pominęliśmy jakiś parametr. Co się jednak stanie gdy podamy atrybuty nieakceptowane przez naszą funkcję? Zostaną one pominięte w wyniku. Przykład:

$result = shortcode_atts(array(
  'color' => 'blue',
  'size' => 15
  ), $atts);

Struktura tablicy $atts:

array('color' => 'red', 'font' => 'Arial')

Wynikiem działania funkcji będzie tablica $result o poniższej strukturze:

array('color' => 'red', 'size' => 15)

Jak widać wartość color została przesłana pomyślnie i przesłoniła wartość domyślną. Inaczej stało się z atrybutem font, który nie znalazł się na liście obsługiwanych parametrów, przez co nie został uwzględniony w wyniku. Skoro wiemy już jak działa funkcja shortcode_atts, sprawmy by nasz tekst „Hello word” został wyświetlony w dowolnym kolorze.

function hello_word($atts){
    $result = shortcode_atts(array(
      'color' => 'black',
    ), $atts);
    echo "<span style='color: ".$result['color']."'>Hello word</span>";
  }
  
  add_shortcode('hello_word', 'hello_word');

Aby zobaczyć efekty należy skorzystać z [hello_word color="red"&#93. Innym sposobem jest użycie funkcji extract() która stworzy nam zmienne zamiast tablicy.

function hello_word($atts){
    extract(shortcode_atts(array(
      'color' => 'black',
    ), $atts));
    echo "<span style='color: $color'>Hello word</span>";
  }

Gdzie podziały się znaczniki?

Do tej pory operowaliśmy na pojedynczych znacznikach, które w swoje miejsce wstawiały jakiś kod. Istnieje jednak też drugi sposób wykorzystania shortcode, który bardzo przypomina znane głównie z forum BBCode. Mowa o otoczeniu jakiegoś fragmentu tekstu znacznikiem otwierającym i zamykającym, przekazując go w ten sposób do naszej funkcji. Dla przykładu, spróbujmy wygenerować button z jakimś tekstem. Na początek musimy dodać drugi parametr do naszej funkcji, przez który przekazany zostanie otoczony fragment.

function button($atts, $content = null){...}

Zmienną $content ustawiłem na null, by móc wykorzystać shortcode w formie jednego znacznika. Może się to przydać np gdy chciałbym wygenerować przycisk bez tekstu, ale za to w kolorze. W następnym kroku przekazany fragment umieszczamy wewnątrz znacznika button i zwracamy wynik, który następnie zostanie wyświetlony w poście.

function button($atts, $content = null){
    extract(shortcode_atts(array(
      'color' => 'black',
    ), $atts));
    
    return "<button style='color: $color'>$content</button>";
  }
  
  add_shortcode('button', 'button');

Jak widać cały kod HTML został schowany do funkcji, dzięki czemu nasz post nie jest zaśmiecany tego typu elementami. Teraz tylko wystarczy wpisać:

[button]Kliknij[/button]

Powinniśmy zobaczyć przycisk z napisem „Kliknij”.

Incepcja

Połączmy teraz nasze shortcodes, próbując wyświetlić przycisk z napisem Hello word.

[button][hello_word][/button]

Ale co to? WordPress wygenerował nam przycisk, ale o Hello word już zapomniał. Jak widzisz nie jest to takie proste. Aby zagnieżdżanie zadziało, należy wewnątrz nadrzędnego shortcode użyć funkcji do_shortcode().

function button($atts, $content = null){
    extract(shortcode_atts(array(
      'color' => 'black',
    ), $atts));
    
    return "<button style='color: $color'>do_shortcode($content)</button>";
  }

Funkcja ta wynajduje w przekazanym tekście inne shortcode i wywołuje przypisane do nich funkcje. Po zmodyfikowaniu kodu powinniśmy ujrzeć poprawnie wygenerowany przycisk.

Podsumowanie

Przedstawiony tutaj sposób, powinien załatwić wszelkie problemy związane z wykonywaniem jakiejś funkcji PHP w poście lub z wielokrotnym powtarzaniem tego samego kodu. Zamiast pisać kilka znaczników, wystarczy wstawić jeden shortcode. Następnym razem przedstawię kilka praktycznych przykładów na wykorzystanie zdobytej dzisiaj wiedzy. Wszelkie niejasności proszę zgłaszać w komentarzach.