Как написать плагин для jQuery

• 05, 23, 2010
•  bullgare
•  javascript, Programming
• No Comments.

Перепечатка статьи, ссылка на оригинал в конце статьи.

За последнее время было много просьб рассказать о том, как написать свой собственный плагин к jQuery. Идя навстречу пожеланиям трудящихся бескрайних полей Интернета – выполняю эти просьбы…

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

Для начала усвоим правила, которым необходимо следовать при написании плагина для jQuery:

• имя файла плагина должно формироваться следующим образом: jquery.[имя_плагина].js;
• все новые методы присоединяются к объекту jQuery.fn, все функции к объекту jQuery;
• в методах, this – это ссылка на текущий объект jQuery;
• любые методы или функции, которые Вы присоединяете, должны иметь точку с запятой в конце – иначе при сжатии код станет некорректным;
• метод должен возвратить объект jQuery, если не предусмотрено иное;
• вы должны использовать this.each, чтобы выполнить итерации по текущему набору элементов – таким путем Вы создадите чистый и совместимый код;
• всегда используйте jQuery вместо $ в коде Вашего плагина – это позволит пользователям изменять псевдоним для jQuery в единственном месте;

Следуя первому правилу, назовем файл нашего плагина jquery.zebra.js и первое, что мы напишем в этом файле, будет определение плагина:

jQuery.fn.zebra = function(){
  // тут мы разместим код плагина
};

И хотя наш плагин еще не содержит вообще никакого кода, его уже можно вызвать следующим образом:

$("selector").zebra();

Но мы договорились, что наш плагин должен уметь принимать некоторые параметры, поэтому давайте немного дополним наш код:

jQuery.fn.zebra = function(options){
  // тут мы разместим код плагина
};

где options – это объект, который может содержит пользовательские настройки. А может и не содержать…. Поэтому первое, что мы сделаем – определим настройки по умолчанию, воспользовавшись для этого jQuery.extend(object).

jQuery.fn.zebra = function(options){
  // настройки по умолчанию
  var options = jQuery.extend({
    bgEven: '#FFC080', // бэкграунд для четных строк
    bgOdd: '#FFDFBF', // бэкграунд для нечетных строк
    fontEven: '#AA7239', // цвет шрифта четных строк
    fontOdd: '#AA7239', // цвет шрифта нечетных строк
    bgHover: '#FF8000', // бэкграунд при hover
    fontHover: '#55391C' // цвет шрифта при hover
  },options);
  // тут мы разместим код
};

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

Двигаемся дальше, и сейчас самое время вспомнить одно из правил написания плагинов к jQuery – вы должны использовать this.each, чтобы выполнить итерации по текущему набору элементов. Заодно вспомним и это правило тоже – метод должен возвратить объект jQuery, если не предусмотрено иное. Проделаем это:

jQuery.fn.zebra = function(options){
  // настройки по умолчанию
  var options = jQuery.extend({
    bgEven: '#FFC080', // бэкграунд для четных строк
    bgOdd: '#FFDFBF', // бэкграунд для нечетных строк
    fontEven: '#AA7239', // цвет шрифта четных строк
    fontOdd: '#AA7239', // цвет шрифта нечетных строк
    bgHover: '#FF8000', // бэкграунд при hover
    fontHover: '#55391C' // цвет шрифта при hover
  },options);
  return this.each(function() {
    // тут мы разместим код
  });
};

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

$("table.example").zebra();

здесь объект jQuery будет содержать таблицу (или таблицы) с классом example.

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

jQuery(this).find('tr:even');

Тут все ясно – this содержит ссылку на текущую таблицу, и в этой таблице мы отбираем только четные строки. Но надо еще установить цвет фона и цвет шрифта для этого набора строк. Воспользуемся для этого css-свойствами background-color и color:

jQuery(this).find('tr:even')
            .css('background-color', options.bgEven)
            .css('color', options.fontEven);

Для всех строк, присутствующих в текущем наборе (сейчас это четные строки текущей таблицы) мы устанавливаем css-свойства background-color и color, получая их значения из объекта options.

Но и этого будет маловато… Нужно обработать прохождение указателя мыши над строкой. Допишем наш код еще немного:

