Expromptum js library
JavaScript CSS
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
examples Update address book example Jun 25, 2014
README.md Update README.md May 19, 2015
bower.json
expromptum.css Update expromptum.css Oct 12, 2016
expromptum.js
expromptum.min.js Fix wrong wrap options in selectus Oct 13, 2016
expromptum.png

README.md

Expromptum

Expromptum — библиотека JavaScript, предназначенная для расширения функциональности работы элементов в HTML.

Использует библиотеку jQuery для работы с элементами (версии 1.8.0 и выше).

Чтобы использовать библиотеку надо подключить ее к странице содержащей соответствующий HTML и выполнить инициализацию.

Пример
<script src="jquery.js"></script>
<script src="expromptum.js"></script>
<style>
    .field {position: relative;}
    .show_on_blured_and_invalid {display: none;}
    .blured.invalid .show_on_blured_and_invalid {display: block; position: absolute; left: 0; bottom: -3em;}
</style>
...
<form method="post">
    <span class="field">
        <input name="email" placeholder="Email" data-xp="type: 'email', required: true"/>

        <span class="show_on_blured_and_invalid">Enter a&nbsp;valid email address.</span>
    </span>

    <span class="field">
        <input name="password" placeholder="Password" type="password" data-xp="required: true"/>
    </span>

    <input type="submit" value="Sign in" data-xp="enabled_on_completed: true"/>
</form>
...
<script>
    expromptum();
</script>

Коротко

Контролы

Тип контрола определяется CSS-селектором или значением свойства type в атрибуте data-xp. Для остальных свойств контрола указаны противоположные или отличные от используемых по умолчанию значения.

<form data-xp="
    type: 'form',
    completed_on_required: false,
    completed_on_valid_required: false,
    completed_on_valid: true,
    completed_on_changed: true
"></form>
<div class="fields" data-xp="type: 'fields'"></div>
<strong for="foldable_1">Panel 1</strong>
<div class="foldable" id="foldable_1" data-xp="type: 'foldable', unfolded: true"></div>
<div class="sheets" data-xp="type: 'fields'">
    <strong for="sheet_1">Sheet 1</strong>

    <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>
</div>
<span class="xp_html" data-xp="type: 'html', computed: '[name=some]' + '!'"></span>

Без указания зависимости computed, в этом контроле мало смысла.

Кнопки

<input type="button" value="Button" data-xp="type: 'button'"/>

<button data-xp="type: 'button'">Button</button>

<span class="button" data-xp="type: 'button'">Button</span>
<input type="submit" data-xp="type: 'submit'"/>

Поля для ввода

<input data-xp="type: 'string'"/>
<textarea data-xp="type: 'text'"></textarea>
<input type="hidden" data-xp="type: 'hidden'"/>
<input type="file" data-xp="type: 'file'"/>
<input type="password" data-xp="type: 'password'"/>
<input class="number" data-xp="
    type: 'number',
    min: 0,
    max: 10,
    step: 2,
    def: 0
"/>
<input class="datemonth" data-xp="type: 'datemonth'"/>
<input class="date" data-xp="type: 'date'"/>
<input class="datetime" data-xp="type: 'datetime'"/>
<input class="email" data-xp="type: 'email'"/>
<input class="phone" data-xp="type: 'phone'"/>

Выбор значений

<select data-xp="type: 'select', hide_disabled_option: false">...</select>
<input class="combobox" list="combobox_1" data-xp="type: 'combobox'"/>
<select id="combobox_1">...</select>
<div class="options" data-xp="type: 'options'">
    <input type="radio"/>
    <input type="radio"/>
</div>

<div class="options" data-xp="type: 'options'">
    <input type="checkbox"/>
</div>
<div class="selectus" data-xp="type: 'selectus'">
    <input type="radio" id="r1"/>
    <label for="r1">Item 1</label>
    <input type="radio" id="r2"/>
    <label for="r2">Item 2</label>
</div>

<div class="selectus" data-xp="type: 'selectus'">
    <input type="checkbox" id="r1"/>
    <label for="r1">Item 1</label>
    <input type="checkbox" id="r2"/>
    <label for="r2">Item 2</label>
