JQuery UI Autocomplete — Использование виджета автозаполнения. Автозаполнение полей формы (плагин jQuery-Autocomplete)
a! Представляю Вам очередную статью в рубрике «Плагины». Рассмотрим плагин jQuery-Autocomplete , с помощью которого легко создать автозаполнение текстовых полей формы. Работает только на jQuery, для хранение значений автозаполнения можно использовать текстовый файл.
HTML разметкаУ поля к которому следуют прикрепить автозаполнение, должен быть атрибут id , именно по нему будет идти привязка:
|
Теперь вызываем метод .autocomplete :
В приведенном примере метод .autocomplete
вызывается с 2мя параметрами, lookup
где
countriesArray
— это массив со странами, о нем и как он формируется немного ниже, а также onSelect
— функция обратного вызова при выборе элемента из предложенного списка.
- serviceUrl — путь до файла с значениями.
- lookup
— массив значений. Это может быть массив строк или:
- suggestion — литерал объекта в формате { value: ‘string’, data: any }
- lookupFilter — function (suggestion, query, queryLowerCase) {} Функция фильтрации для поиска в массиве. По умолчанию частичное совпадение строк (без учета регистра);
- onSelect — Callback функция, вызывается когда пользователь выбирает значение из предложенного списка;
- minChars — Минимальное количество символов, необходимых для запуска автозаполнения. По умолчанию: 1;
- maxHeight — Максимальная высота контейнера со списком значений, в пикселях. По умолчанию: 300;
- deferRequestBy — Количество миллисекунд задержки AJAX запроса. По умолчанию: 0;
- width — Ширина контейнера со списком значений автозаполнения в пикселях, например: 300. По умолчанию: auto;
- params — Дополнительные параметры, передаваемые с запросом, необязательно.
- formatResult — function (suggestion, currentValue) {} пользовательские функции, необязательно.
- delimiter — Строка или RegExp, который разбивает входное значение. Полезно когда, например, вам нужно заполнить список значений, разделенных запятыми;
- zIndex — свойство css zIndex для контейнера со списком предложений. По умолчанию: 9999;
- type — тип Ajax запроса. По умолчанию: GET ;
- noCache — Логическое значение, указывающее, следует ли кэшировать результаты списка предложений. По умолчанию True.
- onSearchStart — function (query) {} вызывается перед запроса AJAX. this связано с input элементом;
- onSearchComplete — function (query) {} вызывается после запроса AJAX. this связано с input элементом;
- tabDisabled — по-умолчанию false . Устанавливает курсор ввода после выбора предложенного значения;
- paramName — по-умолчанию query . Имя параметра запроса, который содержит запрос;
- transformResult — function(response) {} Вызывается после того, как станет готов результат запроса. Преобразует результат в response.suggestions формат;
- autoSelectFirst — если установлено true , первый пункт будет подсвечен при показе списка предложений. Значение по-умолчанию false ;
- appendTo — контейнер, в который будет добавлен список предложений. По-умолчанию body . Может быть JQuery объект, селектор или HTML элемент. Убедитесь в том, чтобы было установлено position: absolute или position: relative для этого элемента.
Теперь о массиве со списком значений выбора. Как писалось в начале это также может быть отдельный текстовый файл, с соответствующей структурой. Вот так выглядит массив:
1 | var
countriesArray =
[
|
1 | // Подгружаем страны из текстового файла:
var countriesArray = $.map (source, function (value, key) { return { value: value, data: key } ; } ) ; |
Где с помощью метода $.map переводим все элементы массива из файла в новый массив со значениями.
ОформлениеСтруктура списка предложений выглядит так:
1 |
|
И применяется простое оформление.
Ну вот и готова предрелизная версия mSearch2. Мы должны ее дружно потетстировать, поправить баги и получится стабильная версия.
В принципе, теперь я воплотил все свои (и не только свои) хотелки. У нас добавилось управление словарями прямо в вдминке и автодополнение.
Со словарями всё просто - при установке дополнения сразу загружаются 2 словаря: русский и английский. Если вам нужно добавить или удалить словарь, для этого появился новый раздел в админке.
В индексации участвуют все установленные словари, ничего настраивать не нужно. При загрузке словаря вы можете выбрать зеркало SourceForge, чтобы качать с ближайшего к вам сервера.
Но все вопросы решены и теперь у нас есть новый сниппет mSearchForm . Вот его параметры:
- &pageId - id страницы, на которую будет отправлен юзер в месте с запросом. Если не указано - это будет текущая страница.
- &tplForm - чанк с фомой для вывода. У тега form обязательно должен быть указан класс msearch2 .
- &tpl - Оформление строчек автодополнения.
- &autocomplete - Настройка автоподсказок. Доступно 3 варианта: results (по умолчанию, поиск по сайту), queries (поиск по запросам) и 0 - отключить.
- &limit - Ограничение выборки строк автодополнения.
- &element - Какой сниппет оформляет результаты. Это актуально только для режима results .
Первый самый интересный - он ищет точно так же как и сниппет mSearch2, получает id совпадений и передаёт их в указанный сниппет. А сниппет может быть любым, главное, чтобы он понимал параметр &resources
.
Заодно сниппету будут переданы все параметры, указанные при вызове mSearchForm - очень похоже на работу mFilter2 с пагинатором.
Таким образом, вы можете указать чанки, подключение ТВ, таблиц, картинок товаров и чего угодно. Так как этот режим сразу выводит точное совпадение, при выборе результата вы отправитесь на конечную страницу - вам нечего искать, вы уже нашли.
Понятно, можно не кликать, а жать enter и будет поиск по тому, что вы набрали, без подсказок. Конечно, все теги в чанках выполняются. Например, мне очень нравится вызывать в них pdoCrumbs .
А второй режим попроще - он просто смотрит таблицу запросов, которая появилась в прошлой версии, и выводит совпадения из неё. Выводит, понятно, только те, что с результатами. Потому, что от дополнения «ккккувпусм» толку никакого не будет (вы бы видели, что у меня на сайте ищут). 
Само дополнение работает на
Если Вы пробовали что-то найти в, то наверняка знаете, что после ввода символа в текстовое поле появляется выпадающий список, который содержит десяток строк со словами, начальные символы которых совпадают с теми символами, что Вы уже успели ввести. Так работает Google Suggest. Почему бы не сделать так же на своем сайте? Ведь это удобно. К тому же с библиотекой jQuery это не так уж и сложно…
Как обычно, для начала я приведу пример, а потом мы будем разбирать, как он работает.
Поскольку это всего лишь пример, поясню, что в левом текстовом поле доступен выбор российских городов, которые начинаются на букву «М», а в правом – список поселков городского типа (пгт) с численностью населения более 10 тыс. жителей (по данным Всероссийской переписи населения на 9 октября 2002 года).
Кроме того, используются разные настройки. В общем, попробуйте пример, а потом продолжим….
Вы можете скачать исходный код примера, и при наличии библиотеки jQuery воспроизвести это пример на своем сайте.
Сначала потребуется только подключить библиотеку и файл query.autocomplete.js в разделе HEAD нужной страницы.
Если скачаете пример, то легко сможете разобраться и в стилевом оформлении. Учтите, что файл jquery.autocomplete.js использует имена классов (начинаются с ac_), но если Вы захотите по каким-то причинам изменить эти имена – это тоже можно будет довольно легко сделать.
Что касается HTML-кода, то естественно нужно описать поле для ввода текста:
А вот использовать jquery.autocomplete.js можно двумя разными способами.
Способ первый:
Если объем данных не очень большой, и данные не будут изменяться, то их можно поместить непосредственно на странице, как и сделано в примере в текстовом поле слева.
$(document).ready(function(){ $("#example").autocompleteArray([ "Магадан", "Магас", "Магнитогорск", "Майкоп", ........ "Муром", "Мценск", "Мыски", "Мытищи", "Мышкин" ], { delay:10, minChars:1, matchSubset:1, autoFill:true, maxItemsToShow:10 }); });
Способ второй:
Если данные большого объема, и/или часто изменяются, то необходимо предусмотреть обработку этих данных на сервере (для примера выбран PHP). jquery.autocomplete.js
предусматривает отправку GET-запроса с параметром q
, значением которого являются введенные символы. Именно так в примере работает текстовое поле справа.
$(document).ready(function(){ $("#example2").autocomplete("autocomplete.php", { delay:10, minChars:2, matchSubset:1, autoFill:true, matchContains:1, cacheLength:10, selectFirst:true, formatItem:liFormat, maxItemsToShow:10, onItemSelect:selectItem }); });
В этих примерах, помимо данных (в первом случае) и URL обработчика (во втором случае) мы передаем некоторые опции. Список опций приведен ниже:
autoFill – когда Вы начинаете вводить текст, в поле ввода будет подставлено (и выделено) первое подходящее значение из списка. Если Вы продолжаете вводить текст, в поле ввода и далее будет подставляться подходящее значение, но уже с учетом введенного Вами текста. (По умолчанию: false).
inputClass – этот класс будет добавлен к элементу ввода. (По умолчанию: «ac_input»).
resultsClass – класс для UL, который будет содержать элементы результата (элементы LI). (По умолчанию: «ac_results»).
– класс для элемента ввода, в то время, когда происходит обработка данных на сервере. (По умолчанию: «ac_loading»).lineSeparator – символ, который разделяет строки в данных, возвращаемых сервером. (По умолчанию: «\n»).
cellSeparator – символ, который разделяет «ячейки» в строках данных, возвращаемых сервером. (По умолчанию: «|»).
minChars – минимальное число символов, которое пользователь должен напечатать перед тем, как будет активизирван запрос. (По умолчанию: 1).
delay – задержка в миллисекундах. Если в течение этого времени пользователь не нажимал клавиши, активизируется запрос. Если используется локальный запрос (к данным, находящимся непосредственно в файле), задержку можно сильно уменьшить. Например до 40ms. (По умолчанию: 400).
cacheLength – число ответов от сервера, сохраняемых в кэше. Если установлено в 1 – кэширование данных отключено. Никогда не устанавливайте меньше единицы. (По умолчанию: 1).
matchSubset – использовать ли кэш для уточнения запросов. Использование этой опции может сильно снизить нагрузку на сервер и увеличить производительность. Не забудьте при этом еще и установить для cacheLength значение побольше. Например 10. (По умолчанию: 1).
matchCase – использовать ли сравнение чувствительное к регистру символов (только если Вы используете кэширование). (По умолчанию: 0).
maxItemsToShow – ограничивает число результатов, которые будут показаны в выпадающем списке. Если набор данных содержит сотни элементов, может быть неудобно показывать весь список пользователю. Рекомендованное значение 10. (По умолчанию: -1).
extraParams – дополнительные параметры, которые могут быть переданы на сервер. Если Вы напишете {page:4}, то строка запроса к обработчику на сервере будет сформирована следующим образом: my_handler.php?q=foo&page=4 (По умолчанию: {}).
width – устанавливает ширину выпадающего списка. По умолчанию ширина выпадающего списка определена шириной элемента ввода. Однако, если ширина элемента ввода небольшая, а строки выпадающего списка содержат большое количество символов – эта опция вполне может пригодиться. (По умолчанию: 0).
selectFirst – если установить в true , то по нажатию клавиши Tab или Enter будет выбрано то значение, которое в данный момент установлено в элементе ввода. Если же имеется выбранный вручную («подсвеченный») результат из выпадающего списка, то будет выбран именно он. (По умолчанию: false).
selectOnly – если установить в true и в выпадающем списке только одно значение, оно будет выбрано по нажатию клавиши Tab или Enter, даже если этот пункт не был выбран пользователем с помощью клавиатуры или указателя мыши. Заметьте, что эта опция отменяет действие опции selectFirst . (По умолчанию: false).
formatItem – JavaScript функция, которая поможет обеспечить дополнительную разметку элементов выпадающего списка. Функция будет вызываться для каждого элемента LI . Возвращаемые от сервера данные могут быть отображены в элементах LI выпадающего списка (см. второй пример). Принимает три параметра: строка результата, позиция строки в списке результатов, общее число элементов в списке результатов. (По умолчанию: none).
onItemSelect – JavaScript функция, которая будет вызвана, когда элемент списка выбран. Принимает единственный параметр – выбранный элемент LI . Выбранный элемент будет иметь дополнительный атрибут «extra», значением которого будет являться массив всех ячеек строки, которая была получена в качестве ответа от сервера. (По умолчанию: none).
Последние две опции весьма важны, если Вы хотите сделать действительно удобный и полезный элемент интерфейса, поэтому приведу примеры.
Function liFormat (row, i, num) { var result = row + "" + row + " тыс.чел."; return result; }
В опции formatItem мы определили имя вызываемой функции – liFormat , а сама функция просто формирует строку, которая будет вставлена в соответствующий элемент LI . Строка содержит название поселка и элемент em , в который выводится количество проживающих там, в тысячах человек. Элемент em имеет класс qnt , с помощью которого, используя CSS , мы сдвигаем этот элемент вправо, немного уменьшаем размер шрифта и делаем сам шрифт зеленого цвета.
Следующий пример для опции onItemSelect :
Function selectItem(li) { if(li == null) var sValue = "Ничего не выбрано!"; if(!!li.extra) var sValue = li.extra; else var sValue = li.selectValue; alert("Выбрана запись с ID: " + sValue); }
Здесь видно как можно работать со значениями атрибута «extra» выбранного элемента LI . В примере мы выводим в alert значение идентификатора для записи из нашей тестовой базы.
Нам осталось только разобрать те действия, которые будут выполняться на стороне сервера. Как Вы наверное помните, мы выбрали для этого PHP . Вспомним также, что на сервер передается GET-запрос с параметром q , содержащим уже введенные пользователем символы. Сам код Вы сможете посмотреть, скачав файл примера.
Весь код мы будем выполнять только в случае существования XMLHttpRequest , только если передан GET-запрос с параметром q . Для примера используется текстовый файл, в котором содержится база данных. Вот фрагмент этого файла:
1:Пашковский:Краснодарский край:43,0 2:Горячеводский:Ставропольский край:34,4 3:Калинино:Краснодарский край:34,1 4:Приволжский:Саратовская область:32,0 . . . . . . . . . . . . . . . . . . . 268:Залари:Иркутская область:10,0 269:Октябрьский:Пермский край:10,0 270:Ишеевка:Ульяновская область:10,0 271:Жешарт:Республика Коми:10,0 272:Прохоровка:Белгородская область:10,0
Мы читаем этот файл в массив, а затем в цикле перебираем все строки, в свою очередь разбивая каждую из них в массив, к элементу под номером один (название поселка) которого обращаемся для поиска соответствия с переданным GET-запросом. Если соответствие будет найдена выводим информацию, правда в несколько ином порядке, чем она хранилась в файле.
Такой подход выбран во-первых, потому что это пример, который должен быть очень просто воспроизведен на любом другом сайте, и во-вторых, чтобы при очень небольшом объеме данных дать почувствовать тот момент, когда запрос выполняется.
Вот собственно и все, обращу разве Ваше внимание на то, что для работы со строками использую.
Последнее обновление: 1.11.2015
Виджет autocomplete предназначен для создания специальных полей ввода с функцией автозаполнения:
В качестве источника автозаполнения указываем какой-нибудь массив и потом применяем виджет.
Подключение виджета к внешнему источникуВ предыдущем примере источник для списка автозаполнения задавался локально. Однако мы можем также динамически подключаться к какому-нибудь скрипту на сервере, который бы нам возвращал список вариантов для автозаполнения. В нашем случае это будет скрипт php. Пусть он будет выглядеть следующим образом:
Выходная переменная $output содержит весь список в формате json. В реальности, конечно, все элементы списка, скорее всего, будут извлекаться из БД, но я для простоты упростил пример.
По сути каждый элемент списка - это объект, у которого определены два свойства: label (отображаемая метка) и value (само значение). В данном случае оба свойства по значению совпадают.
На стороне клиента прием мог бы выглядеть следующим образом:
$("input#lang").autocomplete({ source: function(request,response) { $.getJSON("json.php", { filter: $("input#lang").val() }, function(data){ var suggestions = ; // массив для хранения результатов $.each(data, function(key, val) { suggestions.push(val.value); // добавляем все элементы }); response(suggestions); }); } });
Таким образом, мы динамически получаем введенные в поле ввода символы и передаем их в запросе на сервер. На сервере эти символы используются в качестве фильтра, а в ответ клиенту возвращается набор отфильтрованных записей.
Стилизация виджетаПри применении виджета к элементу input к данному элементу добавляется класс ui-autocomplete-input . А область списка автозаполения представляет собой список ul:
Изменив стили соответствующих классов, мы можем настроить отображение списка:
li.ui-menu-item { font-size: 12px; font-faminy: Verdana; } $(function(){ var langs = ["Java", "JavaScript", "VisualBasic", "PHP", "Pascal"] ; $("input#lang").autocomplete({ source: langs }); });
Свойства виджетаВиджет имеет следующие свойства:
appendTo: указывает, какой элемент будет включать список для автозаполенния:
$(function(){ var langs = ["Java", "JavaScript", "VisualBasic", "PHP", "Pascal"] ; $("input#lang").autocomplete({ appendTo: "#langsList", source: langs }); });
autoFocus: при установке данного свойства в true выделяется первый элемент списка автозаполнения. По умолчанию свойство имеет значение false .
delay: указывает в миллисекундах время задержки до показа списка автозаполенния ($("#langs").autocomplete({ delay: 500 });). По умолчанию данное свойство равно 300
disabled: при установке у свойства значения true отключает виджет. По умолчанию имеет значение false .
minLength: указывает на минимальное количество символов, которое должен ввести пользователь, чтобы отобразился список автозаполнения: $("#langs").autocomplete({ minLength: 0 }); . По умолчанию данное свойство имеет значение 1.
position: используя данное свойство, можно задать положение списка на странице. Объект, с помощью которого можно задать положение, использует ряд опций, список которых можно найти на странице https://api.jqueryui.com/position/ . По умолчанию свойство имеет значение { my: "left top", at: "left bottom", collision: "none" } . Опция my указывает на позицию элемента списка автозаполнения, относительно которой идет выравнивание с элементом ввода. То есть left top выравнивает относительно левого верхнего угла. Опция at указывает уже позицию элемента ввода, относительно которой будет выравниваться список автозаполнения. Опция collision дополнительно настраивает отображение списка.
Мы можем изменить начальные параметры, например, $("input#lang").autocomplete({ position: { my: "right top", at: "right bottom", collision: "fit" }, source: langs });
source: задает источник для автозаполнения. Это может быть массив, который можно задать в качестве внешнего массива или прямо при свойстве: $("input#lang").autocomplete({ source: ["Java", "JavaScript", "VisualBasic", "PHP", "Pascal"]});
Виджет autocomplete имеет следующие методы:
autocomplete("close"): закрывает список ($("#lang").autocomplete("close");)
autocomplete("disable"): отключает виджет
autocomplete("enable"): подключает виджет автозаполнения
autocomplete("destroy"): удаляет функциональность автозаполнения у элемента
autocomplete("widget"): возвращает объект jQuery, представляющий виджет (var widget = $("#lang").autocomplete("widget");)
autocomplete("option"): позволяет получить или установить значения свойств виджета. Например, установим и получим значение свойства collapsible:
Var langs = ["Java", "JavaScript", "VisualBasic", "PHP", "Pascal"] ; $("input#lang").autocomplete({ source: langs}); $("input#lang").autocomplete("option", { autoFocus: true });
autocomplete("search", "value"): производит поиск по списку так с учетом значения value. Например, метод $("#lang").autocomplete("search", "i"); будет эквивалентен действию ввода символа "i" в текстовое поле. И затем буду отображены все элементы списка, в которых присутствует символ "i"
С помощью обработки следующих событий виджета мы можем произвести определенные действия в ответ на действия пользователя:
change(event, ui) : событие возникает после изменения выбранного элемента.
Параметр event содержит объект события, а параметр ui представляет объект, который содержит информацию о выбранном элементе:
Var langs = ["Java", "JavaScript", "VisualBasic", "PHP", "Pascal"] ; $("input#lang").autocomplete({ source: langs}); $("input#lang").autocomplete({ change: function(event, ui) { console.log(ui.item.value); } });
Используя свойство ui.item , мы получаем выбранный элемент. Элемент определен в виде объекта {label, value}, поэому, чтобы получить значение выбранного элемента, используем свойство value
close(event, ui) : возникает при закрытии списка автозаполнения
create(event, ui) : возникает при создании виджета
focus(event, ui) : возникает при передаче фокуса элементу
open(event, ui) : возникает при открытии или отображении списка автозаполнения
response(event, ui) : возникает после завершения поиска, но перед тем, как список результатов автозаполнения появится на экране. Чтобы получить все результаты списка, надо использовать объект ui.content , который представляет массив:
Var langs = ["Java", "JavaScript", "VisualBasic", "PHP", "Pascal"] ;
$("input#lang").autocomplete({ source: langs});
$("input#lang").autocomplete({
response: function(event, ui) {
for (var i = 0; i
Загрузка...
