README.ru.md

jQuery Factory

In English

Простая, пегковесная, цельная фабрика для генерации jQuery плагинов. Позволяет писать плагины в классическом JavaScript стиле вместо предлагаемого jQuery.

Возможности

• Поддержка всех современных браузеров (включая мобильные браузеры)
• Поддержка Internet Explorer 7-8 (необходима jQuery 1.8 или старше)
• Поддержка jQuery начиная с версии 1.6
• Поддержка Zepto (нужен модуль data)
• Около 600 байт в сжатом виде
• Эффективное реиспользование кода при написании нескольких плагинов
• Поддкржка requirejs/webpack и amd
• Режим тестирования

Установка

Bower

bower install --save jquery-factory

Npm

npm install --save jquery-factory

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

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

var $ = require('jquery')(window),
    newPlugin = require('jquery-factory')($);

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

<script src="https://code.jquery.com/jquery-2.2.4.min.js"></script>
<script src="/path/to/newPlugin.jquery.js"></script>

Создание плагина $.newPlugin(pluginName, Constr, options)

Создает новый jQuery плагин в $.fn-объекте с функцией-конструктором Constr. Фабрика принимает название плагина в виде строки pluginName. Если плагин с таким именем существует, будет брошена ошибка.

После создания, объект $.fn.pluginName содержит свойство __constr__ с конструктором Constr для возможности проверки принадлежности плагина:

$('.element').data(pluginName) instanceof $.fn.pluginName.__constr__

Конструктор

Constr принимает в качестве параметров $element, callback и htmlData.

$element содержит текущий jQuery-элемент

callback колбэк по окончанию инициализации (не рекомендуется)

htmlData содержит значение html-атрибута data-<pluginname>, если он был (например <span data-plugin="myText"></span>).

Методы

По-умолчанию, каждый вновь созданный плагин содержит методы init, update и destroy, которые могут быть переопределены.

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

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

destroy метод для удаления экземпляра плагина. Используется метод .removeData.

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

Экземпляры плагина

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

Включение тестов возможно путем помещения их в аргумент callback. callback примет контекст экземпляра. Он должен вернуть true для сохранения экземпляра в элемент или false для удаления.

Примеры

Пустой плагин

Плагин, который ничего не делает:

(function($) {
  var Plugin = function() {}
  $.newPlugin('plugin', Plugin);
})(jQuery);

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

$('.element-set').plugin();

Элемент и параметры инициализации

Плагин принимает параметры инициализации и присоединяемый элемент. Класс opt добавляется, когда присоединяется plugin.

(function($) {
  var Plugin = function($el, opt) {
    this.$el = $el;
    this.opt = opt;
    
    this.$el.addClass(opt);
  }
  $.newPlugin('plugin', Plugin);
})(jQuery);

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

$('.element-set').plugin('some-class');

init, update, destroy методы и события

(function($) {
  var clickHandler = function(e) {
    var self = e.data;
    e.preventDefault();
    // делаем что-либо
  }
  
  var Plugin = function($el, opt) {
    this.$el = $el;
    this.opt = $.extend({
      text : ''
    }, opt);
    
    this.init();
  }
  
  // обработчик инициализации
  Plugin.prototype.init = function() {
    this.$el
      .on('click', this, clickHandler)
      .text(this.opt.text);
  }
  
  // updating text option
  Plugin.prototype.update = function(opt) {
    $.extend(this.opt, opt);
    this.$el.text(this.opt.text);
  }
  
  // метод для удаления
  Plugin.prototype.destroy = function() {
    this.$el
      .off('click', clickHandler)
      .removeData('plugin');
  }
  
  // произвольный метод
  Plugin.prototype.smartMove = function() {
    this.$el
      .toggleClass('smart-class');
  }
  
  $.newPlugin('plugin', Plugin);
})(jQuery);

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

// создание
$('.element-set').plugin({
  text : 'This is new instance of "plugin"'
});

// обновление
$('.element-set').plugin('update', {
  text : 'blah!'
});

// обновление (другой способ)
$('.element-set').plugin({
  text : 'Blah-blah!'
});

// вызов произвольного метода
$('.element-set').plugin('smartMove');

// удаление плагина
$('.element-set').plugin('destroy');

Больше примеров доступно в tests

В планах

• Создавать экземпляры плагина с помощью Object.create (будет потеряна совместимость со старыми браузерами)
• Больше тестов
• Больше примеров
• Адаптация (возможно форк?) для БЭМ процесса разработки
• Тесты совместимости с Zepto

Помощь проекту

Сделайте свой вклад в улучшение проекта :)

Автор

• Kir Peremenov

Благодарности

• asg-3d
• KlonD90