Привет! Решил поделиться, как выглядит разработка плагина WordPress. В этой статье я покажу, как создать простой плагин, который будет отображать прогресс скролла страницы с помощью цветной горизонтальной полоски. Полагаю, вы такое встречали на многих сайтах. Здесь, например. 😉

После того, как все будет работать безопасно и надежно, я размещу этот плагин в репозитории WordPress. Но об этом уже в следующей статье. Здесь же погрузимся в разработку плагина.

Скачать BS Scroll Progress v 1.0

WordPress Plugin Boilerplate

В качестве основы для плагина я буду использовать WordPress Plugin Boilerplate. Она имеет логично организованную архитектуру в объектно-ориентированном стиле и облегчает процесс разработки. Интернационализация, версии подключаемых скриптов согласно версии плагина, активация, деактивация и удаление плагина. Для всего уже созданы соответствующие классы. Есть даже шаблон README.txt, который пригодится при публикации плагина в репозитории wordpress.org. В общем, рекомендую.

Очень часто разработка плагина WordPress у меня начинается именно с WordPress Plugin Boilerplate.

При создании нового плагина я обычно использую генератор, который подготавливает файлы WordPress Plugin Boilerplate с нужными мне именами, названиями, слагами и т.д. Кастомизирует, одним словом. Вот пример такого генератора.

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

/* * @link https://neuropassenger.ru * @since 1.0.0 * @package Bs_Scroll_Progress * * @wordpress-plugin * Plugin Name: BS Scroll Progress * Description: This plugin adds a small colored scroll bar to the top of site pages. * Version: 1.0.0 * Author: Oleg Sokolov * Author URI: https://neuropassenger.ru * License: GPL-2.0+ * License URI: http://www.gnu.org/licenses/gpl-2.0.txt * Text Domain: bs-scroll-progress * Domain Path: /languages */
Code language: PHP (php)

Мой плагин получил слаг bs-scroll-progress. Он используется везде в названиях файлов и директории плагина. Так что в примерах подставляйте то, что есть вместо моего слага фактически у вас.

Создание полоски скролла страницы

Наша разработка плагина WordPress начинается с HTML элемента, который будет отвечать за отображение полоски скролла. Для этого найдем файл класса class-bs-scroll-progress-public.php. Класс Bs_Scroll_Progrss_Public отвечает за все, что наш плагин будет делать во фронтенде. Добавим в него метод для вывода полоски.

HTML

public function show_progress_bar() { include plugin_dir_path( dirname( __FILE__ ) ) . 'public/partials/bs-scroll-progress-public-display.php'; }
Code language: PHP (php)

Здесь я просто подключаю файл, в котором содержится сам HTML элемент для отображения прогресса скроллинга.

<div id="bs_progress-bar"></div>
Code language: HTML, XML (xml)

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

Чтобы все заработало, нужно прицепить метод show_progress_bar к хуку wp_footer. Делаем это в файле class-bs-scroll-progress.php в методе define_public_hooks.

$this->loader->add_action( 'wp_footer', $plugin_public, 'show_progress_bar' );
Code language: PHP (php)

CSS

Теперь немного CSS, чтобы все начало постепенно оживать. Фиксируем позиционирование, чтобы полоска оставалась при скролле, и прижимаем к самому верху страницы. Добавим этот код в публичные стили сайта в файл bs-scroll-progress-public.css.

#bs_progress-bar { position: fixed; top: 0px; width: 0; z-index: 999999; background-color: #73af3d; height: 5px; }
Code language: CSS (css)

Идея проста. Изначально устанавливаем CSS свойство width в 0, с помощью JavaScript высчитываем процент скролла на странице и подставляем это значение в width.

JavaScript

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

Добавим в bs-scroll-progress-public.js следующий код для обновления CSS свойства width.

$( window ).scroll(function() { const windowOffset = $(this).scrollTop(); const articleOffset = $('body').scrollTop(); const articleHeight = $('body').height(); const scrollPercent = ((windowOffset - articleOffset) * 100) / articleHeight; $('#bs_progress-bar').css('width', scrollPercent + '%'); } );
Code language: JavaScript (javascript)

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

Окей, сделаем.

Создание страницы настроек плагина и добавление полей с настройками

Т.к. все это касается админки, будем писать код в файле class-bs-scroll-progress-admin.php.

Прежде всего, нужно добавить нашу страницу настроек в меню WordPress Dashboard.

public function add_plugin_settings_page() { add_options_page( 'Scroll Progress', 'Scroll Progress', 'manage_options', 'bs_scroll_progress', array( $this, 'show_plugin_settings_page' ) ); }
Code language: PHP (php)

Этот метод добавляет для всех администраторов новый пункт меню Scroll Progress в раздел Settings.

Подключим его к хуку admin_menu в файле class-bs-scroll-progress.php в методе define_admin_hooks.

$this->loader->add_action( 'admin_menu', $plugin_admin, 'add_plugin_settings_page' );
Code language: PHP (php)

Разработка плагина WordPress может занимать много времени, но мы его сэкономим и воспользуемся WordPress Settings API для создания полей и секций наших настроек. API возьмет на себя обработку полей, их вывод и санацию (sanitizing).

Создадим метод add_plugin_settings в классе Bs_Scroll_Progress_Admin. Зарегистрируем настройки, добавим секцию и поля настроек.

