Поля ввода со списком выбора - combobox

Полный список свойств и функций, а так же общие правила их использования, см. здесь: Краткий обзор и правила, список функций VcorpJS.

Комбинированный список combobox - это блочный HTML - элемент, который содержит одновременно поле ввода и анимированный список выбора.

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

Плагин использует CSS-классы .pb_combobox и другие, начинающиеся с ".pb_cb_" для вложенных элементов.

HTML - элементы combobox могут содержаться в HTML-коде или создаваться функцией .cbNew(...)
Для поиска и инициализации полей combobox, находящихся в виде HTML-кода, предназначена функция .cbUpdate(...)
Обновление выпадающего списка любого комбобокса выполняет функция .cbChange(descriptor,...)
Прочитать текущее значение из текстового поля input любого комбобокса позволяет функция .cbGet(descriptor)
Задать общую callback-функцию можно через функцию .cbCallback(handler) (см. правила для callback - функций).

Каждому HTML-объекту с классом pb_combobox при его инициализации и работе с ним, присваиваются уникальные id для каждого внутреннего HTML-объекта.

Если тот или иной combobox отработал и становится не нужен, его можно спокойно удалить или затереть в HTML-коде родителя, это корректная операция, VcorpJS следит за внутренними дескрипторами combobox и безопасно устанавливает обработчики событий и внутренние параметры каждого combobox (свойства .pb_EV и .pb_CB).

.cbUpdate( [ handler ] , [ parentNode ] , [ selector ] , [ time ] , [ step ] )

Функция ищет все HTML - элементы с классом pb_combobox внутри указанного родителя parentNode (или по всему документу) и инициализирует их, если они ещё не были инициализированы ранее.

handler - общая callback - функция, вызываемая для всех найденных комбобоксов, отдельное описание ниже по тексту.

parentNode - ссылка на родительский HTML-объект или его текстовый id (в котором будет происходить поиск)
Если родительский объект не указан или не найден, то document (VcorpJS.D).

selector - текстовый селектор для уточнения поиска HTML-объектов, вложенных в parentNode,
работает примерно так: parentNode.querySelectorAll( selector + " .pb_combobox" );
Селектор составляется по правилам CSS - имена классов пишутся с точкой, идентификаторы через решётку #, допустимы каскадные перечисления классов и т.д.

time - время анимации раскрытия списка выбора в миллисекундах (не менее 100, по-умолчанию 100). Задаётся для всех комбобоксов.

step - шаг анимации списка выбора в миллисекундах (не менее 20, по-умолчанию 20). Задаётся для всех комбобоксов.

Функция возвращает массив с номерами дескрипторов для новых найденных и инициализированных комбобоксов.
Массив может быть пустым [], в него попадают только те комбобоксы, которые не были инициализированы ранее.
Чистка освободившихся дескрипторов происходит автоматически (если HTML-объекты удаляются), поэтому в возвращаемом массиве номера дескрипторов могут быть непоследовательными, но всегда по возрастанию.

Функцию VcorpJS.cbUpdate() можно вызывать сколько угодно раз.
При каждом новом вызове, если указан handler, он принудительно меняется для найденных комбобоксов.
При каждом вызове происходит новый поиск - согласно указанным parentNode и selector,
если какой-либо из найденных комбобоксов ещё не был инициализирован, то навешиваются обработчики на различные вложенные элементы, а вложенное поле ввода input получает системный идентификатор в свойстве id (поэтому бесполезно заранее указывать id у вложенных input).
Не указывайте заранее id у обязательных элементов combobox (может возникнуть ошибка инициализации). Если хотите уникальности в исходном HTML-коде, включите скрытые блочные элементы со своим id и задайте для них CSS-правила.

.cbNew( [ parentNode ] , [ inputValue ] , [ arrayValues ] , [ handler ] , [ maxLength ] , [ time ] , [ step ] )

Функция создаёт новый combobox и инициализирует его, присваивая свободный дескриптор новому HTML-элементу (комбобоксу класса pb_combobox).

parentNode - ссылка на родительский HTML-объект или его текстовый id
Если parentNode существует, то его содержимое полностью перезаписывается (через .innerHTML) созданным HTML-элементом класса pb_combobox

inputValue - начальное строковое значение для вложенного текстового поля input

arrayValues - массив строк со значениями (может содержать корректные HTML-строки) для выпадающего списка выбора.

handler - персональная callback - функция, вызываемая только для вновь созданного комбобокса, отдельное описание ниже по тексту.
Персональная callback - функция будет заменена на общую при последующем вызове .cbUpdate(), если комбобокс будет найден по условию поиска.

maxLength - числовое значение атрибута maxLength для создаваемого поля input

