jQuery плагин – 12 советов по написанию

Несмотря на столь большое количество документации о написании jQuery плагинов, практических советов мало. Нет ни одного примера документа, где описано, какими качествами должен обладать хороший jQuery плагин. В статье рассмтариваются 12 советов, которые помогут написать плагин jQuery своими руками.

В этой статье мы меньше будем фокусироваться на самом Java Script коде, больше будем уделять внимания практическим советам.

1 – Пишите плагин по правильному шаблону

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

(function($, window, undefined){
$.fn.myPlugin = function(opts) {
   var defaults = {
      // установите ваши стандартные переменные
   }
 
  // дополните стандартные опции пользовательскими
  var options = $.extend(defaults, opts || {});
 
   return this.each(function(){ // jQuery chainability
     // действия плагина
   });
})(jQuery, window);

Для начала, мы создаем анонимную функцию, которая защитит нас от использования глобальных переменных. По умолчанию передаются три аргумента: $, window, и undefined. Они потребуются ядру jQuery.

Далее мы напишем шаблон jQuery плагина, $.fn.PluginName. Таким образом, мы регистрируем плагин, чтобы можно его было использовать в формате $(selector).method(). Если вы хотите вместо написания плагина использующего функции, сделать его напрямую, пишите следующим образом:

$.PluginName = function(options){
   // опции и действия плагина
}

Такой тип плагина не может иметь цепочку функций, он будет состоять из одной прямой функции. Для примера:

$.splitInHalf = function(stringToSplit){
   var length = stringToSplit.length;
   var stringArray = stringToSplit.split(stringToSplit[Math.floor(length/2)]);
   return stringArray;
}

В этом коде, мы возвращаем массив строк. Для большей ясности, еще один пример:

$.getOddEls = function(jQcollection){ //
   return jQcollection.filter(function(index){
      var i = index+1;
      return (index % 2 != 0);
   });
}

В этом случае, пользователь получает jQuery объект, фильтр, которые берется из jQuery коллекции. Плагины могут возвращать, как массивы, так и строки, цифры, функции, и другие типы данных.

2 – Документируйте свой код (корректно)

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

Документация, это практика, которая не потребует особых правил для ее реализации. Хотя, и так понятно, что чем удобнее и подробнее расписана, тем лучше.

Нужно документировать как внутри кода (комментированием), так и снаружи – отдельным документом, расписать каждый класс, метод, опцию, их случаи использования и так далее.

3 – Сделайте ваш плагин гибким в настройках

Наиболее популярные плагины предрасполагают возможность доступа к переменным, чтобы пользователи могли контролировать некую функциональность плагина. Также, хорошей вещью является возможность вносить свои настройки. Для примера, при создании плагина слайдера, уместными настройками будут – скорость перелистывания, тип слайд шоу, и расширение блока слайдера.

Также хорошей практикой, является возможность доступа к именам классов и ID, с помощью которых мы выбираем DOM элемент. Наряду с этим, они также должны иметь возможность иметь доступ к callback функции, во время каждого ее вызова. Или, когда слайдер делает цикл и возвращается на первый элемент (картинку).

Думать об удобстве использования(юзабилити) и потребностях пользователей - задача разработчика

Давайте рассмотрим еще один пример: плагин делает запрос к API, он должен иметь возможность доступа к возвращенному объекту. Вот пример этой концепции:

$.fn.getFlickr = function(opts) {
   return this.each(function(){ // jQuery chainability
      var defaults = { // опции по умолчанию
         cb : function(data){},
         flickrUrl : // стандартные значения для вызова API
      }
       // расширяем опции пользовательскими
       var options = $.extend(defaults, opts || {});
 
       // вызываем асинхронные функции потом callback
       // передаем в  API объект, который возвратился
       $.ajax(flickrUrl, function(dataReturned){
         options.cb.call(this, dataReturned);
      });
   });
}

Такой код, позволяет нам иметь доступ к данным с помощью следующей строки:

$(selector).getFlickr(function(fdata){ // flickr данные в fdata объекте });

Иной способ доступа к данным, использование хуков (крючков), как опций. В jQuery версии 1.7.1 и выше, мы можем использовать .on(eventName, function(){}) после вызова нашего плагина, чтобы использовать поведение плагина в собственных функциях пользователей. Для примера, плагин ниже, хороший пример, как это реализовать:

$.fn.getFlickr = function(opts) {
   return this.each(function(i,el){
      var $this = el;
      var defaults = {
         flickrUrl : "http://someurl.com"
      }
       var options = $.extend(defaults, opts || {});
 
       $.ajax(flickrUrl, function(dataReturned){
         $this.trigger("callback", dataReturned);
      }).error(function(){
            $this.trigger("error", dataReturned);
         });
   });
}

Это дает нам возможность вызывать getFlickr плагин, плюс к этому, прицеплять некоторые «пожелания».

$(selector).getFlickr(opts).on("callback", function(data){ // действие }).on("error", function(){ // обработка ошибки });

Вы даже не подозреваете, насколько важно снабжать свой jQuery плагин гибкостью и возможностью настройки. Чем более сложный ваш плагин – тем более настроек должен содержать.

4 – Не используйте слишком много конфигураций

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

$(selector).myPlugin();

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

$(selector).fetchTweets("jcutrell");

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

5 – Выносите CSS указания в отдельный файл

Естественно, это касается только определенных плагинов… но, старайтесь все CSS указания выносить в отдельный файл. Так будет проще при создании UI.

Большинство плагинов содержат в комплекте картинки и CSS стили. Но не забывайте второй совет – документируйте CSS стили с картинками также. Разработчики, вряд ли желают просматривать код, чтобы найти то, что им нужно поменять.

Наиболее удобно использовать стилизацию основанную на class/ID доступе. Но классы и ID должны также быть доступными и описанными в документации, чтобы пользователю не приходилось определять, что там происходит.

6 – Предоставьте примеры использования вашего плагина

Если вы не можете предоставить примеры возможностей своего плагина, лучше и не начинайте писать его. Пользователи долго не будут смотреть на него, просто уйдут искать другой.

Это не сложно, ведь вы разработчик плагина. Не будьте ленивы. Вот хорошие идеи для примеров:

«Hello World» пример – всегда удобно использовать в плагинах, которые работают с HTML и CSS.

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

7 – Пишите плагин, сопоставим с большинством версий jQuery

jQuery, как и любая хорошая библиотека, растет и развивается. Некоторые старые методы больше не доступны, некоторые новые вводятся. Хорошим примером этому является .on() метод, который решением «все в одном» для делегации событий. Если вы пишите плагин используя этот метод, люди, которые используют версию jQuery 1.6 будут обделены. Я не имею в виду, что ваш код должен содержать устаревшие методы, но в документации обязательно укажите используемую версию jQuery.

8 – Ведите Changelog

Наряду с обновлением кода плагина под новую версию jQuery, также необходимо контролировать и документировать все обновления. Наилучше делать это с помощью всем известного сервиса GitHub. Это публичный репозиторий, на котором можно хранить все версии плагина, changelog и другое.

9 – Пишите востребованный плагин

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

Если вы все таки решили написать плагин для социальной сферы разработчиков, найдите причину, по которой стоит его писать. Как мы любим выражаться: «Зачем изобретать колесо вновь»? Само собой, иногда новые и лучшие способы тех же вещей приветствуются. Но для этого должны быть вязкие практические причины.

10 – Предоставьте сжатую версию кода

Такой маленький, но очень разумный совет! Сжатая версия делает ваш плагин более востребованным. Разработчикам также важно знать, сколько будет «весить» ваш продукт.

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

11 – Ваш код слишком заумный

Когда вы пишите плагин для jQuery, предполагается, что он будет использоваться другими… не так ли? По этой причине, код вашего плагина должен быть как можно лучше читаем. Если вы лепите все в одну строку или не семантично называете переменные, это создает трудности при чтении кода. Хорошо отформатированный код, это неплохое дополнение к документации. А насчет длинных названий переменных не волнуйтесь, ведь можно просто сжать код.

Называть переменные «a» или «x» - это неправильно!

Также, старайтесь уменьшить число строк в каждой из функции. Так проще для понимания и более логично.

12 – Тестируйте

Надеюсь, вы всегда тестируете свой код, правда? Если нет, как вы можете публиковать его, если не уверены в работоспособности. Ручное тестирование всегда важно, но если вы обновляете страницу в браузере чтобы тестировать работоспособность плагина – это не правильно. Советую пользоваться такими инструментами, как – Qunit, Jasmine, Mocha.

Заканчивая мысли

Если вы собрались писать jQuery плагин, держите на виду эти советы. Может быть, я что-то пропустил. Если знаете, какими еще положительными качествами должен обладать хороший плагин, дайте знать в комментариях. Творческих вам успехов!