</div>

Зависимости

Для получения значений контролов в выражениях используются CSS-селекторы по атрибутам (например, [name=some]) и [this] для данного контрола.

<input data-xp="classed: {on: 'логическое выражение', do: 'имя класса'}"/>
<input data-xp="computed: 'выражение'"/>
<input data-xp="computed: {on: 'выражение', do: 'имя параметра'}"/>
<input data-xp="enabled: 'логическое выражение'"/>
<input data-xp="enabled_on_completed: true"/>
<input data-xp="required: true"/>
<input data-xp="required: 'логическое выражение'"/>
<input data-xp="valid: 'логическое выражение'"/>

Повторения

<div data-xp="
    name: 'имя',
    repeat: {
        id: 'идентификатор',
        min: 1,
        max: 10,
        reset: true,
        template: true
    }
">
    ...
    <button class="repeat_append_button">+</button>
    <button class="repeat_remove_button">&minus;</button>
</div>

Инициализация

Возвращает список 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
<input name="age" data-xp='{"type": "number"}'/>
Пример 2
<input name="age" class="number"/>

Создание нового контрола

Пример 1

Поле с проверкой на соответствие выражению.

xP.controls.register({name: 'zip', base: '_field', prototype: {
    element_selector: '.zip input, input.zip',
    valid: /^\d{6}$/,
    allow_chars_pattern: /^\d+$/
}});
Пример 2

Слайдер для числового значения с использованием виджета Slider.

xP.controls.register({name: 'slider_number', base: 'number', prototype: {
    element_selector: '.slider input',

    init: function(params){
        xP.controls.slider_number.base.init.apply(this, arguments);

        var that = this;

        var slider = this._param(
            'slider',
            $('<div class="slider_control"/>')
                .appendTo(this.$element.parent())
                .slider({
                    min: params.min,
                    max: params.max,
                    value: this.val(),
                    slide: function(event, ui){
                        that.val(ui.value);
                    }
                })
            );

        this.change(function(){
            slider.slider('value', this.val());
        });
    },

    destroy: function(handler, remove){
        if(!arguments.length){
            this._param('slider').destroy();
        }

        return xP.controls.slider_number.base.destroy.apply(
                this, arguments
            );
    },

    param: function(name, value){
        switch(name){
            case 'min':
            case 'max':
            case 'step':
                this._param('slider').slider('option', name, value);

                break;
        };

        return xP.controls.slider_number.base.param.apply(
                this, arguments
            );
    },

    disable: function(disabled){
        disabled = !arguments.length || disabled;

        if(this.disabled !== disabled){
            this._param('slider').slider(
                disabled ? 'disable' : 'enable'
            );
        }

        return xP.controls.slider_number.base.disable.apply(
                this, arguments
            );
    }
}});
Пример 3

Слайдер для набора значений с использованием виджета Slider.

xP.controls.register({name: 'slider_select', base: 'select', prototype: {
    element_selector: '.slider select',

    init: function(params){
        xP.controls.slider_select.base.init.apply(this, arguments);

        var that = this;

        var slider = this._param(
            'slider',
            $('<div class="slider_control"/>')
                .insertAfter(this.$element)
                .slider({
                    min: 0,
                    max: this.$element[0].options.length - 1,
                    value: this.$element[0].selectedIndex,
                    slide: function(event, ui){
                        that.$element[0].selectedIndex = ui.value;
                    }
                })
            );

        this.change(function(){
            slider.slider('value', this.$element[0].selectedIndex);
        });
    },

    destroy: function(handler, remove){
        if(!arguments.length){
            this._param('slider').destroy();
        }

        return xP.controls.slider_select.base.destroy.apply(
                this, arguments
            );
    },

    param: function(name, value){
        switch(name){
            case 'min':
            case 'max':
            case 'step':
                this._param('slider').slider('option', name, value);

                break;
        };

        return xP.controls.slider_select.base.param.apply(
                this, arguments
            );
    },

    disable: function(disabled){
        disabled = !arguments.length || disabled;

        if(this.disabled !== disabled){
            this._param('slider').slider(
                disabled ? 'disable' : 'enable'
            );
        }

        return xP.controls.slider_select.base.disable.apply(
                this, arguments
            );
    }
}});
Пример 4

