Expromptum
Expromptum — библиотека JavaScript, предназначенная для расширения функциональности работы элементов в HTML.
Использует библиотеку jQuery для работы с элементами (версии 1.8.0 и выше).
Чтобы использовать библиотеку надо подключить ее к странице содержащей соответствующий HTML и выполнить инициализацию.
Пример
... Enter a valid email address. ...
Коротко
Контролы
Тип контрола определяется CSS-селектором или значением свойства type
в атрибуте data-xp
. Для остальных свойств контрола указаны противоположные или отличные от используемых по умолчанию значения.
<strong for="sheet_2">Sheet 2</strong>
<div class="sheet" id="sheet_1" data-xp="type: 'sheet'"></div>
<div class="sheet selected" id="sheet_2" data-xp="type: 'sheet'"></div>
Без указания зависимости computed, в этом контроле мало смысла.
Кнопки ```html
Button
Button
<div><a href="#controls.submit">Кнопка отправки</a></div>
```html
<input type="submit" data-xp="type: 'submit'"/>
Поля для ввода ```html ``` ```html ``` ```html ``` ```html ``` ```html ``` ```html ``` ```html ``` ```html ``` ```html ``` ```html ``` ```html ```
Выбор значений ```html ... ``` ```html ... ``` ```html
Зависимости
Для получения значений контролов в выражениях используются CSS-селекторы по атрибутам (например, [name=some]
) и [this]
для данного контрола.
Повторения
... + −
Инициализация
Возвращает список expromptum контролов.
expromptum()
- Проинициализируются все элементы с атрибутом
data-xp
или подходящие под CSS-селекторы по умолчанию, заданные в контролах.
expromptum(selector[, expromptum object | jQuery object])
- Проинициализируются все элементы подходящие под CSS-селектор в первом параметре. Если передан и второй параметр, то селектор будет применен в контексте его элемента.
expromptum(element | elements array | jQuery object)
- Проинициализируются элементы переданные в качестве параметра.
Список объектов
Возвращает массив объектов с дополнительными методами, позволяющими добавлять в него только уникальные экземпляры объектов.
new expromptum.list(array)
Методы
.append(object)
- Проверяет нет ли переданного объекта в массиве и если нет, добавляет его в конец. Возвращает список объектов.
.remove(object)
- Ищет переданный объект в массиве и если находит, удаляет его оттуда. Возвращает список объектов.
.each(function())
- Выполняет переданную функцию для каждого объекта в списке. Если функция вернет значение
false
, то перебор объектов завершится. Возвращает список объектов.
.first([function()])
- Возвращает первый объект в списке или значение
null
, если список пустой. Может выполнить переданную функцию для первого объекта.
.last([function()])
- Возвращает последний объект в списке или значение
null
, если список пустой. Может выполнить переданную функцию для последнего объекта.
.eq(index[, function()])
- Возвращает объект с переданным индексом в списке или значение
null
, если такового нет. Может выполнить переданную функцию для найденного объекта.
Абстрактный класс
Используется в качестве базового класса для всех остальных.
Класс expromptum.base
Методы
.init(params)
- Конструктор объекта.
.destroy([function()[, remove]])
- Деструктор объекта. При передачи в параметре функции, добавляет ее в список. При передаче значения
true
во втором параметре, удаляет функцию из списка. При вызове метода без параметров — выполняет функции в списке. Возвращает объект.
.change([function()[, remove]])
- Обработчик изменения значения объекта. При передачи в параметре функции, добавляет ее в список. При передаче значения
true
во втором параметре, удаляет функцию из списка. При вызове метода без параметров — выполняет функции в списке. Возвращает объект.
.param(name[, value])
- Чтение и запись свойств объекта. Возвращает значение указанного свойства.
Контролы
При инициализации контрола тип определяется по значению параметра type
в атрибуте data-xp
или по селектору типа.
Пример 1
Пример 2
Создание нового контрола
Пример 1
Поле с проверкой на соответствие выражению.
xPcontrols;
Пример 2
Слайдер для числового значения с использованием виджета Slider.
xPcontrols;
Пример 3
Слайдер для набора значений с использованием виджета Slider.
xPcontrols;
Пример 4
Поле с редактированием через Реформатор.
xPcontrols;
Пример 5
Поля для ввода даты с использованием виджета Datepicker.
xPcontrols; xPcontrols;
Абстрактный контрол
- Тип
_item
- Базовый тип
xP.base
Используется в качестве базового класса для классов контролов.
Свойства
.$element
- jQuery-объект, указывающий на основной элемент контрола.
.$container
- jQuery-объект, указывающий на элемент, найденный по CSS-селектору из свойства
container_selector
или на основной элемент.
.disabled
- Логическое значение
true
илиfalse
, в зависимости от доступности контрола.
.container_selector
- CSS-селектор по которому находится элемент контейнер.
.container_disabled_class = 'disabled'
- Имя CSS-класса, назначаемое элементу контейнеру в зависимости от доступности контрола.
.autofocus
- Логическое значение
true
илиfalse
, по которому определяется необходимость перехода фокуса на данный контрол при инициализации.
Методы
.remove()
- Удаляет контрол, в том числе, и все его элементы из DOM-дерева.
.parent()
- Возвращает родительский контрол.
.root()
- Возвращает корневой контрол.
.val([value])
- Чтение и запись значения контрола.
.disable([disabled])
- Определяет доступность контрола. Возвращает данный контрол.
HTML
- Тип
html
- Базовый тип
_item
- Селектор элемента
.xp_html
Используется для вывода в HTML значений других контролов через зависимость computed
.
Пример
+ - * / =
Абстрактный родитель
- Тип
_parent
- Базовый тип
_item
- Селектор элемента
.xp
Используется в качестве базового класса для всех контролов, которые могут выступать родителем для других.
Методы
.children()
- Возвращает список контролов, находящихся внутри данного.
.val([object | objects array])
- Позволяет принимать в качестве значения объект или массив объектов. Значения свойств объекта будут устанавливаться в качестве значений для одноименных контролов, находящихся внутри данного.
Форма
- Тип
form
- Базовый тип
_parent
- Селектор элемента
form
Свойства
.completed_on_required = true
- Логическое значение
true
илиfalse
, по которому определяется считается ли форма готовой для отправки при незаполненных обязательных контролах.
.completed_on_valid_required = true
- Логическое значение
true
илиfalse
, по которому определяется считается ли форма готовой для отправки при неправильно заполненных обязательных контролах.
.completed_on_valid = false
- Логическое значение
true
илиfalse
, по которому определяется считается ли форма готовой для отправки при неправильно заполненных контролах.
.completed_on_changed = false
- Логическое значение
true
илиfalse
, по которому определяется считается ли форма готовой для отправки если не менялось значение хотя бы одного из контролов.
.locked = false
- Логическое значение
true
илиfalse
, по которому определяется возможность отправки формы. Можно использовать для калькуляторов или форм работающих через ajax.
Методы
.submit([function()[, remove]])
- Обработчик события отправки формы.
- При передачи в параметре функции, добавляет ее в список. При передаче значения
true
во втором параметре, удаляет функцию из списка. Возвращает контрол. - При вызове метода без параметров — выполняет функции в списке. Возвращает логическое значение
true
илиfalse
.
- При передачи в параметре функции, добавляет ее в список. При передаче значения
.uncompleted()
- Проверяет готовность формы. Если готова, возвращает
null
. Иначе — строку в которой указана причина (required
,invalid_required
,invalid
,unchanged
). Получить список конфликтных контролов, можно через метод._param('зависимость')
.
Пример
Name Email Message
Группа полей, листы
- Тип
fields
- Базовый тип
_parent
- Селектор элемента
fieldset, .fields, .sheets
Свойства
.name
- Имя группы полей. Необходимо для получения и присвоения значений при использовании повторений у данного контрола.
.$label
- jQuery-объект, указывающий на элемент с атрибутом
for
равнымid
основного элемента данного контрола.
Методы
.count()
- Возвращает количество находящихся внутри данного контролов с непустыми значениями.
Лист
- Тип
sheet
- Базовый тип
fields
- Селектор элемента
.sheet
Свойства
.$label
- jQuery-объект, указывающий на элемент с атрибутом
for
равнымid
основного элемента данного контрола.
.selected_class = 'selected'
- Имя CSS-класса, назначаемое элементам отмеченного контрола (контейнеру и подписи).
.unselected_class = 'unselected'
- Имя CSS-класса, назначаемое элементам не отмеченных контролов (контейнерам и подписям).
Методы
.select([select])
- Отмечает контрол. Возвращает данный контрол.
Сворачиваемая панель
- Тип
foldable
- Базовый тип
fields
- Селектор элемента
.foldable
Свойства
.duration = 200
- Продолжительность сворачивания (разворачивания) контрола в миллисекундах.
.folded_class = 'folded'
- Имя CSS-класса, назначаемое элементам свернутого контрола (контейнеру и подписи).
.unfolded_class = 'unfolded'
- Имя CSS-класса, назначаемое элементам не свернутого контрола (контейнеру и подписи).
Методы
.fold([fold])
- Сворачивает или разворачивает (в случае
fold = false
) контрол. Возвращает данный контрол.
Абстрактное поле
- Тип
_field
- Базовый тип
_parent
- Селектор элемента
input
Селектор контейнера.field
Свойства
.$label
- jQuery-объект, указывающий на элемент с атрибутом
for
равнымid
основного элемента данного контрола.
.allow_chars_pattern
- RegExp, содержащий разрешенные для ввода с клавиатуры символы.
.container_blured_class = 'blured'
- Имя CSS-класса, назначаемое элементу контейнера после того, как произойдет событие
blur
у основного элемента данного контрола.
Методы
.val([value])
- Чтение и запись значения контрола.
Строковое поле
- Тип
string
- Базовый тип
_field
- Селектор элемента
input[type=text], input:not([type])
Текстовое поле
- Тип
text
- Базовый тип
_field
- Селектор элемента
textarea
Скрытое поле
- Тип
hidden
- Базовый тип
_field
- Селектор элемента
input[type=hidden]
Файловое поле
- Тип
file
- Базовый тип
_field
- Селектор элемента
input[type=file]
Кнопка
- Тип
button
- Базовый тип
_parent
- Селектор элемента
input[type=button], button, .button
Кнопка отправки
- Тип
submit
- Базовый тип
_item
- Селектор элемента
input[type=submit], button[type=submit]
Выпадающий список
- Тип
select
- Базовый тип
_field
- Селектор элемента
select
Свойства
.hide_disabled_option = true
- Определяет видимость недоступных элементов. При значении
false
нужный результат будет только в тех браузерах, которые это поддерживают.
Методы
.disable([disabled[, values]])
- Определяет доступность контрола. Второй параметр может содержать одно или массив значений к которым нужно применить первый параметр. Возвращает данный контрол.
.append(values)
- Добавляет пункты выбора. Параметр может содержать одно или массив значений. Каждое из значений может быть: строкой, массивом (вида:
[значение для value, значение для подписи]
) или объектом (вида:{value: значение для value, label: значение для подписи}
). Возвращает данный контрол.
.remove()
- Удаляет все пункты выбора. Возвращает данный контрол.
Группа переключателей
- Тип
options
- Базовый тип
fields
- Селектор элемента
.options
Группирующий контрол, применяемый для назначения зависимостей на группу переключателей или включателей.
Абстрактный переключатель
- Тип
_option
- Базовый тип
_field
Селектор контейнера.option
Используется в качестве базового класса для контролов переключателей и включателей.
Свойства
.container_selector = '.option'
- CSS-селектор по которому находится элемент контейнер.
.selected = null
- Логическое значение
true
илиfalse
, по которому определяется отмечен данный контрол или нет.
.container_initial_selected_class = 'initial_selected'
- Имя CSS-класса, назначаемое элементу контейнеру если данный контрол был отмечен на момент инициализации.
.container_selected_class = 'selected'
- Имя CSS-класса, назначаемое элементу контейнеру если данный контрол отмечен.
Методы
.select([selected])
- Определяет отмечен контрол или нет.
.append(values)
- Добавляет пункты выбора. Параметр может содержать одно или массив значений. Каждое из значений может быть: строкой, массивом (вида:
[значение для value, значение для подписи]
) или объектом (вида:{value: значение для value, label: значение для подписи}
). Возвращает список добавленных контролов.
Переключатель
- Тип
radio
- Базовый тип
_option
- Селектор элемента
input[type=radio]
Включатель
- Тип
checkbox
- Базовый тип
_option
- Селектор элемента
input[type=checkbox]
Поле для эл. почты
- Тип
email
- Базовый тип
_field
- Селектор элемента
.email input, input.email
Поле для телефона
- Тип
phone
- Базовый тип
_field
- Селектор элемента
.phone input, input.phone
Абстрактное поле со скрытым полем
- Тип
_secret
- Базовый тип
_field
Используется в качестве базового класса для всех контролов, внешний вид которых требует создания альтернативных элементов для ввода данных.
Свойства
.$secret
- jQuery-объект, указывающий на на основной элемент контрола, который трансформирован в скрытый.
Поле для пароля
- Тип
password
- Базовый тип
_secret
- Селектор элемента
input[type=password]
Позволяет управлять видимостью введенных символов в поле для ввода пароля.
Свойства
.container_view_class = 'alt'
- Имя CSS-класса, назначаемое элементу контейнеру после нажатия на дополнительно созданный элемент управления.
.control_button_view_class = 'control_button_password_view'
- Имя CSS-класса, назначаемое элементу управления после нажатия на него.
.control_button_view_html = '<span class="control_button control_button_password"/>'
- HTML-код для создания элемента управления видом контрола.
Поле для числа
- Тип
number
- Базовый тип
_secret
- Селектор элемента
input.number, .number input
Позволяет вводить только числа и управлять значением с помощью стрелок на клавиатуре или созданных дополнительно элементов управления.
Свойства
.step = 1
- Шаг, на который будет меняться значение контрола.
.min = 1 - Number.MAX_VALUE
- Минимальное значение контрола.
.def = 0
- Значение по умолчанию, используемое в методах
inc
иdec
при пустомvalue
.
.max = Number.MAX_VALUE - 1
- Максимальное значение контрола.
.element_wrap_html = '<span class="number_control"/>'
- HTML-код обертки для созданного дополнительно элемента, через который будет осуществляться ввод данных пользователем.
.control_button_dec_html = '<span class="control_button control_button_dec"/>'
- HTML-код кнопки увеличения значения контрола.
.control_button_inc_html = '<span class="control_button control_button_inc"/>'
- HTML-код кнопки уменьшения значения контрола.
Методы
.inc()
- Увеличивает значения контрола. Возвращает данный контрол.
.dec()
- Уменьшает значения контрола. Возвращает данный контрол.
Поле для года и месяца
- Тип
datemonth
- Базовый тип
_field
- Селектор элемента
input.datemonth, .datemonth input
Методы
.date([date])
- Чтение и запись даты в качестве значения контрола.
Пример
Поле для даты
- Тип
date
- Базовый тип
datemonth
- Селектор элемента
input.date, .date input
Пример
Поле для даты и времени
- Тип
datetime
- Базовый тип
date
- Селектор элемента
input.datetime, .datetime input
Пример
Комбобокс
- Тип
combobox
- Базовый тип
string
- Селектор элемента
.combobox input, input.combobox, input[list]
Ввод данных с возможность выбора значений из выпадающего списка.
Свойства
.search_from_start = true
- Логическое значение true или false, по которому определяется каким образом фильтровать данные в списке — при совпадении с началом строки или в любом ее фрагменте.
.case_sensitive = false
- Логическое значение true или false, по которому определяется каким образом фильтровать данные в списке — с учетом регистра или без.
.[list](#controls._combolist)
- Контрол, указывающий на список значений.
Список для комбобокса
- Тип
_combolist
- Базовый тип
select
Вспомогательный контрол для комбобокса.
Методы
.show()
- Показывает список. Возвращает данный контрол.
.hide()
- Скрывает список. Возвращает данный контрол.
Зависимости
Абстрактная зависимость
- Тип
_item
- Базовый тип
expromptum.base
Используется в качестве базового класса для всех зависисмостей.
Свойства
.to='[this]'
- Свойство, указывающее на контрол к которому применяется зависисмость.
Управление атрибутом класса
- Тип
classed
- Базовый тип
_item
Свойства
.on
- Логическое выражение, в случае выполнения которого, элементу контейнеру контрола указанного в свойстве
to
, будет назначено имя CSS-класса из свойстваdo
.
.do
- Имя CSS-класса.
Пример 1
Пример 2
Вычисляемое значение
- Тип
computed
- Базовый тип
_item
Свойства
.on
- Выражение, результат которого будет присвоен в качестве значения (через метод
.val(значение)
) контролу, указанному в свойствеto
.
.do
- Имя свойства. Если указано значение, то результат выражения будет присвоен свойству (через метод
.param(свойство, значение)
) контрола, указанного в свойствеto
.
Пример 1
+ - * / =
Доступность
- Тип
enabled
- Базовый тип
_item
Свойства
.on
- Логическое выражение, в случае невыполнения которого, контрол, указанный в свойстве
to
, будет недоступен для работы (disabled
).
Пример
Доступность при полном заполнении
- Тип
enabled_on_completed
- Базовый тип
_item
В зависимости от выполнения условий на обязательность и правильность заполнения формы, делает контрол доступным или недоступным для работы (disabled
).
Пример
Абстрактная зависимость на полное заполнение
- Тип
_rooted
- Базовый тип
_item
Используется в качестве базового класса для остальных зависисмостей, которые могут быть задействованы в условиях полного заполнения формы.
Обязательность заполнения
- Тип
required
- Базовый тип
_rooted
Свойства
.on
- Логическое значение true. Или логическое выражение, в случае выполнения которого, контрол указанный в свойстве
to
, становится обязательным для заполнения.
.container_required_class = 'required'
- Имя CSS-класса, назначаемое элементу контейнеру контрола, в случае, если он не заполнен.
.container_unrequired_class = 'unrequired'
- Имя CSS-класса, назначаемое элементу контейнеру контрола, в случае, если он заполнен.
Пример 1
Пример 2
Соответствие выражению
- Тип
valid
- Базовый тип
_rooted
Свойства
.on
- Логическое выражение, от результата работы которого зависит считается ли данный контрол правильно заполненным.
.container_valid_class = 'valid'
- Имя CSS-класса, назначаемое элементу контейнеру контрола, в случае, если выражение в свойстве
on
возвращаетtrue
.
.container_invalid_class = 'invalid'
- Имя CSS-класса, назначаемое элементу контейнеру контрола, в случае, если выражение в свойстве
on
возвращаетfalse
.
Пример
Изменение
- Тип
changed
- Базовый тип
_rooted
Данная зависимость назначается всем контролам при инициализации.
Свойства
.container_changed_class = 'changed'
- Имя CSS-класса, назначаемое элементу контейнеру контрола, в случае, если его значение было изменено.
Повторения
Свойства
.max = 300
- Максимальное число повторений, по достижении которого, перестает быть доступным контрол добавления.
.min = 1
- Минимальное число повторений, по достижении которого, перестает быть доступным контрол удаления.
.reset
- Логическое значение true сбрасывает значения добавляемых контролов. Для каждого из контролов можно задавать свое соответствующее значение в свойстве
reset_on_repeat
.
.template
- Логическое значение true определяет данный контрол в качестве шаблона для добавляемых контролов.
Пример 1
+ −
Концепция работы с библиотекой
Все значения свойств у основных объектов библиотеки (контролов, зависимостей и повторений) устанавливаются через параметры при инициализации или через вызов метода .param('имя', значение)
. Получение значений возможно и через прямое обращение к свойству.
Большинство методов основных объектов библиотеки возвращают сам объект.
Методы и свойства названия которых начинаются с символа подчеркивания, предназначены только для использования внутри библиотеки. Если же есть необходимости обратится к таким свойствам, это следует делать через вызов метода ._param('имя', значение)
.
Названия свойств, значениями которых являются jQuery-объекты, начинаются с символа доллара.
Режим диагностики
Для диагностики работы в адресной строке можно передать параметр xP=значение
. При этом в консоль браузера будут выводится все обнаруженные ошибки и соответствующие значению сообщения:
controls
— инициализация контролов;
submit
— отправка формы;
dependencies
— инициализация и обработка всех зависимостей;
classed
, enabled
, enabled_on_completed
, required
, valid
, changed
— обработка зависимостей данного типа;
repeats
— инициализация повторений.