Field validation on the server: the ypy-validate extension
Some rules only the server knows: this email is taken, this code has expired. ypy-validate asks the server about them
when the user leaves a field and shows the answer next to the field, before the user presses the button. The form's values
go to the server, but the form is not submitted.
<script src="ypy.min.js"></script>
<script src="ext/ypy-validate.min.js"></script>
<form ypy-post="/signup" ypy-target="#result" ypy-validate-fields="/signup/validate">
<label for="email">Email</label>
<input id="email" name="email" type="email">
<small id="email-error"></small>
<label for="name">Name</label>
<input id="name" name="name">
<small id="name-error"></small>
<button>Create account</button>
</form>Leave the email field after changing it and a POST /signup/validate goes out. If the server answers 422 with
<span>This email is taken</span>, that markup lands in #email-error, and the field gets aria-invalid="true" and
aria-describedby="email-error". The focus stays where the user is. Without the extension the attributes below do
nothing.
Attributes
| Attribute | On | Value | Meaning |
|---|---|---|---|
ypy-validate |
a field | a URL, or nothing | check this field; a bare attribute asks the action of the form |
ypy-validate-fields |
a form, or any element around fields | a URL, or nothing | check every field inside; a field with ypy-validate="false" is left out, and one with its own URL uses it |
ypy-validate-trigger |
a field, or the element with ypy-validate-fields |
a trigger specification | when to check; default change delay:200ms |
ypy-validate-batch |
a field, the element with ypy-validate-fields, or the form (nearest wins) |
a time, nothing, or false |
send the fields asked within that window in one request; bare means 50ms; off by default |
ypy-error-target |
the field | a selector | where the answer goes |
ypy-error-swap |
the field | a swap style | how it goes in; default innerHTML |
ypy-error-focus |
the field | a selector | where focus goes after a 422; default: it stays |
The action of the form is its ypy-post (or ypy-action), else its action attribute, else the current path.
The core already uses ypy-validate="true" and ="false" to switch the browser's own constraint check before a request, and
this extension ignores those two values. Any other value, including none, is a server check. On a form write
ypy-validate-fields, because a form whose ypy-validate is a URL would lose the browser check of its own submit.
Other triggers use the syntax of ypy-trigger. Fields are wired when their subtree is processed, so fields that arrive in a
swap work at once.
<input name="handle" ypy-validate="/handles/check" ypy-validate-trigger="input delay:400ms">
<input name="code" ypy-validate="/codes/check" ypy-validate-trigger="blur">The request
A POST to the URL with every value of the form, so a rule can compare two fields, plus the header YPY-Validate with the
name of the field being checked (the id when the field has no name). It carries the usual YPY-* request headers, and its
YPY-Source is the field.
The server must look at YPY-Validate before it does anything else. The request often goes to the handler of the form
itself, and a handler that does not know the header would run the whole action: create the account, send the email.
POST /signup/validate
YPY-Validate: email
Content-Type: application/x-www-form-urlencoded
email=ana%40example.com&name=AnaThe answer
| Status | Meaning | The page |
|---|---|---|
422 |
the field is invalid | the body is swapped into the place; the field gets aria-invalid="true" and aria-describedby |
204, or an empty 200 |
valid | the place is emptied and aria-invalid is removed |
200 with a body |
valid, with something to say ("Available") | the body is swapped into the place and aria-invalid is removed |
| anything else, or the network fails | no answer | nothing changes; the form validates again when submitted |
The place follows the error convention: ypy-error-target on the field, with every
selector form. Without it, #<id>-error (the field's id, else its name). When the page has no such element, the
extension creates a <div class="ypy-field-error" aria-live="polite"> right after the field. A YPY-Retarget or
YPY-Reswap header and ypy-status:422 still win. A 422 for a field never goes into the form, so the other fields, what
the user typed and the focus stay.
Batches
By default every field is a request of its own, so a paste into a whole form sends one request per field. With
ypy-validate-batch, the fields of one form that ask the same URL within a short window go in a single request.
<form ypy-post="/signup" ypy-validate-fields="/signup/validate" ypy-validate-batch="80ms">
<input id="email" name="email" type="email"><small id="email-error"></small>
<input id="username" name="username"><small id="username-error"></small>
<button>Create account</button>
</form>ypy.config.validate = { batch: '80ms' } turns it on for every form, and ypy-validate-batch="false" turns one off. The
window starts at the first field that asks, and the fields go together in one POST with every value of the form. The header
then holds the names separated by commas, YPY-Validate: email,username, and a single field in a window is sent as without
batching. Fields of two forms or two URLs never share a request, and a field that left the page during the window is not
sent.
The answer is 422 when any field in the batch is invalid and any 2xx when none is. The message of each invalid field
comes as an out-of-band element whose id is the id of that field's place. A field with no such element is valid, and its
place is emptied.
HTTP/1.1 422 Unprocessable Content
Content-Type: text/html; charset=utf-8
<small id="email-error" ypy-swap-oob="innerHTML">This email is taken</small>Batching is off by default because the server must read the list: a handler that only knows one name would see
email,username and find no rule for it. The same handler answers a single field, so a page can turn batching on and off
without a change on the server.
Concurrency
A field has at most one check in flight, so a slow answer never overwrites a fresh one. Different fields are checked
independently. A request sent by the form cancels the checks of its fields that are still running, so a late "invalid" does
not appear after the form was accepted. A check is not sent if the field left the page while the debounce waited. A
request that carries YPY-Validate does not expire the ypy-cache.
Accessibility
The answer region has aria-live="polite" when the extension creates it, so give your own region the same attribute.
aria-invalid and aria-describedby follow each check. A check never moves the focus, because the user is moving through the
form, and ypy-error-focus changes that deliberately for one field. The check is a hint, and the form must still validate on
submit.
Pitfalls
-
A handler that does not read
YPY-Validateruns the real action on every check. Test it with a request that carries the header. - With batching on,
YPY-Validatecan hold commas. Split it and do not compare it with one field name. -
In a batch, a
422without an out-of-band element for a field means that field is valid. A422with a plain-text body empties every place and marks no field. -
A form with
enctype="multipart/form-data"sends its files with every check. Give the fieldypy-encoding="application/x-www-form-urlencoded"to send the values as text only.