Как написать плагин jQuery. Создание JQuery плагина

", { text: $this.attr("title") }); // Если плагин еще не был инициализирован if (! data) { /* Здесь делаем еще какие-то вещи */ $(this).data("tooltip", { target: $this, tooltip: tooltip }); } }); }, destroy: function() { return this.each(function(){ var $this = $(this), data = $this.data("tooltip"); // Используем пространства имён FTW $(window).unbind(".tooltip"); data.tooltip.remove(); $this.removeData("tooltip"); }) }, reposition: function() { // ... }, show: function() { // ... }, hide: function() { // ... }, update: function(content) { // ... } }; $.fn.tooltip = function(method) { if (methods) { return methods.apply(this, Array.prototype.slice.call(arguments, 1)); } else if (typeof method === "object" || ! method) { return methods.init.apply(this, arguments); } else { $.error("Метод " + method + " не существует в jQuery.tooltip"); } }; })(jQuery);

Использование data помогает вам следить за переменными и состояниями между вызовами методов плагина. Хранение всех данных в одном объекте позволяет легко к ним обращаться, и, в случае необходимости, так же легко их удалять.

Написание jQuery-плагинов позволяет наиболее эффективно использовать возможности библиотеки. А повторное использование кода экономит ваше время и делает разработку более эффективной. Вот краткие итоги поста, держите их в уме, когда будите писать свой следующий плагин:

• Всегда оборачивайте свой плагин в функцию (function($){ // здесь сам плагин })(jQuery); .
• Не оборачивайте this в непосредственном scope плагина.
• Если ваш плагин не должен возвращать важных значений, то всегда возвращайте this , чтобы работали цепочки вызовов.
• Не запрашивайте большое количество аргументов при вызове плагина, лучше передавать объект, который переопределит настройки по умолчанию.
• Не добавляйте в объект jQuery.fn более чем одно пространство имён на плагин.
• Используйте пространства имён для ваших методов, событий и данных.
• jQuery.fn читается как "джейКуэри эффин".

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

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

Все требования к верстке описаны в вышеуказанном уроке, поэтому на них останавливаться не будем. Назовем наш будущий плагин «mySimpleSlider».

Плагин представляет собой новый метод в объекте jquery, следственно, для создания плагина, необходимо добавить функцию с его реализацией в объект jQuery.fn, как это показано ниже.

(function($){ jQuery.fn.mySimpleSlider = function(options){ // Здесь будет реализация метода }; })(jQuery);

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

Options = $.extend({ nextBtn:null, // Селектор кнопки "следующий" prevBtn:null, // Селектор кнопки "предыдущий" playBtn:null, // Селектор кнопки play/pause selectors:null, // Селектор "переключателей" slideWidth:100, // Шаг прокрутки (px) delay:null, // Интервал между авто пролистыванием duration:500 // Скорость переключения слайдов }, options);

После этого внутри плагина мы можем обратиться к свойствам, используя запись вида options.имя_свойства . Теперь можем приступить к написанию функций необходимых для работы плагина, но прежде зададим глобальные, по отношению к плагину, переменные:

Var slider = this; // Объект, к которому применен плагин var intervalID; // Указатель таймера

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

// Функция «включения» function start(){ // Вызов функции next при нажатии на nextBtn $(options.nextBtn).on("click", next); // Вызов функции prev при нажатии на prevBtn $(options.prevBtn).on("click", prev); Запуск таймера для авто пролистывания setTimer(); /* Перелистывание на выбранный слайд при условии существования переключателей */ if(options.selectors) { $(options.selectors).on("click", function(){ selectSlide($(this).index()) }); } } // Функция «выключения» function finish(){ // Отключение вызова функций всех событий $(options.nextBtn).unbind(); $(options.prevBtn).unbind(); $(options.selectors).unbind(); // Остановка таймера авто переключения clearInterval(intervalID); }

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

Function setTimer(){ // Если задержка не задана - не запускаем таймер if(!options.delay) return false; /* Если задана кнопка play/pause И она в состоянии "pause" - не запускаем таймер */ if(options.playBtn) if($(options.playBtn).hasClass("pause")) return false; // Запуск таймера intervalID = setInterval(next, options.delay); }

Function next(){ /* Если текущий слайд - последний, то возвращаемся к первому */ if(getIndex() == (getCount()-1)) { selectSlide(0); } // Иначе идет перелистывание на следующий слайд else { selectSlide(getIndex()+1); } } function prev(){ /* Если текущий слайд - первый, то переходим к последнему */ if(getIndex() == 0) { selectSlide(getCount()-1); } // Иначе происходит переход на предыдущий слайд else { selectSlide(getIndex()-1); } }

В приведенных выше функциях используются еще три пользовательские функции, которые описаны ниже.

// Функция переключения на слайд //с выбранным индексом function selectSlide(index){ // Отключение срабатывания событий finish(); // Переключение на слайд $(slider).children("ul").animate({left:options.slideWidth *-1*index+"px"}, options.duration, start); // Отображение выбранного слайда в «статус баре» $(options.selectors).removeClass("active"); $(options.selectors).eq(index).addClass("active"); } // Функция, которая возвращает индекс текущего слайда function getIndex(){ return ($(slider).children("ul") .position().left / options.slideWidth)*(-1); } // Функция подсчета количества слайдов function getCount(){ return $(slider).children("ul") .children("li").length; }

Завершает наш плагин функция make , которая и запускается при вызове плагина. Она будет содержать функцию включения события, а так же код запускающий работу кнопки play/pause если такая имеется. Этот код не занесен в функцию start так как используется только один раз, при запуске плагина. Кнопка имеет два состояния: play и pause , которые контролируются через классы с соответствующими названиями. Функция make имеет следующий вид:

Var make = function(){ // Если задана кнопка play/pause if(options.playBtn) { /* При нажатии на кнопку меняем ее состояние на обратное текущему и запускаем либо останавливаем таймер в зависимости от состояния кнопки */ $(options.playBtn).on("click", function(){ if($(this).hasClass("pause")) { $(this).removeClass("pause"); $(this).addClass("play"); setTimer(); } else { clearInterval(intervalID); $(this).removeClass("play"); $(this).addClass("pause"); } }); } // Включение реакции на события // управляющих элементов start(); };

По завершению работы плагин возвращает функцию make :

Return this.each(make);

На этом наш урок по созданию собственных плагинов окончен. Удачной реализации собственных идей и до свидания!

Итак, вы стали комфортно работать с jQuery и хотели бы знать, как написать свой собственный плагин. Замечательно! Вы там, где нужно. Расширение функционала jQuery по средствам плагинов и методов является очень мощной штукой и может спасти много часов разработки Вам и Вашим коллегам, заключая Ваши самые часто употребляемые функции в плагины. Этот пост, обрисует в общих чертах, основы, лучшие методы, и распространенные ошибки, которые надо учитывать при написании Вашего плагина.

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

Начнем писать JQuery плагин, с добавления нового метода к объекту jQuery.fn, где имя метода - это название Вашего плагина:

JQuery.fn.myPlugin = function() { // здесь помещаете код Вашего плагина };

Но постойте! Где же мой знак доллара, который я знаю и люблю?- спросите Вы. Он по прежнему доступен, однако надо убедиться, что Ваш плагин не будет конфликтовать с другими библиотеками, которые также могут использовать знак доллара(Mootools, Prototype). Для этого код Вашего плагина нужно поместить в само вызывающееся замыкание.

(function($){ $.fn.myPlugin = function() { // здесь код Вашего плагина }; })(jQuery);

Так-то лучше. После этого, другие библиотеки сколько угодно могут изменять знак $, на Вас это не отразится. Внутри замыкания, $ будет равен jQuery.

Контекст

Теперь у нас есть оболочка, и мы можем начать писать фактический код плагина. Но прежде, чем мы это сделаем, я хотел бы сказать несколько слов о контексте. Внутри плагина зарезервированное слово this это ссылка на объект jQuery. Но когда, в коде плагина используются callback функции, то там this - это ссылка на нативный DOM элемент. Ошибки возникают тогда, когда разработчики лишний раз делают $(this) или наоборот забывают это делать

(function($){ $.fn.myPlugin = function() { // тут не нужно делать так $(this) потому-что // "this" уже является объектом jquery // $(this) будет обозначать то же самое, что $($("#element")); this.fadeIn("normal", function(){ // а вот здесь this это ссылка на нативный DOM объект, и чтобы работать с ним // надо сделать так $(this) }); }; })(jQuery); $("#element").myPlugin();

Hello World!!!

Теперь, когда мы понимаем контекст jQuery плагинов, давайте напишем плагин, который на самом деле что-то делает.

(function($){ $.fn.maxHeight = function() { var max = 0; this.each(function() { max = Math.max(max, $(this).height()); }); return max; }; })(jQuery); var tallest = $("div").maxHeight(); // вернет высоту самого высокого div"а

Это простой плагин, который использует метод .height() для возвращения высоты самого высокого DIV"а на странице.

Поддержка цепочек вызовов

В предыдущем примере плагин возвращает целое значение, высоту самого высокого DIV"а на странице, но зачастую цель плагина просто как-то изменить набор элементов, и передать их на следующий метод в цепи вызовов. Красота и лаконичность цепочек вызовов jQuery является одной из причин, почему jQuery так популярна. Таким образом, чтобы поддерживать цепочки вызовов в плагине, Вы должны убедиться, что Ваш плагин возвращает это this в своей главной функции.

(function($){ $.fn.lockDimensions = function(type) { return this.each(function() { var $this = $(this); if (!type || type == "width") { $this.width($this.width()); } if (!type || type == "height") { $this.height($this.height()); } }); }; })(jQuery); $("div").lockDimensions("width").css("color", "red");

Поскольку плагин возвращает this в непосредственном теле его функции, он поддерживает цепочку вызовов и jQuery коллекцией можно продолжать манипулировать JQuery методами, такими, как к примеру .css . Так что если Ваш плагин не возвращает ценного значения, Вы должны всегда возвращать this в непосредственном теле функции плагина. Кроме того, параметры которые вы подаете при вызове плагина, подаются как аргументы функции плагина. В примере выше таким аргументом является type, а при вызове в него подается значение "width". Кстати, плагин Выше закрепляет высоту или ширину каждого блока на странице, в соответствии с его текущими размерами.

Умолчания и опции

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

(function($){ $.fn.tooltip = function(options) { var settings = { "location" : "top", "background-color" : "blue" }; return this.each(function() { // если опции существуют, то совмещаем их // со значениями по умолчанию if (options) { $.extend(settings, options); // при этом важен порядок совмещения } // код плагина тут }); }; })(jQuery); $("div.tools").tooltip({ "location" : "left" });

В этом примере, после вызова плагина tooltip с соответствующими опциями, в настройках по умолчанию затирается поле location на значение "left". В итоге Так настройки примут вид:

{ "location" : "left", "background-color" : "blue" }

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

$("div.tools").tooltip(); // все настройки останутся по умолчанию

Пространство имен

Правильное пространства имен вашего плагина является очень важной частью разработки плагинов. Верно именованный плагин будет иметь очень низкий шанс быть перезаписанным другими плагинами или кодом. Верное именование методов также делает Вашу жизнь проще, так как это помогает лучше отслеживать именно Ваши методы, события и данные. Идея просто, обдуманно называйте Ваш плагин. Посмотрите на следующий пример

alert($("#myid1").html())// сперва метод вернет верное значение Контент1 jQuery.fn.html = function(){ return "Hello World"; } alert($("#myid1").html())// а затем "Hello World";

Методы плагина

Ни при каких обстоятельствах плагин не должен занимать более чем одно имя в объекте jQuery.fn.

(function($){ $.fn.tooltip = function(options) { // ЭТО }; $.fn.tooltipShow = function() { // ОЧЕНЬ }; $.fn.tooltipHide = function() { // ПЛОХО }; $.fn.tooltipUpdate = function(content) { // !!! }; })(jQuery);

Такой код загромождает объект $.fn . Это рекомендуется, поскольку может помех до $. Fn имен. Чтобы исправить это, вы должны собрать все методы Вашего плагина в один объект, и вызывать метод по его строковому имени

(function($){ var methods = { init: function(options) { // ЭТО }, show: function() { // УЖЕ }, hide: function() { // ЛУЧШЕ))) }, update: function(content) { // !!! } }; $.fn.tooltip = function(method) { // логика вызова метода if (methods) { return methods[ method ].apply(this, Array.prototype.slice.call(arguments, 1)); } else if (typeof method === "object" || ! method) { return methods.init.apply(this, arguments); } else { $.error("Метод " + method + " в jQuery.tooltip не существует"); } }; })(jQuery); $("div").tooltip(); // вызов метода init $("div").tooltip({ // вызов метода init с параметрами foo: "bar" }); $("div").tooltip("hide"); // вызов метода hide $("div").tooltip("update", "Это новый контент!"); // вызов метода update с параметрами

Этот тип архитектуры плагинов позволяет инкапсулировать все ваши методы в замыкание плагина, и вызывать методы, указывая первым параметром в плагине строковое название метода, а уже далее какие-либо дополнительные параметры, которые Вам, потребуется для этого метода. Этот тип методов инкапсуляции и архитектуры является стандартом для jQuery плагинов и используется в бесчисленном количестве плагинов, включая плагины и виджеты в jQueryUI .

События

Менее известных особенность метода bind является то, что он позволяет для одного пространства имен установить события. Если ваш плагин порождает некие события, хорошей практикой будет, чтобы событие привязывалось к Вашему пространству имен. Таким образом, если Вам нужно отключить позже, Вы можете сделать это без вмешательства в другие события, которые, возможно, были привязаны к одному типу событий. Вы можете использовать уникальные имена Ваших событий, путем добавления ".<название плагина>".

(function($){ var methods = { init: function(options) { return this.each(function(){ $(window).bind("resize.tooltip", methods.reposition); }); }, destroy: function() { return this.each(function(){ $(window).unbind(".tooltip"); }) }, reposition: function() { // ... }, show: function() { // ... }, hide: function() { // ... }, update: function(content) { // ...} }; $.fn.tooltip = function(method) { if (methods) { return methods.apply(this, Array.prototype.slice.call(arguments, 1)); } else if (typeof method === "object" || ! method) { return methods.init.apply(this, arguments); } else { $.error("Метод " + method + " не существует в jQuery.tooltip"); } }; })(jQuery); $("#fun").tooltip(); // некторое время спустя... $("#fun").tooltip("destroy");

В этом примере, когда плагин tooltip инициализируется методом init, он связывает метод reposition с событием resize окна в пространстве имен "tooltip". Позже, если разработчик должен уничтожить tooltip, мы можем отключить события, связанные c плагином, передав его имя, в данном случае "tooltip", в метод unbind. Это позволяет безопасно отключить события плагина, без случайной отмены привязки событий, которые были связаны с событиями за пределами плагина.

Данные

Часто при разработке плагинов, Вам может понадобиться проверить состояние плагина или проверить, инициализирован ли уже Ваш плагин на данный элемент. Использование метода jQuery.data является отличным способом для отслеживания и хранения переменных для каждого элемента. Однако вместо того, чтобы обслуживать кучу отдельных вызовов data с разными именами, лучше использовать один объект содержащий все переменные, и доступ к этому объекту будет через одно имя.

(function($){ var methods = { init: function(options) { return this.each(function(){ var $this = $(this), data = $this.data("tooltip"), tooltip = $("