Раскройте всю мощь API WordPress Shortcode

 Array ( [name] => Here is my name [n] => 5 ) 

в первом параметре нашей функции.

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

 function replace_my_shortcode($atts, $content = '') { $atts = shortcode_atts(array( 'name' => 'World', 'n' => 1 ), $atts); return 'Hello ' . $atts['name'] . '!'; } 

Эта функция объединит массив $atts предоставленный пользователем, и массив, указанный в первом параметре, который содержит значения по умолчанию. В приведенном выше примере, если пользователь не заполняет атрибут name , мы отображаем «Hello World!» . В противном случае будет использовано указанное имя.

Атрибуты без имени

Иногда неназванный атрибут может быть лучшим решением, чем традиционный. Например, чтобы [myimage id="7"] изображения: [myimage 7] вместо [myimage id="7"] . Проблема возникает, когда мы пытаемся получить эти специальные атрибуты. Без имени для поиска, какой ключ мы должны выбрать?

Что касается других, безымянные атрибуты могут быть найдены в первом параметре нашей функции обратного вызова с пронумерованными ключами. Пример будет понятнее длинного объяснения, поэтому предположим, что пользователь дает нам [myshortcode 7 name="My name"] . Затем мы находим следующий массив в первом параметре нашей функции обратного вызова.

 Array Array ( [0] => 7 [name] => My name ) 

Если существует более одного безымянного атрибута, единственный способ отличить их друг от друга — это их порядок. Например, у нас есть следующий массив, если пользователь вставляет [myshortcode 7 name="My name" display test="value" 22] .

 Array ( [0] => 7 [name] => My name [1] => display [test] => value [2] => 22 ) 

Часто именованные атрибуты предпочтительнее, потому что их легче получить. Тем не менее, безымянные атрибуты не являются большой проблемой, если вы ограничиваете их небольшим числом или если они служат только логическими значениями. На самом деле, такой [myshortcode name="Me" show] как [myshortcode name="Me" show] , безусловно, лучше для пользователя печатать, чем [myshortcode name="Me" show="true"] .

Для логических значений безымянные атрибуты — хорошая идея: мы устанавливаем их как true если они присутствуют, и как false противном случае. Однако здесь остается вопрос: как насчет значений по умолчанию?

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

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

 function normalize_attributes($atts) { foreach ($atts as $key => $value) { if (is_int($key)) { $atts[$value] = true; unset($atts[$key]); } } return $atts; } не function normalize_attributes($atts) { foreach ($atts as $key => $value) { if (is_int($key)) { $atts[$value] = true; unset($atts[$key]); } } return $atts; } 

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

 function replace_my_shortcode($atts, $content = '') { $atts = normalize_attributes($atts); $atts = shortcode_atts(array( 'name' => 'World', 'hide' => false ), $atts); if (!$atts['hide']) return 'Hello ' . $atts['name'] . '!'; else return ''; } 

В этом примере, если пользователь вставляет [myshortcode name="You"] , мы отображаем «Hello You!» . Однако, если [myshortcode hide] , то мы ничего не отображаем. Абсурд, но вы поняли идею!

В заключение

Shortcode API — это мощный инструмент для разработчиков.

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

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

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

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