Разработка плагина WordPress для отображения полоски скролла страницы

Привет! Решил поделиться, как выглядит разработка плагина 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.

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