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>

По умолчанию на русском языке. Используется в контролах: number, datemonth, date, datetime, date.picker, datemonth.picker, datetime.picker. Также считывается xml:lang у <html>, либо у любого элемента формы. В библиотеке кроме русского есть en-GB. Можно добавить свою. Если локализация не задана у контрола, будет проверяться вверх по дереву, вплоть до html.

<form  xml:lang="ru">
    <input class="number" data-xp='{locale: "en-GB"}'/>
    <input class="date picker"  xml:lang="ru" />
</form>

Инициализация своей локализации

    <input class="date picker"  xml:lang="es" />

	var es_locate = {
				abbr: 'es',
				prev_month: 'Anterior',
				current_month: 'Corriente',
				next_month: 'Siguiente',
				yesterday: 'Ayer',
				today: 'Hoy',
				tomorrow: 'mañana',
				now: 'Ahora',
				close_popup:  'cerca'
			}
	xP.locale.add(
		'es' /*id*/,
		es_locate, /*объект локали*/
		'en-GB' /*default_id - откуда брать недостающие параметры*/
	);
	
	/* добавление производится до инициализации формы */
	expromptum();

Контролы

Тип контрола определяется 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>

HTML

<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'"/>

Календарь

Поле для года и месяца с календарем

<input class="datemonth picker" data-xp="type: 'date_picker'"/>

Поле для даты с календарем

<input class="date  picker" data-xp="type: 'date_picker'"/>

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

<input class="datetime picker" data-xp="type: 'date_picker'"/>

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

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

<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);
	}
}});

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

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

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

artlebedev / expromptum Goto Github PK

expromptum's Introduction

Expromptum

Пример

Кнопки

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

Календарь

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

Методы

Методы

Пример 1

Пример 2

Пример 1

Пример 2

Пример 3

Пример 4

Свойства

Методы

Пример

Методы

Свойства

Методы

Пример

Свойства

Методы

Свойства

Методы

Свойства

Методы

Свойства

Методы

Методы

Свойства

Методы

Свойства

Методы

Свойства

Свойства

Свойства

Методы

Методы

Пример

Пример

Пример

Свойства

Методы

Свойства

Свойства

Пример 1

Пример 2

Свойства

Пример 1

Свойства

Пример

Пример

Свойства

Пример 1

Пример 2

Свойства

Пример

Свойства

Свойства

Пример 1

expromptum's People

Contributors

Stargazers

Watchers

Forkers

expromptum's Issues

Recommend Projects

Recommend Topics

Recommend Org