jQuery UI – надстройка над JavaScript-библиотекой jQuery. Она поможет создавать по настоящему интерактивные веб-приложения. Сегодня мы познакомимся с виджетом Datepicker.
Виджет Datepicker
Datepicker – это интерактивный календарь, который связан с полем ввода. Щелчок в поле ввода приводит к тому, что в отдельном слое открывается небольшой календарь. Выбираете нужную дату и готово – дата занесена в поле ввода.

Для начала посетим страницу настраиваемой закачки на сайте jQuery UI, чтобы получить необходимые нам файлы. Щелкаем на ссылке Deselect all component , чтобы не закачивать лишнее, а затем выбираем только то, что нам потребуется – отмечаем чекбокс Datepicker и чекбокс UI Core.
Кроме этого, справа есть выпадающий список, где можно выбрать понравившуюся тему оформления. Если все готово, кликаем кнопку Download и получаем архив. Можно испытать пример как есть, но интереснее создать свою HTML-страничку, где сначала в разделе HEAD подключить несколько файлов, которые есть в архиве.

<link type="text/css" href="css/ui-lightness/jquery-ui-1.7.2.custom.css" rel="stylesheet" />
<script src="js/jquery-1.3.2.min.js" type="text/javascript"></script>
<script src="js/jquery-ui-1.7.2.custom.min.js" type="text/javascript"></script>
<script src="js/i18n/jquery-ui-i18n.js" type="text/javascript"></script>

Сначала мы подключили файл стилей одной из многочисленных тем оформления. Кроме этого мы подключили файл библиотеки и файл, в котором заключена функциональность UI Core и виджета Datepicker. И наконец, последний файл обеспечивает локализацию виджета для нужного языка. Найти его можно в полученном архиве, в папке /development-bundle/ui/i18n

Из разметки потребуется минимум – просто элемент input:

<input  id="datepicker" type="text" />

Кстати, если Вы хотите, чтобы календарь не появлялся по щелчку в элементе input, а был всегда виден – просто используйте обычный элемент div:

<div  id="datepicker"><div>

Связываем виджет Datepicker с нашей HTML-разметкой:

<script type="text/javascript">
$(function(){
  $("#datepicker").datepicker();
});
</script>

Отлично! С настройками по умолчанию все понятно, но нам хотелось бы иметь календарь на русском языке (или, к примеру, на украинском). Давайте это сделаем:

<script type="text/javascript">
$(function(){
  $.datepicker.setDefaults(
        $.extend($.datepicker.regional["ru"])
  );
  $("#datepicker").datepicker();
});
</script>

Приведенный в примере код обеспечит поддержку русского языка, а если Вы замените ru на uk (интересно, почему не на ua?) то получите календарь уже на украинском языке.

Но вероятно Вам понадобится изменить какие-то настройки, чтобы использовать Datepicker для решения своих задач. Давайте попробуем это сделать.

<script type="text/javascript">
$(function(){
  $.datepicker.setDefaults(
        $.extend($.datepicker.regional["ru"])
  );
  $("#datepicker").datepicker({
    minDate: "-30",
    maxDate: "+1m +1w +3d"
  });
});
</script>

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

altField – jQuery селектор для другого поля, которое должно быть обновлено, как только будет выбрана дата в Datepicker. Формат даты в этом дополнительном поле устанавливается с помощью опции altFormat.

altFormat – формат даты, который будет использоваться для опции altField. Эти настройки позволяют показывать пользователю один формат даты, тогда как для вычислений может использоваться другой формат. Полный список возможных форматов можно найти на
http://docs.jquery.com/UI/Datepicker/formatDate

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

buttonImage – адрес картинки, которая будет отображаться на кнопке, с помощью которой можно вызывать календарь. Используется совместно с опцией showOn, когда та принимает значения ‘button’ или ‘both’. Если был определен текст в опции buttonText, он становится значением атрибута alt картинки.

buttonImageOnly – если для этой опции установить значение true, то картинка, адрес которой определен в опции buttonImage, будет отображаться не на кнопке, а сама по себе.

buttonText – текст, отображающийся на кнопке, с помощью которой можно вызывать календарь. Используется совместно с опцией showOn, когда та принимает значения ‘button’ или ‘both’.

changeMonth – если в этой опции передать значение true, будет возможно выбирать месяц из выпадающего списка.

changeYear – если в этой опции передать значение true, будет возможно выбирать год из выпадающего списка.

