Настраиваемый плагин для jQuery, который реализует функционал слайдера.

Добро пожаловать! Это руководство может Вам ознакомиться с проектом, а также разобраться с запуском и правильным использованием плагина.

Что из себя представляет данный плагин?

Custom Slider - плагин, написанный на TypeScript, с использованием сборщика проектов webpack. В качестве архитектуры выбран MVP-подход, c разделением приложения на слои. Плагин работает совместно с библиотекой jQuery, расширяя возможности ее использования.

Оглавление

• Что из себя представляет данный плагин?
• Оглавление
• Демо
• Приступая к работе
  • Требуемые зависимости
  • Установка
  • Использование
  • Конфигурация
  • Методы
    • Список методов
  • События
    • Список событий
• Архитектура плагина
• UML диаграмма
• Тесты
• Автор
• Лицензия

Демо

См. Демонстрацию на странице проекта.

Приступая к работе

Требуемые зависимости

Перед использованием плагина, необходимо включить jQuery в исполняемом файле вашего проекта.

import $ from 'jquery'

Установка

Для установки зависимостей вам потребуется:

• Установить NodeJS
• Используя NPM выполнить npm install jquery
• Затем выполнить установку самого плагина npm install ...

Использование

• Импортируйте плагин import 'customslider'.
• Создайте div элемент на странице, который будет использован плагином для мутации.
• Примените плагин jQuery customslider с конфигурацией следующим образом:

$('#slider').sliderPlugin({
  step: '500',
  mode: 'Multiple',
  orientation: 'Gorizontal',
  defaultInterval: ['5000', '10000'],
  maximumValue: '15000',
  showSettings: false,
  showValue: false
});

Конфигурация

Объект конфигурации может содержать следующие параметры (значения по умолчанию указаны ниже):

{
  showSettings: boolean,  
  showValue: boolean,
  defaultValue: string,
  defaultInterval: [string, string],
  minimumValue: string,
  maximumValue: string,
  step: string,
  orientation: 'Vertical' | 'Gorizontal',
  mode: 'Single' | 'Multiple',
  onValueChanged: Function | undefined;
  measurement: string
} 

• showSettings - это логическое свойство, определяющее, отображать или скрывать панель конфигурации слайдера.
• showValue - это логическое свойство, определяющее, отображать или скрывать значение над ползунком слайдера.
• defaultValue - это строка, которая задает значение слайдера по-умолчанию.
• defaultInterval - это кортеж, содержащий строки, значение которых определяет установленные показатели слайдера в множественном режиме по-умолчанию.
• minimumValue - это строка, которая определяет минимально возможное значение слайдера.
• maximumValue - это строка, которая определяет максимально возможное значение слайдера.
• step - это строка, которая определяет значение шага (минимального изменения) слайдера в большую или меньшую сторону.
• orientation - это строковый ключ, который задает ориентированность слайдера (вертикально или горизонтально).
• mode - это строковый ключ, который задает режим работы слайдера (с одним или несколькими значениями).
• measurement - это строка, которая будет отображаться как единица измерения значения слайдера.
• onValueChanged - это функция, которая является обработчиком события, на изменение значения слайдера.

Все параметры не являются обязательными.

Методы

Методы обеспечивают способ программного взаимодействия с плагином. Методы плагина можно вызвать следующим образом:

$('#slider').sliderPlugin('init', { mode: 'Multiple' });  

Плагин работает как прокси для доступа к методам.

Список методов

Ниже приводится список всех доступных методов.

init(options)

Инициализирует плагин с параметрами в качестве объекта конфигурации. Не отличается от обычного использования плагина.

destroy()

Удаляет компонент представления плагина. Удаление событий, внутренних объектов и добавленных HTML-элементов.

$('#slider').sliderPlugin('destroy');  

update(options)

Метод обновления модели плагина, c последующим изменением вида плагина.

$('#slider').sliderPlugin('update', { defaultValue: '20' });  

value()

Геттер на получение текущего значения плагина.

$('#slider').sliderPlugin('value')  

События

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

Список событий

valueChanged (event, value) - изменено состояние слайдера.

$('#slider').sliderPlugin({
  onValueChanged: function (_, change) {
    // Здесь ваша логика
  }
});  

Архитектура плагина

Как уже было указано ранее, плагин реализует Model-View-Presenter паттерн проектирования. Приложение разделено на 3 независимых слоя.

• Модель - содержит данные слайдера. Имеет сеттер на изменение данных из вне.
• Представление - это слой, который отвечает за визуальное отображение данных. Данный паттерн не предусматривает знание представления о модели.
• Презентер - организует взаимодействие между представлением и моделью.

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

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

Таким же образом, если программно изменить данные модели, презентер узнает об этом и получит данные, которые передаст в представление для изменения отображения.

Ниже расмотрим более детально, как происходят взаимодействия.

При инициализации в конструкторе презентера инициализируется представление view = new View(object, this.model.getDataModel().options), в качестве аргументов переданы объект, где будет размещено отображение, а вторым данные модели. К созданному объекту вида, устанавливаем обработчик изменения модели view.initHandleChangeModel(this.handleChangeModel). Также подписываемся на изменение модели unsub.push(this.model.subscribe(this.handleUpdateView)). Метод subscribe() возвращает объект, внутри которого есть функция для отписки от наблюдения за моделью. Объект сохраняется в свойстве класса в массиве. По действию пользователя вызывается обработчик изменения модели changeModalHandler(option, value) с нужным типом. Презентер обращается в модель для обновления this.model.updateData(option, value, 'view'). Презентер подписан на обновление модели, cрабатывает обработчик обновления вида observer(this.options, prevOptions) - что соответствует вызову handleUpdateView() в презентере. Тем самым перерисовывая представление view.updateView(data, oldData).

UML диаграмма

Тесты

После клонирования репозитория, необходимо установить все зависимости из package.json, выполнив команду npm install. После чего выполнить команду для запуска тестов npm run test.

Автор

• Victor Kiselev

Лицензия

Этот проект лицензируется в соответствии с лицензией MIT — подробности см. в файле LICENSE