Розробка шорткодів (Shortcodes) для WordPress

Розробка WordPress Шорткодів

Шорткод — механізм WordPress, що дозволяє редакторам вставити довільний PHP-вивід прямо в вміст поста за допомогою команди на зразок [my_shortcode param="value"]. Редактори не потребують знань PHP, не мають доступу до шаблонів — але через шорткод можуть вставити таблицю, форму, віджет або карту будь-де в контенті. Реалізація простого шорткода займає кілька годин; шорткод зі складним рендерингом і налаштуваннями — 1–2 дні.

Реєстрація шорткода

add_shortcode('my_button', 'my_button_shortcode_handler');

function my_button_shortcode_handler(array $atts, ?string $content = null): string {
    $atts = shortcode_atts([
        'url'    => '#',
        'color'  => 'primary',
        'target' => '_self',
        'size'   => 'md',
    ], $atts, 'my_button');

    // Санітизація
    $url    = esc_url($atts['url']);
    $color  = sanitize_html_class($atts['color']);
    $target = in_array($atts['target'], ['_self', '_blank']) ? $atts['target'] : '_self';
    $size   = in_array($atts['size'], ['sm', 'md', 'lg']) ? $atts['size'] : 'md';
    $label  = $content ? wp_kses_post($content) : 'Натисніть';

    return sprintf(
        '<a href="%s" target="%s" rel="%s" class="btn btn--%s btn--%s">%s</a>',
        $url,
        $target,
        $target === '_blank' ? 'noopener noreferrer' : '',
        esc_attr($color),
        esc_attr($size),
        $label
    );
}

shortcode_atts() об'єднує атрибути, надані користувачем, зі стандартними. Третій параметр — назва шорткода — дозволяє фільтрувати стандартні значення через shortcode_atts_my_button.

Шорткод з вкладеним вмістом

add_shortcode('my_tabs', 'my_tabs_shortcode');
add_shortcode('my_tab', 'my_tab_shortcode');

function my_tabs_shortcode(array $atts, ?string $content = null): string {
    if (!$content) return '';
    // do_shortcode обробляє вкладені [my_tab]
    $inner = do_shortcode($content);
    return '<div class="my-tabs">' . $inner . '</div>';
}

function my_tab_shortcode(array $atts, ?string $content = null): string {
    $atts = shortcode_atts(['title' => 'Вкладка', 'active' => 'no'], $atts, 'my_tab');
    $is_active = $atts['active'] === 'yes' ? ' my-tab--active' : '';
    $title = esc_html($atts['title']);
    $body = $content ? do_shortcode($content) : '';
    return "<div class=\"my-tab{$is_active}\" data-title=\"{$title}\">{$body}</div>";
}

Використання в редакторі:

[my_tabs]
  [my_tab title="Опис" active="yes"]Вміст першої вкладки[/my_tab]
  [my_tab title="Характеристики"]Список характеристик[/my_tab]
[/my_tabs]

Шорткод з запитом до бази даних

add_shortcode('recent_projects', function (array $atts): string {
    $atts = shortcode_atts([
        'count'    => 3,
        'category' => '',
        'columns'  => 3,
    ], $atts, 'recent_projects');

    $args = [
        'post_type'      => 'project',
        'posts_per_page' => absint($atts['count']),
        'post_status'    => 'publish',
    ];

    if ($atts['category']) {
        $args['tax_query'] = [[
            'taxonomy' => 'project_category',
            'field'    => 'slug',
            'terms'    => sanitize_title($atts['category']),
        ]];
    }

    $query = new WP_Query($args);

    if (!$query->have_posts()) {
        return '<p>Проекти не знайдені.</p>';
    }

    ob_start();
    echo '<div class="projects-grid projects-grid--cols-' . absint($atts['columns']) . '">';
    while ($query->have_posts()) {
        $query->the_post();
        get_template_part('template-parts/project-card');
    }
    wp_reset_postdata();
    echo '</div>';
    return ob_get_clean();
});

ob_start() / ob_get_clean() — стандартний спосіб захопити вивід шаблонних частин, які використовують echo замість return.

Кешування результатів

Шорткоди з запитами до БД або зовнішніх API слід кешувати через Transients API:

add_shortcode('exchange_rates', function (): string {
    $cache_key = 'my_exchange_rates';
    $cached = get_transient($cache_key);
    if ($cached !== false) {
        return $cached;
    }

    $response = wp_remote_get('https://api.exchangerate.host/latest?base=USD&symbols=EUR,GBP');
    if (is_wp_error($response)) {
        return '<p>Дані недоступні.</p>';
    }

    $data = json_decode(wp_remote_retrieve_body($response), true);
    $html = '<ul class="rates">';
    foreach ($data['rates'] as $currency => $rate) {
        $html .= "<li><strong>{$currency}:</strong> " . number_format($rate, 2) . '</li>';
    }
    $html .= '</ul>';

    set_transient($cache_key, $html, HOUR_IN_SECONDS);
    return $html;
});

TTL слід вибирати залежно від того, як часто змінюються дані. Для курсів валют достатньо 1 години; для лічильника відвідувачів кешування шкідливе.

Реєстрація кнопки в Gutenberg

Щоб редактори могли вставити шорткод кнопкою, а не вводити вручну, додайте кнопку в TinyMCE (класичний редактор) або обгортку блоку для Gutenberg:

// TinyMCE плагін — додавання кнопки в редактор
(function ($) {
  tinymce.create('tinymce.plugins.my_shortcodes', {
    init: function (ed) {
      ed.addButton('my_button_shortcode', {
        title: 'Вставити кнопку',
        image: myShortcodesAdmin.pluginUrl + '/icon.svg',
        onclick: function () {
          const url = prompt('URL кнопки:');
          const label = prompt('Текст кнопки:');
          if (url && label) {
            ed.insertContent(`[my_button url="${url}"]${label}[/my_button]`);
          }
        },
      });
    },
  });
  tinymce.PluginManager.add('my_shortcodes', tinymce.plugins.my_shortcodes);
})(jQuery);

Шорткоди проти блоків Gutenberg

Шорткоди не застаріли, але мають обмеження: немає попереду в редакторі, синтаксис неясний для редактора. Для нових проектів на Gutenberg краще створювати користувацькі блоки (окрема послуга). Шорткоди залишаються оптимальним вибором для Classic Editor, Elementor, WPBakery та будь-яких сторонніх конструкторів, які можуть обробляти do_shortcode().