jQuery(this).find('tr:even')
    .css('background-color', options.bgEven)
    .css('color', options.fontEven)
    .hover(
      function () {
	jQuery(this)
              .css('background-color', options.bgHover)
              .css('color', options.fontHover);
      },
      function () {
        jQuery(this)
              .css('background-color', options.bgEven)
              .css('color', options.fontEven);
      }
);

Мы воспользовались методом hover() библиотеки jQuery, передав ему две функции. Первая определит css-свойства в момент, когда указатель мыши находится над строкой, а вторая – вернет старые значения, когда он выйдет за пределы строки.

Точно такой же код нужно написать и для нечетных строк текущей таблицы и в итоге получится следующее:

jQuery.fn.zebra = function(options){
// настройки по умолчанию
var options = jQuery.extend({
  bgEven: '#FFC080', // бэкграунд для четных строк
  bgOdd: '#FFDFBF', // бэкграунд для нечетных строк
  fontEven: '#AA7239', // цвет шрифта четных строк
  fontOdd: '#AA7239', // цвет шрифта нечетных строк
  bgHover: '#FF8000', // бэкграунд при hover
  fontHover: '#55391C' // цвет шрифта при hover
},options);
return this.each(function() {
  // четные строки
  jQuery(this).find('tr:even')
    .css('background-color', options.bgEven)
    .css('color', options.fontEven)
    .hover(
      function () {
        jQuery(this)
              .css('background-color', options.bgHover)
	      .css('color', options.fontHover);
      },
      function () {
        jQuery(this)
               .css('background-color', options.bgEven)
               .css('color', options.fontEven);
      }
    );
  // нечетные строки
  jQuery(this).find('tr:odd')
    .css('background-color', options.bgOdd)
    .css('color', options.fontOdd)
    .hover(
      function () {
        jQuery(this)
               .css('background-color', options.bgHover)
               .css('color', options.fontHover);
      },
      function () {
        jQuery(this)
               .css('background-color', options.bgOdd)
               .css('color', options.fontOdd);
      }
    );

});
};

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

О плагине jquery.zebra.js

Плагин jquery.zebra.js позволяет легко изменять цвет фона и шрифта для четных и нечетных строк таблицы, выделяет цветом строку над которой находится указатель мыши. Совместим с IE 6.0+, FF 2+, Safari 2.0+, Opera 9.0+.

Установка плагина jquery.zebra.js

Подключите к странице требующиеся для работы файлы – библиотеку jQuery и файл плагина:

<script type="text/javascript" src="js/jquery.js"></script>
<script type="text/javascript" src="js/jquery.zebra.js"></script>

Использование плагина jquery.zebra.js

1. Использование плагина с настройками по умолчанию:

<script type="text/javascript">
$(document).ready(function(){
    $("table.bClass").zebra();
});
</script>

В этом примере плагин работает с таблицей (или таблицами), которая имеет класс bClass. К четным и нечетным строкам таблицы будут применены css-правила, которые зададут для них разный цвет фона и разный цвет шрифта. В примере будут использованы настройки по умолчанию.

2. Использование плагина с пользовательскими настройками:

<script type="text/javascript">
$(document).ready(function(){
    $("table.cClass").zebra({
      bgEven: "#CC66CC",
      bgOdd: "#E6ACE6",
      fontEven: "#662266",
      fontOdd: "#662266",
      bgHover: "#331133",
      fontHover: "#FFFFFF"
    });
});
</script>

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

Доступные опции.

bgEven – строка: цвет фона для четных строк.
bgOdd – строка: цвет фона для нечетных строк.
fontEven – строка: цвет шрифта четных строк.
fontOdd – строка: цвет шрифта нечетных строк.
bgHover – строка: цвет фона при прохождении указателя мыши над строкой.
fontHover – строка: цвет шрифта при прохождении указателя мыши над строкой.

Демонстрация работы.

Здесь можно посмотреть демо

Вот и все. Осталось разве что привести пару ссылок по теме:

http://docs.jquery.com/Plugins/Authoring
http://www.learningjquery.com/2007/10/a-plugin-development-pattern

и теперь Вы знаете как написать свой плагин для библиотеки jQuery. Удачи!

Оригинал статьи.