about:morf
Home / К началу |
Dwonload |
На Русском |
Examples / Примеры
Morf is a relatively small (12K compressed and 16K uncompressed) JavaScript program,
which is meant to make your forms more usable.
With Morf you can create user-friendly forms with validation features -
even if you are totally dumb in JavaScript.
The name "Morf" is an anagram to "form"
The goal of creating Morf was to attach new features to valid XHTML forms using
as few additional scripting as possible. The main features are as follows:
- user data validation with a possibility of custom error processing;
- advanced data submission and communicating with the server.
Morf is an independent appplication (it does not use any third-party libraries).
The following features are implemented in Morf:
- client-side validation - both with built-in and custom validators;
- sending form-data via asynchronous requests (no page-reloads);
- simple data-exchange protocol for communicating with the server-backend:
the client should receive a JavaScript object (JSON-serialized) in response to its request,
and, depending on that object's contents, either outputs errors encountered by server
or calls a function - processor for the data transmitted from server back to the client;
"отловил" сервер или же вызывает функцию обработчик (можно пользовательскую);
- Morf uses declarative syntax - a specific HTML-markup - to define
validation rules, error messages ans so on. Because Morf uses its own XML-namespace,
this does not hurt XHTML-documents (if you use XHTML DOCTYPE);
- user callbacks executed upon
a) error
b) successful data submission
(by default, Morf will output error-list in case of error and
reload the page in case of success);
- tracking form elements’ state so that invalid elements could be marked by means of CSS;
Morf basic usage
It is very simple to include Morf into your webpage:
just insert the following code inside the <HEAD> tag: <script type="text/javascript" src="/path/to/morf.js"><srcipt>.
Morf will then start its work after the page loads,
and all the forms on the page (with the exception of those specially marked)
will be handled by Morf.
Morf declarative syntax:
By default, Morf uses "x:" namespace, but
you may change this behavior by setting a value for Morf.NS property.
Morf attributes:
- FORM x:runat - the only value that matters,
is client - and it means that this particular form should not be
handled by Morf. Morf will, however, still
validate the form.
- FORM x:mark-required - text that will be used to mark required fields in this form.
This text will be inserted into the beginning of <LABEL> tag,
in case we're able to find one for the element, and immediately after the element irself -
in case we're not able to find a corresponding<LABEL>.
- FORM x:done - JavaScript-callback, which has to be called upon a successful
data submission (which also means that the server response does not point to errors).
The callback should not contain ending brackets.
Example - <form x:done="MyObject.MyMethod">.
The callback is passed a single argument data -
this is the data that the server passed back to the client after processing form data.
- FORM x:failed - JavaScript-callback, which has to be called when encountering
errors during validation, data submission, or the errors that the server has encountered -
and passed back to the client.
Tha callback is called with a single argument error_list - this
is an array of strings - error messages.
- Element x:required - any non-empty value in this attribute points to the fact that
this element is required.
- Element x:required-error - error message - raised when an element marked as
x:required is not fullfilled by the form user.
- Element x:pattern - regular expression that the user-contributed text should match.
- Element x:pattern-error - error message - raised when the element value does not match
pattern provided in x:pattern.
- Element x:validator - JavaScript-object that should be used for validation.
Custom validator should contain method validate(value),
that returns a boolean.
In Morf, the following built-in validators are implemented:
email and url.
In order to use a built-in validator for an element, you should provide its name
prefixed with "x:" - inside the x:validator attribute,
for example: <input x:validator="x:email" />.
- Element x:validator-error - error message - raised when the element value
does not match the validator provided in x:validator.
How does Morf communicate with the server?
Form data are passed to the server by means of usual HTTP requests - GET or POST, depending on
the value of the form's method attribute.
From server Morf expect a text containing a JSON-serialized
JavaScript object. That object should contain three fields:
- code - response code ("ok" in case everything is ok, or
"error" - in case of an error);
- error_list - errors encountered by the server - an array of strings;
- data - an arbitrary JavaScript-object (or even simplay a string or a number),
that should be passed to the callback - successfull submission processor.
Known / possible bugs:
At the moment, I am working on form serialization algorythm.
Current version may have problems serializing
<input type="checkbox">,
<input type="radio">, <select multiple="true()">
Questions, wishes etc - are greatefully accepted at crocodile2u at yandex.ru