13 10 10 Użycie makrokodów w Wordpresie

Jak zawsze dodany przez : Sylwek, komentarze: ( 0 )

W tym wpisie skupię się na makrokodach (shortcodes) w Wordpresie. Funkcjonalność, o której mowa, jest dostępna w systemie od wersji 2.5. Makrokody zostały stworzone po to, aby umożliwić pośrednie osadzenie kodu PHP w treści wpisu. Rozwiązano tym samym problem, który zdążył już doczekać się wielu wątpliwych technicznie rozwiązań.

Z punktu widzenia użycia, makrokody w Wordpresie przypominają filtry. W praktyce więc mamy do czynienia z nazwą makrokodu, do którego podłączamy kod do wykonania (w postaci metody klasy lub zwykłej funkcji).

Makrokody są przechowywane podobnie jak filtry w nieuporządkowanej tablicy PHP.
Każdy makrokod może mieć przyporządkowaną jedną funkcję do wykonania.Funkcja ta nie powinna nieczego wyświetlać ale zwracąć łańcuch znaków.

Aby makrokod mógł zadziałać, konieczna jest jego rejestracja, co wykonuje się z pomocą funkcji add_shortcode w pliku functions.php aktywnego motywu lub pliku wtyczki.

Osadzenie makrokodu we wpisie wymaga zastosowania specjalnej składni, która przypomina tę znaną z BBCode.

Rejestracja makrokodu

Rejestracja makrokodu i dodanie kodu dla niego może wyglądać jak poniżej:

add_shortcode('makrokod','funkcja_do_wykonania')

function funkcja_wykonania(){
  // ten kod zostanie wykonany
}

Aby skorzystać z tak zarejestrowanego makrokodu wystarczy wstawić gdzieś we wpisie:

[makrokod]

WordPress wywołuje makrokody z pomocą funkcji do_shortcode, która jako jedyny argument pobiera łańcuch znaków do przefiltrowania. Jeżeli znaleziony zostanie w nim jakiś zarejestrowany makrokod, wykonany będzie podczepiony do niego kod.

Wewnętrznie do odpalenia podczepionej funkcji lub metody dla makrokodu wykorzystywana jest standardowa funkcja PHP o nazwie call_user_func. Call_user_func może wywołać funkcję z dodatkowymi argmentami, API makrokodów skwapliwie z tego korzysta.

Makrokody z argumentami

Jeżeli chcemy zarejestrować makrokod, dla którego będzie wywoływana funkcja z arguemtnami możemy tego dokonać jak następuje:

add_shortcode('makrokod','kod_do_wykonania')

function kod_do_wykonania($atts) {
  extract(
    shortcode_atts(
      array(
        'attr1' => 'wartość 1'
      ),
    $atts)
  );
  return "attr1 = {$attr1}";
}

Aby skorzystać z tak zarejestrowanego makrokodu, należy dodać gdzieś w treści wpisu bloga kod jak poniżej:

[makrokod]

W rezultatcie otrzymamy: attr1 = wartość 1.

Identyczny do poprzedniego kod można wywołać z argumentem jak następuje:

[makrokod attr1="inna_wartość"]

Będzie on skutkował wyświetleniem: attr1 = inna_wartość.

Tytułem przypominienia dodam, że funkcja extract służy do importowania zmiennych do aktualnej tablicy symboli. Funkcja shortcode_atts łączy dwie tablice zastępując nieistniejące wartości w drugiej z nich tymi z pierwszej.

Należy zwrócić uwagę na nazwy atrybutów użytych w makrokodach bo wszystkie duże litery zostają standardowo zaminione na małe.

Makrokod może mieć domknięcie:

[makrokod]zawartość do przefiltrowania[/makrokod]

W takim wypadku funkcja dodana do makrokodu otrzyma drugi atrybut, którym będzie łańcuch znaków znajdujący się miedzy początkiem i końcem taga makrokodu (w przykładzie powyżej będzie to "zawartość do przefiltrowania").

function a_paragraph( $atts, $fragment_tekstu = null ) {
   return '<p>' . $fragment_tekstu . '</p>';
}

add_shortcode('makrokod','a_paragraph')

Do wywoływanie makrokodów na określonej zawartości w Wordpresie służy funkcja do_shortcode, która przyjmuje łańcuch znaków jako jedyny argument.

do_shortcode('some_content');

Aby wyczyścić tablicę z makrokodami, efektywnie wyrejestrowując je wszystkie, należy skorzystać z funkcji remove_all_shortcodes.

remove_all_shortcodes()

Aby usunąć pojedyńczy makrokod o określonej nazwie, korzystamy z funkcji remove_shortcode, która przyjmuje nazwę makrokodu do wyrejestrowania.

remove_shortcode('makrokod')

Przykład użycia makrokodów

Z pomocą makrokodów można umieścić reklamy we treści wpisu.
Trywialny przykład może wyglądać jak następuje.

function display_my_ad($atts){
  $default_ad = 1;
  $ads = array(
    'Reklama pierwsza',
    'Reklama druga',
    'Reklama trzecia'
  );
  $html = '';

  $ad_count = count($ads);
  if(is_array($atts)){
    extract($atts);
  }

  $ad = ( isset($ad) and array_key_exists($ad,$ads) ) ? intval($ad) : $default_ad;
  $html = "<div>";
  $html .= $ads[$ad] ;
  $html .= "</div>";
  return $html;
}
add_shortcode('display_ad','display_my_ad')

Kod należy umieścić w pliku functions.php aktywnego motywu. Wywołanie może wyglądać jak następuje:

[display_ad ad=2]

Jak widać użycie makrokodów w Wordpresie jest dość łatwe.
Pełną dokumntację i wszystkie funkcje wchodzące w skład API można znaleźć w pliku wp-includes/shortcode.php.

Kategorie: wordpress
Tagi: makrokod