Понимание шорткодов WordPress

Если вы используете WordPress какое-то время, вы, вероятно, уже использовали некоторые шорткоды.

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

[example shortcode]

Другими словами: шорткоды вызывают что-то особенное, где бы они ни находились в вашем тексте.
Но вы не ограничены предопределенными шорткодами; вы можете определить собственные шорткоды, чтобы делать все, что хотите! Они могут быть простыми, сложными или чем-то средним.

В этой серии мы начнем с простого шорткода и перейдем к более сложным (и даже более полезным!) примерам.

Примечание: здесь мы будем работать в основном с PHP, особенно в файле functions.php вашей темы. Если вы не используете дочернюю тему (или пользовательскую/стартовую тему, которую можно редактировать, не опасаясь, что обновления перезапишут ваши изменения), вам нужно создать дочернюю тему перед запуском.

Также обратите внимание: вам не нужны знания PHP, чтобы прочитать этот пост, но знание хотя бы основ поможет. Используемый здесь код довольно прост, и мы постарались максимально упростить его копирование и настройку. Мы объясним каждую часть кода по мере продвижения, но если вы совершенно не знакомы с PHP темы WordPress, имейте в виду, что немного плохого кода в вашем файле functions.php может сломать сайт.

Полезный пример простого шорткода

Допустим, нам нужен шорткод, который вставляет в сообщение специальный раздел с информацией об авторе, например:

Вместо того, чтобы создавать и стилизовать поле, изображение и текст в визуальном редакторе WordPress, мы просто создадим шорткод для вывода всего этого с помощью простого фрагмента!

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

Шаг 1: Добавьте шорткод в файл functions.php вашей темы

Вы будете использовать функцию add_shortcode , чтобы дать своему шорткоду имя и сообщить WordPress, что он должен делать каждый раз, когда используется шорткод. Добавьте эту строку в файл functions.php вашей темы:

 [php]add_shortcode( 'author_bio', 'create_author_bio' );[/php]

На самом деле не имеет значения, где находится functions.php , но во избежание конфликтов мы рекомендуем поместить его в самый конец. (Однако, если файл заканчивается закрывающим тегом ?>, он должен идти непосредственно перед ним, а не после него.)

Прежде чем мы пойдем дальше, давайте немного разобьем эту строку, чтобы мы поняли, что на самом деле здесь происходит. Два фрагмента текста или «аргументы» внутри круглых скобок на самом деле не являются чем-то особенным; это просто имена. Давайте рассмотрим, что означает каждый из них:

1. Первый аргумент: в данном случае author_bio — сообщает WordPress фактическое имя вашего шорткода. Это будет текст, который пользователи могут ввести в скобках, чтобы использовать шорткод. Таким образом, с этим кодом, как написано, [author_bio] будет нашим шорткодом для запуска нашего поля с биографией автора.
   Этот текст может быть любым, но всегда лучше стараться быть уникальным. Таким образом, вы не рискуете, что ваше имя шорткода будет конфликтовать с чьим-то именем из другого установленного плагина или темы.
2. Второй аргумент: в данном случае create_author_bio — указывает WordPress на фактическую функцию PHP, которую он должен выполнять всякий раз, когда используется этот шорткод. Мы создадим эту функцию на следующем шаге; на данный момент мы просто сообщаем WordPress, как будет его называться. (Это имя также должно быть уникальным, чтобы избежать конфликтов.)

Так что, если это поможет, вы можете подумать о коде следующим образом:

 [php]add_shortcode( 'when_you_see_THIS_shortcode', 'do_THIS' );[/php]

Если вас интересуют более подробные сведения, ознакомьтесь с записью Кодекса add_shortcode .

Шаг 2: Создайте функцию для обработки шорткода

Теперь нам нужно создать функцию, которую мы только что назвали!

