🛠 Jak dodać własny shortcode w WordPress: analiza add_shortcode() [+2 przykłady]

Stworzyli Państwo snippet, dodali do functions.php, a WordPress mówi „cheatin' uh?". Znajome? Shortcode'y, podstawowy mechanizm rozszerzania WordPressa, a add_shortcode() otwiera do niego dostęp w 15 linijkach kodu. Ale między „Hello World" a rzeczywistym scenariuszem czyhają pułapki: return kontra echo, kolejność parametrów funkcji callback, konflikt tagów.

Shortcode'y pojawiły się w WordPress 2.5 i od tego czasu stały się fundamentem ekosystemu: formularze kontaktowe, galerie, slidery, wyświetlanie pól niestandardowych, wszystko to żyje wewnątrz nawiasów kwadratowych. add_shortcode() nie zmieniała się od lat, a opanować ją można w pół godziny.

Poniżej pełna analiza funkcji z dwoma gotowymi przykładami: od roku autorskiego w stopce do listy użytkowników witryny.

💡 Szybki przegląd:

• Składnia i parametry add_shortcode(), tag i callback
• Zasada: zawsze return, nigdy echo
• Hook init, dlaczego bez niego shortcode może nie działać
• Dwa sposoby przekazywania danych: treść między tagami i atrybuty
• Gotowy kod: shortcode dla roku autorskiego i listy użytkowników

Jak działa add_shortcode() w WordPress

Funkcja add_shortcode() to punkt wejścia do rejestracji dowolnego niestandardowego shortcode'a. Przyjmuje dwa obowiązkowe parametry: unikalny tag i nazwę funkcji callback, która zwróci treść.

Zgodnie z dokumentacją WordPress, callback otrzymuje trzy argumenty w stałej kolejności:

• $attributes, tablica atrybutów przekazanych w shortcodzie
• $content, tekst między tagiem otwierającym a zamykającym
• $tag, nazwa tagu, pod którą shortcode jest zarejestrowany

Podstawowy przykład, shortcode wyświetlający „Hello World!":

1
// Callback-функція шорткоду
2
function hello_world_shortcode_callback( $attributes, $content, $tag ) {
3
    return 'Hello World!';
4
}
5
// Реєстрація шорткоду
6
function hello_world_shortcode() {
7
    add_shortcode( 'hello-world', 'hello_world_shortcode_callback' );
8
}
9
add_action( 'init', 'hello_world_shortcode' );

Kod dodaje się do functions.php motywu potomnego lub przez wtyczkę Code Snippets. Po tym [hello-world] w edytorze wpisu wyświetli „Hello World!".

Dlaczego return, a nie echo

Proszę zwrócić uwagę na return wewnątrz funkcji callback. Jeśli użyją Państwo echo, wyjście nastąpi zanim WordPress zbuduje resztę strony, „Hello World!" znajdzie się na samej górze, a otaczająca treść się rozjedzie.

Zasada jest prosta: **callback shortcode'a zawsze zwraca wartość przez ****return**. Żadnych echo, print ani bezpośredniego wypisywania HTML poza buforem.

Hook init jest obowiązkowy

Twórcy na WordPress.org zalecają wpinanie rejestracji shortcode'a na hook init, a nie wywoływanie add_shortcode() bezpośrednio w ciele functions.php. Bez init WordPress może nie zdążyć zainicjować wewnętrznych mechanizmów i shortcode po prostu nie zadziała.

Składnia i parametry

Sygnatura funkcji:

1
add_shortcode( string $tag, callable $callback )

$tag, nazwa shortcode'a (bez nawiasów). Jeśli dwie wtyczki zarejestrują shortcode z tym samym tagiem, ostatnia nadpisze poprzednią. Aby uniknąć konfliktów, należy dodawać unikalny prefiks: nie [gallery], a [myplugin_gallery].

$callback, nazwa funkcji zwracającej treść. Można przekazać ciąg z nazwą funkcji, funkcję anonimową lub metodę klasy (przekazując tablicę [ $object, 'method_name' ]).

Jak używać shortcode'ów w edytorze