closeText – эта опция используется совместно с showButtonPanel, если последняя имеет значение true. Значение опции closeText определяется в файле локализации, если он используется, но это значение можно переопределить, явно указав его.

constrainInput – по умолчанию опция имеет значение true и принуждает строго соблюдать формат даты, определенный в опциях виджета, в текстовом поле ввода. Чтобы иметь возможность не соблюдать этот формат, следует установить опцию в false.

currentText – эта опция используется совместно с showButtonPanel, если последняя имеет значение true. Значение опция currentText определяется в файле локализации, если он используется, но это значение можно переопределить, явно указав его.

dateFormat – определяет формат даты. Значение опции dateFormat определяется в файле локализации, если он используется, но это значение можно переопределить, явно указав его. Полный список возможных форматов можно найти на

http://docs.jquery.com/UI/Datepicker/formatDate

dayNames – массив, содержащий полные названия дней недели, начиная с воскресенья. Определяется в файле локализации, если он используется, но это значение можно переопределить, явно указав его.

dayNamesMin – массив, содержащий 2-хбуквенную аббревиатуру названия дней недели, начиная с воскресенья. Определяется в файле локализации, если он используется, но это значение можно переопределить, явно указав его.

dayNamesShort – массив, содержащий 3-хбуквенную аббревиатуру названия дней недели, начиная с воскресенья. Определяется в файле локализации, если он используется, но это значение можно переопределить, явно указав его.

defaultDate – устанавливает дату, которая будет подсвечена при первом открытии, если поле выбора даты пустое. Опция может быть определена через объект Date, либо как количество дней от текущего для (например +7 или -15), либо как строка значений, определяющих период (‘y’ для лет, ‘m’ для месяцев, ‘w’ для недель, ‘d’ для дней, например ‘+1m +7d’), и наконец как null для текущего дня.

duration – длительность эффекта анимации при открытии (закрытии) календаря. Может принимать значения в виде строки – ‘fast’, ‘normal’ (по умолчанию), ’slow’ или в виде числа в миллисекундах. Если передать пустую строку, календарь будет открываться и закрываться без эффекта анимации.

firstDay – опция устанавливает первый день недели: воскресенье – 0, понедельник – 1,… Определяется в файле локализации, если он используется, но это значение можно переопределить, явно указав его.

gotoCurrent – если установить значение опции в true, то кнопка «Сегодня» (доступная при showButtonPanel: true) будет указывать на выбранную дату взамен текущей.

hideIfNoPrevNext – если Вы ограничиваете диапазон доступных дат с помощью опций minDate и maxDate, то при достижении края диапазона, стрелки «Назад» и «Вперед» становятся неактивными. Но их можно и совсем скрывать, передав в опции hideIfNoPrevNext значение true.

isRTL – для этой опции необходимо установить значение true, если используется язык с написанием справа налево. Определяется в файле локализации, если он используется.

maxDate – устанавливает максимальную возможную для выбора дату через объект Date или как число дней от текущего (например +7) или как строку значений определяющих период (‘y’ для лет, ‘m’ для месяцев, ‘w’ для недель, ‘d’ для дней, например ‘+1y +1m’), или null для отсутствия ограничения.

minDate – устанавливает минимальную возможную для выбора дату через объект Date или как число дней от текущего (например -7) или как строку значений определяющих период (‘y’ для лет, ‘m’ для месяцев, ‘w’ для недель, ‘d’ для дней, например ‘-1y -1m’), или null для отсутствия ограничения.

monthNames – массив, содержащий полные названия месяцев. Определяется в файле локализации, если он используется, но это значение можно переопределить, явно указав его.

monthNamesShort – массив, содержащий 3-хбуквенную аббревиатуру названия месяцев. Определяется в файле локализации, если он используется, но это значение можно переопределить, явно указав его.

navigationAsDateFormat – по умолчанию опция имеет значение false. Если установить значение true, функция dateFormat будет примерена к значениям опций nextText, prevText и currentText с тем, чтобы отображать при навигации, например предыдущее и следующее названия месяцев.

nextText – текст, который отображается в качестве ссылки на следующий месяц. Определяется в файле локализации, если он используется, но это значение можно переопределить, явно указав его. Если используется файл стилей ThemeRoller’а, это значение заменяется иконкой.

numberOfMonths – эта опция определяет, сколько месяцев сразу нужно показать. Значение опции может быть просто числом или массивом, состоящим из двух элементов, которые определяют соответственно количество строк и столбцов. Например, значение [2, 3] отобразит календарь в две строки по три месяца.