time и step - соответственно время и шаг анимации раскрытия списка выбора в миллисекундах. Задаются для всех комбобоксов.

Функция возвращает дескриптор, закреплённый за вновь созданным комбобоксом.

.cbChange( [ descriptor ] , [ arrayValues ] , [ handler ] , [ maxLength ] , [ status ] , [ time ] , [ step ] )

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

descriptor - числовой дескриптор комбобокса или ссылка на HTML-объект комбобокса или его текстовый id

arrayValues - массив строк со значениями (может содержать корректные HTML-строки) для выпадающего списка выбора.

handler - персональная callback - функция, вызываемая только для комбобокса descriptor, отдельное описание ниже по тексту.
Персональная callback - функция будет заменена на общую при последующем вызове .cbUpdate(), если комбобокс будет найден по условию поиска.

maxLength - числовое значение атрибута maxLength для вложенного поля input

status - внешний вид и поведение раскрывающегося списка вариантов быстрого выбора.
Число: если 1, то список раскрывается; если 2, то закрывается; иначе остаётся как был. Анимация.

Функция возвращает true или false - если указанный комбобокс не найден или некорректен.

.cbGet( descriptor )

Функция возвращает текстовое содержимое поля input указанного комбобокса, или false если он не найден или некорректен.

descriptor - числовой дескриптор комбобокса или ссылка на HTML-объект комбобокса или его текстовый id

Общая callback - функция для всех combobox

.cbCallback( handler )

Установка общей callback - функции для всех комбобоксов веб-страницы
(дополнительно см. правила для callback - функций).

handler может быть текстовой строкой содержимого функции - в этом случае имена передаваемых параметров следующие:
e, desc, obj_parent, id_combobox, id_img, id_select, id_input, arrayValues, inputValue, typeEvent

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

Функция вызывается как: function(e, desc, obj_parent, id_combobox, id_img, id_select, id_input, arrayValues, inputValue, typeEvent); где:

this - ссылка на HTML-объект класса pb_combobox
e - объект event текущего события (для поля ввода - keyup, keypress, keydown, change; для строки списка - mousedown)
desc - числовой дескриптор комбобокса (от 1)
obj_parent - ссылка на родительский объект комбобокса parentNode
id_combobox - свойство id комбобокса (HTML-элемента класса pb_combobox)
id_img - свойство id вложенного HTML-элемента класса .pb_cb_image
id_select - свойство id вложенного HTML-элемента класса .pb_cb_select
id_input - свойство id вложенного HTML-элемента input
arrayValues - массив с текстовыми HTML-строками списка быстрого выбора (HTML-содержимое элементов класса .pb_cb_option)
inputValue - текущее строковое значение вложенного поля input
typeEvent - значение "input" или "option" (если событие mousedown)

Почему так много параметров? На всякий случай, для динамичного управления комбобоксом, а именно:

callback - функция может вернуть true (или 1) - в этом случае содержимое выпадающего списка мгновенно заменяется значениями из массива arrayValues, а поскольку этот массив передаётся по ссылке, то обновлять список можно из callback-функции, меняя количество элементов и их содержимое.
Нужно быть внимательным, чтобы не присвоить новую ссылку на массив локальной переменной.
Лучше для надёжности воспользоваться функцией .cbChange(), но можно и быстро поменять содержимое массива без вызова этой функции, вернув true,
разумеется, можно контролировать и менять содержимое поля ввода input, да и остальные части комбобокса.

Визуальный пример комбинированного списка выбора:

Для простоты и наглядности примера, combobox сделан как HTML-фрагмент с последующей инициализацией .cbUpdate()

<div class="pb_combobox">
<input
type="text" value="0" maxlength="30"
placeholder="введите что-нибудь"
/>
<div class="pb_cb_image">▼</div>
<div class="pb_cb_select">
<div class="pb_cb_option">Строка 1</div>
<div class="pb_cb_option">Строка 2</div>
<div class="pb_cb_option">Строка 3</div>
<div class="pb_cb_option">Строка 4</div>
<div class="pb_cb_option">5 5 5 5 5</div>
</div>
</div>

<script type="text/javascript">
/* Инциализация combobox */
VcorpJS.ready( function(e) { VcorpJS.cbUpdate(); } );
/* Или так тоже можно */
VcorpJS.ready( "VcorpJS.cbUpdate()" );
</script>

▼

Строка 1

Строка 2

Строка 3

Строка 4

5 5 5 5 5

Так же см. combobox в форме обратной связи.

Плагин использует CSS-классы :
.pb_combobox и другие для вложенных
элементов, начинающиеся с ".pb_cb_"

Для навигации по всем страницам этого раздела сайта используйте пиктограмму или ссылку Навигация в верхней строке навигации.