Поле с редактированием через Реформатор.

xP.controls.register({name: 'wysiwyg', base: 'string', prototype: {
    element_selector: '.wysiwyg textarea',

    init: function(params){
        xP.controls.wysiwyg.base.init.apply(this, arguments);
        this._param('reformator', reformator.append(this.$element[0], {bar: true}));
    },

    destroy: function(handler, remove){
        if(!arguments.length){
            this._param('reformator').destroy();
        }

        return xP.controls.wysiwyg.base.destroy.apply(this, arguments);
    }
}});
Пример 5

Поля для ввода даты с использованием виджета Datepicker.

xP.controls.register({name: 'date_picker', base: '_secret', prototype: {
    element_selector: 'input.date.picker, .date.picker input',

    init: function(params){
        this.locale = xP.locale;

        xP.controls.date_picker.base.init.apply(this, arguments);

        var month_names = [],
            day_names = [this.locale.weekday[6].name],
            day_names_min = [this.locale.weekday[6].abbr];

        for(var i = 0, ii = this.locale.month.length; i < ii; i++){
            month_names.push(this.locale.month[i].name);
        }

        for(var i = 0, ii = this.locale.weekday.length - 1; i < ii; i++){
            day_names.push(this.locale.weekday[i].name);

            day_names_min.push(this.locale.weekday[i].abbr);
        }

        this.$element.datepicker($.extend({
            autoSize: true,
            changeMonth: true,
            changeYear: true,
            dateFormat: this.locale.date,
            firstDay: this.locale.first_day,
            prevText: this.locale.prev_month,
            nextText: this.locale.next_month,
            dayNames: day_names,
            dayNamesMin: day_names_min,
            monthNamesShort: month_names,
            altField: this.$secret,
            altFormat: 'yy-mm-dd'
        }, this.datepicker));

        if(this._.initial_value){
            this.$element.datepicker(
                'setDate',
                new Date(this._.initial_value.replace(/\s*\d+:\S+\s*/, ''))
            );
        }
    },

    destroy: function(handler, remove){
        if(!arguments.length){
            this.locale.destroy();

            this.$element.datepicker('destroy');
        }
        return xP.controls.date_picker.base.destroy.apply(this, arguments);
    },

    param: function(name, value){
        switch(name){
            case 'min':
                this.$element.datepicker('option', 'minDate', value);
                return value;
                break;

            default:
                return xP.controls.datepicker.base.param.apply(this, arguments);
        };
    },

    date: function(){
        return this.$element.datepicker('getDate');
    },

    val: function(value){
        if(!arguments.length){
            return this.disabled
                ? undefined
                : (
                    this.$secret
                        ? this.$secret.val()
                        : this.$element.val()
                );
        }else{
            this.$element.datepicker('setDate', new Date(value));

            return this;
        }
    }
}});


xP.controls.register({name: 'datetime_picker', base: 'date_picker', prototype: {
    element_selector: 'input.datetime.picker, .datetime.picker input',

    init: function(params){
        var value = params.$element.val();

        xP.controls.datetime_picker.base.init.apply(this, arguments);

        this._.$time = $('<input value="' + value.substr(11,2)
            + '" class="hours"/>:<input value="' + value.substr(14,2)
            + '" class="minutes"/>').insertAfter(this.$element);

        var that = this,
            add_time = function(){
                that.$secret.val(
                    that.$secret.val().replace(/\s+\d+:\d+/, '')
                        + ' ' + that._.$time.first().val() + ':'
                        + that._.$time.last().val()
                );
            };

        this._.time_control = new xP.list();

        this._.$time.filter('input').each(function(){
            that._.time_control.append(
                (new xP.controls.number({
                    $element: $(this),
                    min: 0,
                    max: 23,
                    changed: null
                }))
                    .change(add_time)
                    .change(function(){
                        that.change();
                    })
            );
        });

        this._.time_control.last().max = 59;

        this.change(add_time);

        if(this._.initial_value){
            this.$secret.val(this._.initial_value);
        }
    },

    destroy: function(handler, remove){
        if(!arguments.length){
            this._.time_control.each(function(){this.destroy();});

            this._.$time.remove();
        }

        return xP.controls.datetime_picker.base.destroy.apply(this, arguments);
    },

    disable: function(disabled){
        disabled = !arguments.length || disabled;

        if(this.disabled !== disabled){
            xP.controls.datetime_picker.base.disable.apply(this, arguments);

            this._.time_control.each(function(){this.disable(disabled);});
        }

        return this;
    }
}});

