Wordpress: Простые шорткоды

Впервые шорткоды стали довольно популярными в WordPress 2.5. Они явились удобным способом предоставить пользователям возможность легко добавлять содержимое, генерируемое плагинами или темами на любой странице или в посте без необходимости глубоких знаний PHP и необходимости редактирования файлов шаблона темы.

Этот рецепт объясняет, как создать простой пользовательский шорткод, который будет использоваться для быстрого добавления ссылки на текущую страницу в Twitter в любом посте или странице, таким образом внося некую автоматизацию повторяющейся задачи.

1. Перейдите в директорию плагинов движка WordPress: wp-content/plugins
2. Создайте там новую директорию и назовите её twitter-shortcode
3. Зайдите внутрь директории и создайте новый текстовый файл. Назовите его twitter-shortcode.php
4. Откройте ваш новый файл в текстовом редакторе и добавьте следующий код:

       <?php
       /*
           Plugin Name:    Twitter Shortcode
           Plugin URI:
           Description:    Этот плагин позволяет добавлять шорткод Twitter [tf]
           Version:        1.0
           Author:         Самый лучший автор
           Author URI:     http://xxxxxxx.xx/
           License:        GPLv2
       */
   

5. Добавьте следующую строку кода, чтобы объявить новый шорткод, просто с помощью двух символов "tf" и укажите имя функции, которая должна вызываться когда шорткод встретится в тексте поста или страницы (символы шорткода указываются здесь без квадратных скобок!):

   add_shortcode('tf', 'twitter_feed_shortcode' );
   

6. Далее добавляем реализацию функции-обработчика (я специально добавил пробелы в ссылку на Twitter, что бы она не считалась ссылкой, в реальном коде этих пробелов делать не нужно!):

   function twitter_feed_shortcode( $atts ) {
       return '<a href="h t t p : // twitter.com / ylefebvre">Twitter Feed</a>';
   }
   

7. Сохраняем файл
8. Идем в админку нашего сайта во вкладку Plugins
9. Находим наш плагин в списке и активируем его
10. Откройте какую-нибудь страницу или пост на редактирование и добавьте в его конец следующий (например) текст:

    Come and check out our [tf] for more information on this post.

11. Сохраните изменение.

Теперь если просмотреть пост или страницу на сайте то можно заметить, что символы [tf] в тексте страницы заменились на ссылку с текстом : Twitter Feed

Как это работает...

Шорткоды имеют сходство с action хуками и filters хуками. Функции-обработчики шорткодов вызываются, тогда когда пришло время для выполнения задачи, как это делают action хуки, но функции-обработчики должны вернуть результат своей работы посредством оператора return как это делают filter хуки.

Что касается входных данных, функция-обработчик шорткода будет получать входные данные в некоторых случаях, а в некоторых случаях функция-обработчик будет только лишь возвращать некий вывод.

При использовании в тексте поста или страницы, любой шорткод, в окружении пары квадратных скобок идентифицируется движком WordPress, который затем выполняет поиск функций-обработчиков, зарегистрированных для этого шорткода. Если таковая находится, то она вызывается и возвращаемый ею результат используется для замены оригинального текста шорткода в контенте. Если ни одна функция обработчики НЕ находится, то шорткод просто выводится в том виде, как он был прописан в контенте: [tf]

Так же, как и функции-обработчики фильтров, функции-обработчики шорткодов не должны выводить никакого содержимого непосредственно при помощи инструкций echo, print и т.п. т.к. скорее всего этот вывод будет проявляться в неожиданном месте в разметке страницы, потому что WordPress вызывает все функции-обработчики шорткодов еще до формирования страницы.

Для простых шорткодов, ктаких как в этом рецепте, функция-обработчик должна вернуть некую информацию (в нашем случае ссылку на твиттер), но она не получает каких-либо дополнительных данных в своих параметрах. При этом, в функции-обработчике можно использовать служебные функции, такие как get_the_ID, get_the_title, и др. утилитарные функции WordPress, чтобы иметь возможность производить соответствующий вывод тогда и там, где это нужно.

Другие типы шорткодов (которые мы будем рассматривать позже) будут иметь более сложный контекст и конфигурацию. Вообще в функции-обработчике шорткодов можно получать доступ к ранее сохраненным в базе данным - параметрам, но это мы так же рассмотрим несколько позже, когда будем проходить настройки пользователя и создание страницы администратора.

Предыдущие статьи этого цикла:

1. WordPress: С чего начинаются плагины
2. WordPress: Добавление контента в тег head страниц
3. WordPress: Функции для работы с путями
4. WordPress: Использование хуков фильтров
5. WordPress: Добавление содержимого в каждый пост при помощи фильтров
6. WordPress: Изменение содержимого страницы при помощи фильтров
7. Отлов ошибок при разработке плагинов