Поскольку на последнем шаге мы только что сообщили WordPress, что имя нашей функции — create_author_bio, наш код теперь должен выглядеть так, как только мы добавим новую функцию:

 [php]add_shortcode( 'author_bio', 'create_author_bio' ); function create_author_bio(){ //Code goes here! }[/php]

Вы можете заметить, что эта функция еще ничего не делает; все, что находится внутри него, является комментарием. Мы позаботимся об этом на следующем шаге. А пока мы просто хотим отметить, что здесь есть только две части: регистрация шорткода и функция, которая происходит всякий раз, когда он используется. WordPress PHP может выглядеть пугающе, но на самом деле это так просто!

Примечание: не имеет значения, идет ли функция create_author_bio после функции add_shortcode или перед ней. Порядок в данном случае не важен.

Шаг 3: Заставьте функцию что-то делать

Теперь осталось только заставить нашу функцию делать то, что мы хотим!

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

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

 [html]<aside class="author-bio-box"></span> <img src="https://upload.wikimedia.org/wikipedia/en/1/1f/Bilbo_Baggins_Tolkien_illustration.jpg"> <p>Bilbo Baggins is the author of <cite>The Hobbit</cite>, translator of various works from the elvish, and author of a number of poems and songs.</p> <p>He is the oldest Hobbit ever in Middle Earth, and spends his days in his Tol Eressea home across the sea.</p> </aside>[/html]

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

Теперь все, что нам нужно сделать, это заставить функцию нашего шорткода вернуть приведенный выше HTML!

Поскольку файл functions.php должен содержать только… ну, PHP-функции (а также для аккуратности), мы удалили разрывы строк и пробелы между теми HTML-элементами, которые мы только что рассмотрели, и спрятали их в строку (внутри одинарных кавычек). . Но функционально это все тот же фрагмент HTML, который мы только что видели выше, и вот как должен выглядеть наш окончательный код PHP:

 [html]add_shortcode( 'author_bio', 'create_author_bio' ); function create_author_bio(){ return '<aside class="author-bio-box"><img src="https://upload.wikimedia.org/wikipedia/en/1/1f/Bilbo_Baggins_Tolkien_illustration.jpg"><p>Bilbo Baggins is the author of <cite>The Hobbit</cite>, translator of various works from the elvish, and author of a number of poems and songs.</p><p>He is the oldest Hobbit ever in Middle Earth, and spends his days in his Tol Eressea home across the sea.</p></aside>'; }[/html]

Мы закончили с PHP! После того, как мы сохранили наш файл functions.php с приведенным выше окончательным кодом, любой автор может просто ввести [author_bio] на любой странице или в сообщении, и указанный выше HTML появится вместо шорткода!

Кроме того, действительно крутая вещь: если нам когда-нибудь понадобится обновить нашу биографию, нам не нужно будет редактировать каждое место, где она появляется! Вместо этого все, что нам нужно сделать, это отредактировать код в нашем файле functions.php , и он будет обновлен везде и сразу. Аккуратно, да?

Однако, чтобы извлечь из этого максимальную пользу, мы, вероятно, захотим добавить некоторые специальные стили в поле био.

Шаг 4: Добавьте немного CSS

Шорткод не хорош без стиля, так что давайте его добавим! Возможно, вам придется немного изменить некоторые значения, в зависимости от шрифтов вашего собственного сайта (на изображении выше — Fanwood Text) и от того, какие правила CSS уже действуют. Или вы просто хотите попробовать что-то другое!

Этот CSS можно скопировать в файл style.css вашей (дочерней) темы, или, если вы используете WordPress 4.7 или более позднюю версию (как и должно быть!), вы можете просто вставить этот CSS в поле «Дополнительный CSS» в разделе «Настройка». экран:

 [css].author-bio-box { background: #d4ead9; padding: 2em; overflow: auto; font-family: Fanwood Text; font-size: 1.2em; line-height: 1.4em; } .author-bio-box img { float: left; max-width: 128px; height: auto; margin: 0 1em 0 0; } .author-bio-box > p:first-of-type:first-letter { font-size: 3.1em; line-height: 1; float: left; margin-bottom: -.2em; } .author-bio-box > p:last-of-type { margin: 0; }[/css]

Теперь все должно выглядеть намного лучше. Но не стесняйтесь экспериментировать с CSS, чтобы создать собственную авторскую рамку и сделать так, чтобы она чувствовала себя как дома на вашем сайте!

Рекомендуется: сделать функцию «подключаемой».

Это не относится к шорткодам и не обязательно для работы кода, но это лучшая практика, и сейчас самое время упомянуть об этом.

Сначала немного о том, как работает PHP :

Помните, как мы сами назвали нашу функцию create_author_bio ? Что ж, в названии create_author_bio; мы могли бы также легко назвать нашу функцию как угодно (хотя будет лучше, если имя функции даст вам хотя бы небольшой намек на то, что она делает, поэтому мы выбрали create_author_bio ).

Но вот в чем дело: если две PHP-функции названы одинаково, результатом будет фатальная ошибка, которая не позволит загрузить сайт, так как PHP не будет знать, какая функция правильная. PHP не угадывает, поэтому просто останавливается.

И нам нужно беспокоиться не только о нашем коде; сайт WordPress может использовать код десятков или даже сотен разных разработчиков, в зависимости от установленных плагинов и тем. Если одно и то же имя функции используется дважды, все ломается!

Это плохо, и, очевидно, мы хотим убедиться, что этого никогда не произойдет.

Мы можем сделать это, сделав нашу функцию «подключаемой»; другими словами, сообщаем WordPress не создавать нашу функцию, если уже существует другая функция с таким же именем. Это элегантно просто; мы просто заключаем наш существующий код в этот простой условный оператор:

 [php]if( !function_exists( 'create_author_bio' ) ){ //Our existing PHP goes here! }[/php]

Это условное выражение if просто проверяет, что функция с именем create_author_bio еще не существует. Весь наш PHP-код, который мы использовали до сих пор, можно просто поместить внутрь этого оператора между фигурными скобками { } .

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

Заключение

Вот и все! Надеюсь, вам понравилось создавать собственный шорткод биографии автора! Если вы следовали инструкциям, все, что вам нужно сделать, это ввести [author_bio] в любом месте страницы или сообщения, и ваш код появится!

Этот шорткод можно легко адаптировать для вывода чего угодно на страницу. GIF, пользовательский блок HTML и/или JavaScript, изображение или видео… все, что вы хотите!

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

Хорошие новости: мы рассмотрели только основы шорткодов, а они способны на гораздо больше!