Абстрактный контрол

  • Тип _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.

Пример
<input name="number_1" data-xp="type: 'number'"/>

<select name="operator">
    <option>+</option>
    <option>-</option>
    <option>*</option>
    <option>/</option>
</select>

<input name="number_2" data-xp="type: 'number'"/>

=

<span data-xp="type: 'html', computed: 'eval([name=number_1] * 1 + [name=operator] + [name=number_2] * 1)'"></span>

Абстрактный родитель

  • Тип _parent
  • Базовый тип _item
  • Селектор элемента .xp

Используется в качестве базового класса для всех контролов, которые могут выступать родителем для других.

Методы

.children()

  • Возвращает список контролов, находящихся внутри данного.

.val([object | objects array])

  • Позволяет принимать в качестве значения объект или массив объектов. Значения свойств объекта будут устанавливаться в качестве значений для одноименных контролов, находящихся внутри данного.

.focus()

  • Устанавливает фокус. Возвращает данный контрол.

Форма

  • Тип 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]])

  • Обработчик события отправки формы.
    1. При передачи в параметре функции, добавляет ее в список. При передаче значения true во втором параметре, удаляет функцию из списка. Возвращает контрол.
    2. При вызове метода без параметров — выполняет функции в списке. Возвращает логическое значение true или false.

.uncompleted()

  • Проверяет готовность формы. Если готова, возвращает null. Иначе — строку в которой указана причина (required, invalid_required, invalid, unchanged). Получить список конфликтных контролов, можно через метод ._param('зависимость').
Пример
<form method="post">
    <div class="field">
        <label for="field_name">Name</label>
        <input name="name" id="field_name" data-xp="required: true"/>
    </div>

    <div class="field">
        <label for="field_email">Email</label>
        <input name="email" id="field_email" data-xp="type: 'email', required: true"/>
    </div>

    <div class="field">
        <label for="field_message">Message</label>
        <textarea name="message" id="field_message" data-xp="required: true"></textarea>
    </div>

    <div class="field">
        <input type="submit" value="Send" data-xp="enabled_on_completed: true"/>
    </div>

    <div id="uncompleted"></div>
</form>

<script>
    (function(){
        expromptum();

        var uncompleted = $('#uncompleted');

        expromptum('form').first().change(function(){
            var html = '';

            this._param('required')
                .append(this._param('invalid'))
                .each(function(){
                    html += (html ? ', ': '') + this.$label.text();
                });

            uncompleted.html((html ? 'Fill fields: ' : '') + html);
        });
    })();
</script>

Группа полей, листы

  • Тип 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])

  • Отмечает контрол. Возвращает данный контрол.

.show([complete])

  • Отмечает контрол и выполняет после этого переданную функцию. Возвращает данный контрол.

Демо


Сворачиваемая панель

  • Тип foldable
  • Базовый тип fields
  • Селектор элемента .foldable

Свойства

.duration = 200

  • Продолжительность сворачивания (разворачивания) контрола в миллисекундах.

.folded_class = 'folded'

  • Имя CSS-класса, назначаемое элементам свернутого контрола (контейнеру и подписи).

.unfolded_class = 'unfolded'

  • Имя CSS-класса, назначаемое элементам не свернутого контрола (контейнеру и подписи).

Методы

.fold([fold, complete])

  • Сворачивает или разворачивает (в случае fold = false) контрол и выполняет после этого функцию переданную в параметре complete. Возвращает данный контрол.

.show([complete])

  • Отмечает контрол и выполняет после этого переданную функцию. Возвращает данный контрол.