prevText – текст, который отображается в качестве ссылки на предыдущий месяц. Определяется в файле локализации, если он используется, но это значение можно переопределить, явно указав его. Если используется файл стилей ThemeRoller’а, это значение заменяется иконкой.

shortYearCutoff – значение по умолчанию +10. Эта опция используется только при условии использования в dateFormat двузначной записи года и выполняет роль компенсатора для определения века. Если значение передано в виде числа, используется как есть. Если значение передано в виде строки, конвертируется в число и добавляется к текущему значению года. После того как значение определено, все данные, выступающие в качестве значения года, и меньшие и равные ему считаются годами текущего века. Значения большие – считаются годами предыдущего века.

showAnim – определяет тип анимации при открывании календаря. По умолчанию имеет значение show (при закрывании будет использован hide). Без подключения дополнительных файлов могут быть использованы эффекты ’slideDown’ и ‘fadeIn’ (при закрывании соответственно будут использоваться эффекты ’slideUp’ и ‘fadeOut’). Так же возможно использование любых эффектов jQuery UI Effects при условии их дополнительного подключения.

showButtonPanel – установка значения true для этой опции приведет к тому, что будет показана панель с двумя кнопками – переход к сегодняшней дате и закрытие календаря.

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

showMonthAfterYear – по умолчанию используется значение false и в заголовке название месяца идет перед годом. При использовании значения true название месяца будет следовать за годом.

showOn – по умолчанию эта опция имеет значение ‘focus’, что заставляет календарь открываться при щелчке в поле ввода. Другие возможные значения – ‘button’ и ‘both’. Рядом с полем ввода появится кнопка. В первом случае календарь будет открываться по щелчку на кнопке, а во втором случае как по щелчку на кнопке, таки при получении фокуса полем ввода.

showOptions – если Вы используете один из эффектов jQuery UI Effects, с помощью этой опции ему можно передать дополнительные настройки. Например: showOptions: {direction: ‘up’}.

showOtherMonths – по умолчанию имеет значение false. Если использовать true, на календаре будут отображаться дни предыдущего и/или следующего месяца без возможности их выбора.

stepMonths – определяет насколько месяцев сдвигать календарь при щелчке по ссылкам Следующий и Предыдущий. По умолчанию – 1.

yearRange – управление диапазоном лет, отображаемых в выпадающем списке (при использовании опции changeYear). По умолчанию используется значение ‘-10:+10′ относительно текущего года. Возможно использование и абсолютного формата, например ‘1980:2025′.

Перейдем к знакомству с событиями виджета Datepicker:

<script type="text/javascript">
$(function(){
  $.datepicker.setDefaults($.extend(
    $.datepicker.regional["ru"])
  );
  $("#datepicker").datepicker({
    beforeShow: function(input) {
      $(input).css("background-color","#ff9");
    },
    onSelect: function(dateText, inst) {
      $(this).css("background-color","");
      alert("Выбрано: " + dateText +
        "\n\nid: " + inst.id +
        "\nselectedDay: " + inst.selectedDay +
        "\nselectedMonth: " + inst.selectedMonth +
        "\nselectedYear: " + inst.selectedYear);
    },
    onClose: function(dateText, inst) {
      $(this).css("background-color","");
    }
  });
});
</script>

В примере мы передаем виджету сразу три опции, в которых определены callback-функции. В опции beforeShow определена функция, которая будет вызвана перед отображением календаря. С помощью css-свойства background-color, эта функция установит желтый цвет фона для элемента input. В опции onSelect определена функция, которая будет вызвана в момент выбора какой-либо даты в календаре и передаст пустое значение css-свойству background-color, возвратив его в начальное состояние. И, наконец, в опции onClose определена функция, которая вызывается при закрытии календаря, если никакое значение выбрано не было. Она тоже вернет css-свойство background-color в его начальное состояние.

Но, обратите внимание, все callback-функции принимают некоторые аргументы. С ними стоит познакомиться немного подробнее.

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

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

Функция, определенная в опции onClose принимает те же два аргумента, что и функция из опции onSelect.

И еще одно важное обстоятельство для callback-функций, определенных в опциях onSelect и onClose – в контексте этих функций ссылка this указывает на объект, характеризующий элемент input.

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

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

beforeShowDay – в этой опции можно определить пользовательскую функцию, которая будет принимать в качестве аргумента выбранную дату. Функция должна возвратить массив, где элемент с индексом [0] – true или false показывает, возможен или нет выбор этой даты. Элемент с индексом [1] содержит имя класса (классов) для отображения даты. Элемент с индексом [2] (опционально) – текст всплывающей подсказки для даты. Функция будет вызываться для каждой даты в календаре в момент наведения указателя мыши.

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