public function add_plugin_settings() { register_setting( 'bs_sp_general', 'bs_sp_selector' ); register_setting( 'bs_sp_general', 'bs_sp_color' ); register_setting( 'bs_sp_general', 'bs_sp_width' ); add_settings_section( 'bs_sp_general', 'General Settings', array( $this, 'show_general_settings_section' ), 'bs_scroll_progress' ); add_settings_field( 'bs_sp_selector', 'CSS tag selector with main content', array( $this, 'show_bs_sp_selector_field' ), 'bs_scroll_progress', 'bs_sp_general' ); add_settings_field( 'bs_sp_color', 'Hex color of the Progress Bar', array( $this, 'show_bs_sp_color_field' ), 'bs_scroll_progress', 'bs_sp_general' ); add_settings_field( 'bs_sp_width', 'Width in px of the Progress Bar', array( $this, 'show_bs_sp_width_field' ), 'bs_scroll_progress', 'bs_sp_general' ); }
Code language: PHP (php)

Прицепим регистрацию настроек к хуку admin_init.

$this->loader->add_action( 'admin_init', $plugin_admin, 'add_plugin_settings' );
Code language: PHP (php)

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

function show_bs_sp_selector_field() { $selector = get_option( 'bs_sp_selector' ); echo "<input type='text' class='regular-text' name='bs_sp_selector' value='" . ($selector ?? 'body') . "'>"; } function show_bs_sp_color_field() { $color = get_option( 'bs_sp_color' ); echo "<input type='color' class='regular-text' name='bs_sp_color' value='" . ($color ?? '#73af3d') . "'>"; } function show_bs_sp_width_field() { $width = get_option( 'bs_sp_width' ); echo "<input type='number' min='1' max='10' step='1' class='regular-text' name='bs_sp_width' value='" . ($width ?? '1') . "'>"; }
Code language: PHP (php)

После этого можно заняться выводом страницы настроек. Обратите внимание, что ранее в методе add_plugin_settings_page мы указали метод show_plugin_settings_page для этого. Значит его и добавим в класс Bs_Scroll_Progress_Admin.

function show_plugin_settings_page() { ?> <h1 class="wp-heading-inline"> <?php echo get_admin_page_title() ?> </h1> <form method="post" action="options.php"> <?php settings_fields( 'bs_sp_general' ); do_settings_sections( 'bs_scroll_progress' ); submit_button(); ?> </form> <? }
Code language: HTML, XML (xml)

Здесь мы сначала выводим заголовок страницы (строка 4). Затем создаем форму, добавляем в нее скрытые поля с помощью settings_fields для безопасности и работы Settings API (строка 8). Выводим, наконец, сами поля с настройками при помощи do_settings_sections (строка 9). И добавляем кнопку отправки формы, используя функцию submit_button.

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

function show_general_settings_section() { // Block before fields }
Code language: JavaScript (javascript)

Метод пустой, но добавить в файл class-bs-scroll-progress-admin.php нужно, так как мы указывали его при регистрации секции с настройками.

Использование настроек плагина

Мы хотим, чтобы толщину и цвет полоски устанавливали настройки плагина. Для этого удалим выделенные строки 6 и 7 из нашего CSS файла bs-scroll-progress-public.css.

#bs_progress-bar { position: fixed; top: 0px; width: 0; z-index: 999999; background-color: #73af3d; height: 5px; }
Code language: CSS (css)

Затем найдем в классе Bs_Scroll_Progress_Public (class-bs-scroll-progress-public.php) метод enqueue_styles и добавим в него кое-что интересное.

public function enqueue_styles() { wp_enqueue_style( $this->plugin_name, plugin_dir_url( __FILE__ ) . 'css/bs-scroll-progress-public.css', array(), $this->version, 'all' ); $selector = get_option( 'bs_sp_selector' ); $color = get_option( 'bs_sp_color' ); $width = get_option( 'bs_sp_width' ); if ( $selector && $color && $width ) { $css = "#bs_progress-bar {background-color: {$color}; height: {$width}px;}"; wp_add_inline_style( $this->plugin_name, $css ); } }
Code language: PHP (php)

Здесь мы проверяем настройки плагина. Если они установлены, то добавляем inline CSS на нашу страницу с необходимыми параметрами цвета и толщины полоски.

После этого улучшим метод enqueue_scripts. Нам нужно сохранить в JavaScript переменной bsSPSelector селектор элемента, который содержит основной контент.

public function enqueue_scripts() { wp_enqueue_script( $this->plugin_name, plugin_dir_url( __FILE__ ) . 'js/bs-scroll-progress-public.js', array( 'jquery' ), $this->version, false ); $selector = get_option( 'bs_sp_selector' ); if ( $selector ) { $script = "const bsSPSelector = '{$selector}';"; wp_add_inline_script( $this->plugin_name, $script, 'before' ); } }
Code language: PHP (php)

Если селектор установлен, то добавляем переменную с его значением перед публичными скриптами плагина. Да, да, функция wp_add_inline_script изумительна.

Удаление плагина

Последнее, о чем нужно позаботиться при разработке плагина WordPress — действия при удалении плагина. Нам нужно очистить в базе данных записи с нашими настройками. Добавим в файл uninstall.php в корне плагина код для очистки.

// If uninstall not called from WordPress, then exit. if ( ! defined( 'WP_UNINSTALL_PLUGIN' ) ) { exit; } delete_option( 'bs_sp_selector' ); delete_option( 'bs_sp_color' ); delete_option( 'bs_sp_width' );
Code language: PHP (php)

Готово! Наша разработка плагина WordPress для отображения прогресса скроллинга закончена. Можете теперь активировать плагин. Если сделали все правильно, то после настройки полоска скролла появится у вас на сайте.

У нас получился простой плагин, который никак не замедляет сайт, принимает настройки пользователя и выводит в соответствии с ними Progress Bar вверху страницы.

Исходный код плагина вы можете скачать одним архивом по этой ссылке.

Дальнейшие планы — публикация на wordpress.org.

Разработка плагина WordPress и публикация на wordpress.org

Я уже отправил плагин на проверку и жду ответа. Подробнее об этом в следующей статье. 😉