Демо


Абстрактное поле

  • Тип _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

Методы

.click([function()[, remove]])

  • Обработчик нажатия кнопки. При передачи в параметре функции, добавляет ее в список. При передаче значения true во втором параметре, удаляет функцию из списка. При вызове метода без параметров — выполняет функции в списке. Возвращает контрол.

Кнопка отправки

  • Тип submit
  • Базовый тип _item
  • Селектор элемента input[type=submit], button[type=submit]

Выпадающий список

  • Тип select
  • Базовый тип _field
  • Селектор элемента select

Свойства

.hide_disabled_option = true

  • Определяет видимость недоступных элементов. При значении false нужный результат будет только в тех браузерах, которые это поддерживают.

enable_by = 'value'

  • Определяет по какому свойству option определять доступность.

Методы

.disable([disabled[, values]])

  • Определяет доступность контрола. Второй параметр может содержать одно или массив значений к которым нужно применить первый параметр. Возвращает данный контрол.

.append(values)

  • Добавляет пункты выбора. Параметр может содержать одно или массив значений. Каждое из значений может быть: строкой, массивом (вида: [значение для подписи, значение для value]) или объектом (вида: {value: значение для value, label: значение для подписи}). Возвращает данный контрол.

.remove()

  • Удаляет все пункты выбора. Возвращает данный контрол.

.text()

  • Возращает текстовое значение выбранного option.

Демо


Группа переключателей

  • Тип options
  • Базовый тип fields
  • Селектор элемента .options

Группирующий контрол, применяемый для назначения зависимостей на группу переключателей или включателей.


Выпадающий список из переключателей

  • Тип selectus
  • Базовый тип options
  • Селектор элемента .selectus

Демо


Абстрактный переключатель

  • Тип _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])

  • Чтение и запись даты в качестве значения контрола.
Пример
<input name="datemonth" value="2013-04" class="datemonth"/>

Демо


Поле для даты

  • Тип date
  • Базовый тип datemonth
  • Селектор элемента input.date, .date input
Пример
<span class="date field">
    <input id="date_from" name="date_from" value="2010-02-20"/>
</span>

<span class="date field">
    <input id="date_to" name="date_to" data-xp="
        valid: '[name=date_from] < [this]'
    "/>
</span>

Демо


Поле для даты и времени

  • Тип datetime
  • Базовый тип date
  • Селектор элемента input.datetime, .datetime input
Пример
<input name="datetime" value="2013-04-01 12:00" class="datetime"/>

Демо


Комбобокс

  • Тип 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()

  • Скрывает список. Возвращает данный контрол.

Зависимости

Абстрактная зависимость

Используется в качестве базового класса для всех зависисмостей.

Свойства

.to='[this]'

  • Свойство, указывающее на контрол к которому применяется зависисмость.

Управление атрибутом класса

  • Тип classed
  • Базовый тип _item

Свойства

.on

  • Логическое выражение, в случае выполнения которого, элементу контейнеру контрола указанного в свойстве to, будет назначено имя CSS-класса из свойства do.

.do

  • Имя CSS-класса.
Пример 1
<input name="some"/>

<input name="thing" data-xp="classed: {on: '[name=some]', do: 'some'}"/>
Пример 2
<input name="some"/>

<input name="thing" data-xp="classed: [{on: '[name=some]', do: 'some'}, {on: '[name=some] == \'\'', do: 'no'}]"/>

Демо


Вычисляемое значение

  • Тип computed
  • Базовый тип _item

Свойства

.on

  • Выражение, результат которого будет присвоен в качестве значения (через метод .val(значение)) контролу, указанному в свойстве to.

.do

  • Имя свойства. Если указано значение, то результат выражения будет присвоен свойству (через метод .param(свойство, значение)) контрола, указанного в свойстве to.
Пример 1
<input name="number_1" data-xp="type: 'number'"/>

<select name="operator">
    <option>+</option>
    <option>-</option>
    <option>*</option>
    <option>/</option>
</select>

<input name="number_2" data-xp="type: 'number'"/>

=