W edytorze WordPress, Gutenberg czy Classic, shortcode wstawia się w nawiasach kwadratowych. Dla naszego przykładu:

[hello-world]

Pełna forma z tagiem zamykającym również działa:

[hello-world][/hello-world]

Drugi wariant jest potrzebny, gdy między tagami przekazywana jest treść (o tym poniżej).

Jak wywołać shortcode w PHP

W szablonach motywu lub wtyczkach shortcode'y uruchamia się przez do_shortcode():

1
echo do_shortcode( '[hello-world]' );

Funkcja przyjmuje ciąg ze shortcodem i zwraca wynik jego wykonania. Przydatna, gdy trzeba osadzić wyjście shortcode'a w logice PHP, na przykład w header.php lub wewnątrz pętli.

Przekazywanie danych do shortcode'a: dwa sposoby

Sposób 1: treść między tagami

Proszę umieścić dane między tagiem otwierającym a zamykającym:

[hello-world]from John to Mary[/hello-world]

Callback otrzymuje ciąg from John to Mary przez drugi parametr $content:

1
// Callback з підстановкою контенту між тегами
2
function hello_world_shortcode_callback( $attributes, $content, $tag ) {
3
    return 'Hello ' . $content . ' World!';
4
}
5
// Реєстрація
6
function hello_world_shortcode() {
7
    add_shortcode( 'hello-world', 'hello_world_shortcode_callback' );
8
}
9
add_action( 'init', 'hello_world_shortcode' );

Wynik: „Hello from John to Mary World!".

Sposób 2: atrybuty

Proszę przekazać parametry bezpośrednio w tagu otwierającym:

[hello-world from="John" to="Mary"][/hello-world]

W funkcji callback atrybuty są dostępne przez pierwszy parametr $attributes, tablicę asocjacyjną, gdzie klucze pokrywają się z nazwami atrybutów:

1
// Callback з читанням атрибутів шорткоду
2
function hello_world_shortcode_callback( $attributes, $content, $tag ) {
3
    return 'Hello from ' . $attributes['from'] . ' to ' . $attributes['to'] . '!';
4
}
5
// Реєстрація
6
function hello_world_shortcode() {
7
    add_shortcode( 'hello-world', 'hello_world_shortcode_callback' );
8
}
9
add_action( 'init', 'hello_world_shortcode' );

Wyjście: „Hello from John to Mary!". Atrybuty są wygodniejsze dla danych strukturalnych (cena, URL, ID), a treść między tagami, dla dowolnego tekstu.

W praktyce do atrybutów warto od razu dodać shortcode_atts(), wbudowaną funkcję WordPress, która scala przekazane atrybuty z tablicą wartości domyślnych. Bez niej odwołanie do $attributes['from'] rzuci notice PHP, jeśli użytkownik nie podał atrybutu. Z shortcode_atts() zawsze otrzymują Państwo wypełnioną tablicę: zadane klucze z wartościami fallback, a nieznane atrybuty są automatycznie filtrowane.

Dwa gotowe shortcode'y dla WordPress

1. Automatyczny bieżący rok

Shortcode [current-year], który sam podstawia aktualny rok, nie trzeba poprawiać daty w stopce każdego stycznia:

1
// Callback: повертає поточний рік через date('Y')
2
function current_year_shortcode_callback( $attributes, $content, $tag ) {
3
    return date( 'Y' );
4
}
5
// Реєстрація шорткоду [current-year]
6
function current_year_shortcode() {
7
    add_shortcode( 'current-year', 'current_year_shortcode_callback' );
8
}
9
add_action( 'init', 'current_year_shortcode' );

Proszę umieścić [current-year] w stopce lub tekście wpisu, a rok będzie aktualizował się automatycznie.

2. Lista zarejestrowanych użytkowników

Shortcode [users-list] wyświetla nazwy wszystkich użytkowników witryny w formie listy punktowanej. Przyda się na stronie „Zespół" lub w raportach administracyjnych:

1
// Callback: отримує всіх користувачів і формує HTML-список
2
function my_custom_users_list() {
3
    $users = get_users();
4
    $list_html = '<ul>';
5
    foreach ( $users as $user ) {
6
        $list_html .= '<li>' . $user->data->display_name . '</li>';
7
    }
8
    $list_html .= '</ul>';
9
    return $list_html;
10
}
11
// Реєстрація шорткоду [users-list]
12
function register_my_users_list_shortcode() {
13
    add_shortcode( 'users-list', 'my_custom_users_list' );
14
}
15
add_action( 'init', 'register_my_users_list_shortcode' );

get_users() bez argumentów zwraca wszystkich użytkowników. Aby ograniczyć wyniki do roli, proszę przekazać tablicę: get_users( [ 'role' => 'editor' ] ). Kod dodaje się do functions.php aktywnego motywu lub do niestandardowej wtyczki.

Wideo: tworzenie shortcode'ów w WordPress

Krótkie wideo na temat, rejestracja shortcode'a od zera, od napisania funkcji do testowania w edytorze:

⁉️🤔 Często zadawane pytania

Co się stanie, jeśli dwie wtyczki zarejestrują shortcode z tym samym tagiem?

WordPress wykona ten, który załadował się jako ostatni. Pierwszy shortcode zostanie nadpisany, po cichu, bez błędów. Dlatego w swoich shortcode'ach zawsze należy używać prefiksu: [acme_gallery] zamiast [gallery]. W ten sposób eliminują Państwo konflikt z jakąkolwiek inną wtyczką lub motywem.

Czy można wywoływać shortcode'y wewnątrz innych shortcode'ów?

Tak. Jeśli callback pierwszego shortcode'a zwraca ciąg z tagiem drugiego, WordPress automatycznie przetworzy zagnieżdżony shortcode. Ale proszę nie zapominać o do_shortcode(): jeśli tworzą Państwo treść ręcznie i znajdują się w niej shortcode'y, proszę przepuścić ciąg przez do_shortcode() jawnie. Standardowe zachowanie the_content robi to samodzielnie, ale bezpośrednie wywołanie funkcji callback, nie.

Gdzie umieszczać kod shortcode'ów, w motywie czy we wtyczce?

Niestandardowe shortcode'y niosą funkcjonalność, a nie wygląd, dlatego właściwiej jest wydzielić je do osobnej wtyczki. Zmiana motywu nie zepsuje witryny: shortcode'y będą nadal działać. Minimum to motyw potomny, jeśli na pewno nie planują Państwo zmiany głównego.

Czy są ograniczenia dotyczące nazwy tagu?

Nazwa musi składać się z liter łacińskich, cyfr i myślników. Spacje, podkreślenia i znaki specjalne są niedozwolone. Zalecana długość to do 20 znaków, małe litery. Przykład: [my-plugin-shortcode].

Jak debugować shortcode, jeśli nic nie wyświetla?

Pierwszy krok, proszę włączyć WP_DEBUG w wp-config.php. Drugi, proszę sprawdzić, czy callback zwraca wartość przez return, a nie echo. Trzeci, proszę upewnić się, że hook init jest obecny. Jeśli nie ma błędów, ale wyjście jest puste, proszę dodać error_log() w callbacku i sprawdzić logi serwera.

Co trzeba zapamiętać o shortcode'ach WordPress

Shortcode'y to dojrzały i stabilny mechanizm. add_shortcode() nie zmieniała się od lat: tag, callback, hook init, return zamiast echo. Proszę zapamiętać te cztery rzeczy, a każdy niestandardowy shortcode zadziała za pierwszym razem.

• Jeśli wyświetlają Państwo rok w stopce, proszę wziąć gotowy [current-year].
• Jeśli potrzebna jest lista użytkowników, [users-list] z filtrem według roli.
• Jeśli piszą Państwo własny shortcode od zera, zawsze prefiks i zawsze init.

Jako następny krok proszę zobaczyć, jak przekształcić shortcode w osobną wtyczkę i opublikować ją w katalogu WordPress.org, to najlepszy sposób, by oddzielić funkcjonalność od motywu i podnieść profil deweloperski.