Разработка плагина 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.

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