about:morf
К началу / Home |
Скачать |
In English |
Примеры / Examples
Морф - это относительно небольшая (12Кб в сжатом виде и 16Кб в полном) программа на JavaScript,
которая предназначена для того чтобы сделать ваши формы более удобными.
С помощью Морф можно делать юзабельные формы с валидацией введенных значений -
даже совершенно не зная JavaScript.
Название «Морф» возникло как анаграмма на английское «form».
Цель создания Морф - получить инструмент, с помощью которого
формы, созданные с помощью валидного XHTML, приобрели бы качественно новые свойства,
по возможности без написания новых скриптов. Главные из этих свойств:
- валидация введенных пользователем значений с возможностью обработки ошибок;
- продвинутое управление отправкой данных и взаимодействие с сервером.
Морф - независимое приложение (используются только встроенные возможности JavaScript,
без необходимости подключения сторонних библиотек).
Морф предоставляет следующий набор функциональности:
- валидация введенных значений на стороне клиента - как с помощью
встроенных валидаторов, так и с помощью валидаторов,
определенных пользователем;
- отправка данных формы с помощью асинхронных запросов (без перезагрузки страницы);
- простой протокол общения с серверной частью:
в ответ на свой запрос клиент принимает от сервера объект JavaScript, сериализованный в виде JSON,
и в зависимости от его содержимого, выводит список ошибок, которые
"отловил" сервер или же вызывает функцию - обработчик переданных с сервера данных
(можно пользовательскую);
- простой декларативный синтаксис - специфическую HTML-разметку - для
задания правил валидации, сообщений об ошибках и т. д. Поскольку Морф
использует собственное пространство имен, это не нарушает валидность
XHTML-документа (если вы используете доктайп XHTML);
- пользовательские коллбэки, выполняющиеся при
a) появлении ошибки
б) успешной отправке данных
(по умолчанию Морф выдает список ошибок на страницу в случае отлова ошибок,
и перегружает страницу в случае успешной отправки данных);
- отслеживание состояния элементов формы, таким образом чтобы неправильно заполненные
элементы можно было выделить при помощи CSS;
Как использовать Морф?
Подключить Морф очень просто: внутри тега <HEAD> на своей странице
вставьте такой код: <script type="text/javascript" src="/путь/к/morf.js"><srcipt>.
Морф отработает после загрузки страницы и все формы на этой странице
(за исключением специальным образом помеченных) будут теперь обрабатываться
с помощью Морф.
Декларативный синтаксис Морф:
По умолчанию, Морф использует пространство имен "x:", однако,
вы можете изменить это поведение, задав значение для свойства Morf.NS.
Атрибуты Морф:
- FORM x:runat - единственное значение, которое имеет смысл -
client - указывает на то, что данную форму не следует отправлять при
помощи Морф. Морф при этом все же продолжает
производить валидацию данной формы.
- FORM x:mark-required - текст, которым следует помечать необходимые для заполнения поля.
Этот текст вставляется в начало тега <LABEL>, если таковой
отыщется для элемента, и сразу после самого элемента - если <LABEL>
не отыщется.
- FORM x:done - JavaScript-коллбэк, который следует выполнить в случае успешной отправки
формы и получения от сервера ответа, который не сигнализирует об ошибках.
Коллбэк следует указывать без скобок в конце.
Например - <form x:done="MyObject.MyMethod">.
Коллбэк вызывается с единственным аргументом data - это данные,
которые сервер передал назад клиенту после обработки данных формы.
- FORM x:failed - JavaScript-коллбэк, который следует выполнить в случае возникновения ошибок
при валидации, отправке данных, или же ошибок, которые обнаружил сервер и передал их назад клиенту.
Коллбэк вызывается с единственным аргументом error_list - это массив
строк - сообщений об ошибках.
- Element x:required - любое непустое значение в этом атрибуте указывает на то, что
данный элемент является необходимым для заполнения.
- Element x:required-error - текст ошибки при незаполнении элемента, помеченного
атрибутом x:required.
- Element x:pattern - шаблон (регулярное выражение), которому должен соответствовать текст,
введенный пользователем в поле.
- Element x:pattern-error - текст ошибки при несоответствии значения шаблону, указанному в
атрибуте x:pattern.
- Element x:validator - JavaScript-объект, который следует использовать для валидации значения элемента.
Пользовательский валидатор должен содержать метод validate(value),
который возвращает булево значение.
В Морф реализованы также следующие встроенные валидаторы:
email и url.
Для того чтобы присвоить элементу встроенный валидатор, следует указать его имя с префиксом "x:",
например: <input x:validator="x:email" />.
- Element x:validator-error - текст ошибки при несоответствии значения валидатору, указанному в
атрибуте x:validator.
Как Морф "общается" с сервером?
Данные передаются на сервер в виде обычных HTTP-запросов GET или POST, в зависимости от значения атрибута
method формы.
От сервера же Морф ожидает получить текст, содержащий JavaScript-объект,
сериализованный в нотации JSON. Этот объект должен содержать три поля:
- code - код ответа ("ok" в случае если все нормально, или же
"error" в случае ошибки);
- error_list - список ошибок, "отловленных" на стороне сервера - массив строк;
- data - произвольный JavaScript-объект (или даже просто строка или число),
который нужно передать в функцию - обработчик успешного завершения отправки данных.
Известные / возможные неполадки:
В данный момент я работаю над улучшением алгоритма сериализации форм.
В текущей версии возможны баги при сериализации значений
<input type="checkbox">,
<input type="radio">, <select multiple="true()">
Все вопросы, пожелания и т. д. - на crocodile2u at yandex.ru