<input name="number_3" data-xp="type: 'number', computed: 'eval([name=number_1] * 1 + [name=operator] + [name=number_2] * 1)'" readonly="true"/>

Демо


Доступность

  • Тип enabled
  • Базовый тип _item

Свойства

.on

  • Логическое выражение, в случае невыполнения которого, контрол, указанный в свойстве to, будет недоступен для работы (disabled).
Пример
<input name="a"/>

<input name="b" data-xp="enabled: '[name=a]'"/>

Демо


Доступность при полном заполнении

  • Тип enabled_on_completed
  • Базовый тип _item

В зависимости от выполнения условий на обязательность и правильность заполнения формы, делает контрол доступным или недоступным для работы (disabled).

Пример
<form>
    <textarea name="message" data-xp="required: true"></textarea>

    <input type="submit" data-xp="enabled_on_completed: true"/>
</form>

Демо


Абстрактная зависимость на полное заполнение

  • Тип _rooted
  • Базовый тип _item

Используется в качестве базового класса для остальных зависисмостей, которые могут быть задействованы в условиях полного заполнения формы.


Обязательность заполнения

  • Тип required
  • Базовый тип _rooted

Свойства

.on

  • Логическое значение true. Или логическое выражение, в случае выполнения которого, контрол указанный в свойстве to, становится обязательным для заполнения.

.container_required_class = 'required'

  • Имя CSS-класса, назначаемое элементу контейнеру контрола, в случае, если он не заполнен.

.container_unrequired_class = 'unrequired'

  • Имя CSS-класса, назначаемое элементу контейнеру контрола, в случае, если он заполнен.
Пример 1
<input name="name" data-xp="required: true"/>
Пример 2
<input name="a"/>

<input name="b" data-xp="required: '[name=a]'"/>

Демо


Соответствие выражению

  • Тип valid
  • Базовый тип _rooted

Свойства

.on

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

.container_valid_class = 'valid'

  • Имя CSS-класса, назначаемое элементу контейнеру контрола, в случае, если выражение в свойстве on возвращает true.

.container_invalid_class = 'invalid'

  • Имя CSS-класса, назначаемое элементу контейнеру контрола, в случае, если выражение в свойстве on возвращает false.
Пример
<input name="zip" data-xp="valid: /^\d{6}$/'"/>

Демо


Изменение

  • Тип changed
  • Базовый тип _rooted

Данная зависимость назначается всем контролам при инициализации.

Свойства

.container_changed_class = 'changed'

  • Имя CSS-класса, назначаемое элементу контейнеру контрола, в случае, если его значение было изменено.

Повторения

Свойства

.max = 300

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

.min = 1

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

.reset

  • Логическое значение true сбрасывает значения добавляемых контролов. Для каждого из контролов можно задавать свое соответствующее значение в свойстве reset_on_repeat.

.template

  • Логическое значение true определяет данный контрол в качестве шаблона для добавляемых контролов.
Пример 1
<span class="field">
    <input name="a[0]" data-xp="repeat: true"/>

    <button class="repeat_append_button">+</button>

    <button class="repeat_remove_button">&minus;</button>
</span>

Демо


Концепция работы с библиотекой

Все значения свойств у основных объектов библиотеки (контролов, зависимостей и повторений) устанавливаются через параметры при инициализации или через вызов метода .param('имя', значение). Получение значений возможно и через прямое обращение к свойству.

Большинство методов основных объектов библиотеки возвращают сам объект.

Методы и свойства названия которых начинаются с символа подчеркивания, предназначены только для использования внутри библиотеки. Если же есть необходимости обратится к таким свойствам, это следует делать через вызов метода ._param('имя', значение).

Названия свойств, значениями которых являются jQuery-объекты, начинаются с символа доллара.


Режим диагностики

Для диагностики работы в адресной строке можно передать параметр xP=значение. При этом в консоль браузера будут выводится все обнаруженные ошибки и соответствующие значению сообщения: controls — инициализация контролов; submit — отправка формы; dependencies — инициализация и обработка всех зависимостей; classed, enabled, enabled_on_completed, required, valid, changed — обработка зависимостей данного типа; repeats — инициализация повторений.