onClose – в этой опции определяется функция, которая будет вызвана, когда календарь был закрыт без выбора какой-либо даты.

onSelect – в этой опции определяется функция, которая будет вызвана, когда в календаре выбрана какая-либо дата.

Теперь можно поговорить о методах виджета Datepicker. Давайте добавим в наш HTML-код обыкновенную ссылку:

<a href="#">Открыть в диалоге</a>

и используем вот такой javascript-код:

<script type="text/javascript">
$(function(){
  $.datepicker.setDefaults(
      $.extend($.datepicker.regional["ru"])
  );
  $("#datepicker").datepicker({
    changeYear: true
  });
  $("a").click(function(){
    $("#datepicker").datepicker(
        "dialog",
        "23.04.2009",
        function(){
          alert("Событие onSelect");
        },
        { showButtonPanel: true },
        [300, 300]
    );
  });
});
</script>

В приведенном примере мы демонстрирует работу метода dialog. Мы вызываем этот метод при щелчке на ссылке Открыть в диалоге. Первый аргумент – это название метода, второй аргумент textDate – дата на которой по умолчанию будет открываться календарь. Остальные три аргумента необязательные, но мы познакомимся и с ними. В аргументе onSelect можно передать callback-функцию, которая будет вызвана при выборе конкретной даты в календаре. В аргументе settings можно передать объект с новыми настройками виджета, которые будут применены к календарю, который будет открыт в диалоговом окне. И, наконец, последний аргумент pos – здесь можно задать координаты, в которых будет появляться календарь. Координаты можно задавать числами, но если передать в функцию, вызываемую по щелчку на ссылке объект event, то можно будет определить координаты, используя свойства объекта event. Например, использовать event.clientX и event.clientY.

Далее приведены описания всех методов виджета Datepicker.

destroy – .datepicker(‘destroy’) полностью удаляет всю функциональность виджета Datepicker. Возвращает элементы в состояние, предшествующее инициализации.

disable – .datepicker(‘disable’) временно запрещает использование всей функциональности виджета. Вновь разрешить ее использование можно с помощью метода enable.

enable – .datepicker(‘enable’) разрешает использование всей функциональности виджета, если ранее она была запрещена с использованием метода disable.

option – .datepicker(‘option’, optionName, [value]) с помощью этого метода можно получить или установить значение любой опции виджета после инициализации.

dialog – .datepicker(‘dialog’, dateText, [onSelect], [settings], [pos]) открывает виджет Datepicker в режиме диалогового окна. В аргументе dateText передается дата, на которой должен быть открыт календарь. Остальные аргументы необязательные. В аргументе onSelect можно передать функцию, которая будет вызвана в момент выбора даты в календаре, в аргументе settings можно передать объект с новыми настройками виджета, в аргументе pos – координаты, в которых будет открыто диалоговое окно. Здесь можно использовать события мыши, чтобы определить координаты.

isDisabled – .datepicker(‘isDisabled’) метод возвращает значение true, если к виджету был применен метод disable и false в противном случае.

hide – .datepicker(‘hide’, [speed]) скрывает ранее открытый календарь.

show – .datepicker(’show’) открывает календарь.

getDate – .datepicker(‘getDate’) метод возвращает дату, выбранную в календаре.

setDate – .datepicker(’setDate’, date) метод позволяет установить дату в календаре. Значением аргумента date может быть число, определяющее количество дней от текущей даты (например: +7 или -14) или строка, определяющая период (‘y’ для лет, ‘m’ для месяцев, ‘w’ для недель, ‘d’ для дней, например ‘+1m +7d’). Значение null установит текущую дату.

Вот и все. Разве что сказать, что для управления календарем можно использовать горячие клавиши:
- page up/down – предыдущий/следующий месяц;
- ctrl+page up/down – предыдущий/следующий год;
-ctrl+home – выбор текущего месяца или открытие календаря после того как он был закрыт;
- ctrl+left/right – предыдущий/следующий день;
- ctrl+up/down – предыдущая/следующая неделя;
- enter – выбор отмеченной даты;
- ctrl+end – закрытие и удаление даты из поля ввода;
- escape – закрытие календаря без выбора даты;

google.com bobrdobr.ru del.icio.us technorati.com linkstore.ru news2.ru rumarkz.ru memori.ru moemesto.ru