MetaLamp 4 task - Slider for jQuery

Четвертое задание - плагин для jQuery, в котором выполнен функционал «бегунка» (также называемого слайдером) - специальный контрол, который позволяет перетягиванием задавать какое-то числовое значение.

Демо страница

Содержание

Возможности
Развертывание
Подключение и использование
API
Архитектура
UML-диаграмма
Использованные инструменты

Возможности

Любое количество слайдеров на странице без конфликтов
Простое и удобное API для взаимодействия со слайдером
Два типа слайдера (одиночный и диапазон)
Поддержка отрицательных значений
Широкие возможности кастомизации
- задание размера шага
- выбор вертикального либо горизонтального вида
- возможность задать диапазон значений
- возможность вкл/откл прогресс бар
- возможность вкл/откл подписи шкалы значений
- возможность вкл/откл подписи над ползунками
Поддержка тач устройств
Поддержка управления с клавиатуры
Подстраивается под изменения ширины/высоты контейнера

Развертывание

Клонирование репозитория

  git clone https://github.com/fullstack-development/frontend-intership-slider.git

Установка зависимостей

npm install

Разработка	Тестирование	Покрытие тестами	Production сборка
`npm run dev`	`npm test`	`npm run test:coverage`	`npm run build`

Подключение и использование

Для работы плагина необходимо подключить `jQuery-3.x
Для подключения плагина на страницу необходимо взять из папки ./dist файлы:
- plugin.js
- plugin.css

Пример подключения на страницу:

<html>
  <head>
    ...
    <!--jQuery-->
    <script defer="defer" 
      src="https://code.jquery.com/jquery-3.6.0.min.js">
    </script>
    <!--Plugin JavaScript file-->
    <script defer="defer" src="plugin.js"></script>
    <!--Plugin styles file-->
    <link href="plugin.css" rel="stylesheet" />
  </head>
</html>

Инициализация с настройками по умолчанию:

  <!--HTML-->
  <body>
    ...
    <div id="root"></div>
  </body>

  // JavaScript
  $('#root').sliderPlugin();

С пользовательскими настройками:

  $('#root').sliderPlugin({
    min: 0,
    max: 100,
    step: 25,
    valueFrom: 50,
    valueTo: 75,
    orientation: 'horizontal',
    isRange: false,
    hasFill: true,
    hasLabels: true,
    hasTooltips: true,
    color: 'orange',
  })

Опции

Опции	Тип	По-умолчанию	Описание
`min`	number	`0`	минимальное значение шкалы
`max`	number	`100`	максимальное значение шкалы
`step`	number	`25`	шаг шкалы
`valueFrom`	number	`50`	значение одиночного ползунка / начальное знач. диапазона
`valueTo`	number	`75`	конечное значение диапазона
-----	-----	-----	-----
`orientation`	string	`'horizontal'`	ориентация слайдера (horizontal/vertical)
`isRange`	boolean	`false`	тип слайдера (одиночный/диапазон)
`hasFill`	boolean	`true`	заливка (от min до valueFrom либо от valueFrom до valueTo)
`hasLabels`	boolean	`true`	подписи шкалы значений
`hasTooltips`	boolean	`true`	отображение текущего значения над ползунком
`color`	string	`'orange'`	цвет слайдера (orange/green)

API

sliderPlugin( method: 'getState' | 'setValue' | 'onChange', options)

Плагин принимает в качестве параметров объект с опциями либо методы для изменения и получения данных.

getState(): IOptions - метод, который возвращает текущее состояние слайдера в виде объекта со всеми опциями.

  const state = $('#root').sliderPlugin('getState') 
  console.log(state) // {min: 0, max: 100, step: 25, valueFrom: 50, valueTo: 75, …}

setValue( name: string, value: number | string | boolean ): void - метод для изменения любого значения слайдера. Принимает название параметра (string) и значение (string, number, boolean)

  $('#root').sliderPlugin('setValue', 'min', -100) 
  $('#root').sliderPlugin('setValue', 'valueFrom', 20) 
  $('#root').sliderPlugin('setValue', 'orientation', 'vertical') 
  $('#root').sliderPlugin('setValue', 'isRange', true) 
  $('#root').sliderPlugin('setValue', 'hasTooltips', false) 
  $('#root').sliderPlugin('setValue', 'hasLabels', false)

Кастомное событие

onChange( func: EventCallback ): void - метод который позволяет передать callback функцию на событие изменения слайдера.

  $('#root').sliderPlugin('onChange', () => {
    `any code`
  })

Также позволяет через объект detail получить любые значение слайдера.

  $('#root').sliderPlugin('onChange', (evt) => console.log(evt.detail))

Архитектура

Плагин построен по MVP-архитектуре с Passive View. Такой подход позволяет отделить бизнес-логику от отображения. Отвязка слоев приложения осуществляется благодаря использованию паттерна Observer, который расширяет основные модули и позволяет им взаимодействовать ничего не зная друг о друге.

Model

Model является модулем отвечающим за хранение всего состояния приложения и валидацию данных (расчеты, которые относятся к бизнес-логике). Предоставляет методы для чтения и записи (всех параметров либо каждого по отдельности), а также методы для обработки значений слайдера полученных в процентах и методы увеличения/уменьшения значения ползунка на величину шага.

View

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

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

Для инициализации либо пересоздания графической части существует Slider - это класс-фабрика, который в соответствие с переданными опциями создает все элементы слайдера и формирует объект с созданными компонентами, после чего View может легко взаимодействовать с subView. Это позволяет локализовать и изолировать в одном месте создание всех графических компонентов.

Связь между View и subView осуществляется также с помощью паттерна Observer, что позволяет уменьшить сложность графической части, обеспечить простое взаимодействие, слабую связность и модульность элементов.

Помимо прослушивания событий subView в классе View также реализованы некоторые фичи слайдера:

метод checkKnobZIndex() меняет свойство z-index у ползунков в зависимости от того, какой из-них задействован в данный момент;
метод createDoubleTooltip() отвечает за то, чтобы у двойного слайдера ползунки объединялись в один общий;
также во View реализована возможность перехвата target со шкалы, чтобы после нажатия на любое место шкалы можно было сразу передвигать ползунок.

Presenter

Presenter - единственный модуль, который имеет зависимости от других слоев приложения.

Presenter создает модель и отображение
Подписывается на изменения модели и отображения
Реагирует на сообщения об обновлении модели и обновляет отображение
Реагирует на сообщения от отображения о действиях пользователей и обновляет модель
Формирует кастомное событие, для того, чтобы была возможность получать актуальные данные либо осуществлять стороннюю логику при перемещении слайдера.

Таким образом передача данных снизу вверх осуществляется следующим образом subVeiw ->View -> Presenter -> Model

UML диаграмма классов

открыть превью диаграммы в draw.io для удобного просмотра

fullstack-development / fronted-intership-slider