Forms: Web Form Validation

1 Introduction

This library lets you declaratively validate web form data (and potentially json, xml and other structured data). It differs from the formlets provided by Formlets: Functional Form Abstraction in two important ways:

• the validation model and the presentation are separate, and

• you are given the ability to display and control validation errors.

1.1 Tutorial

1.1.1 Validation

forms are composed of other forms and formlets, functions that can take an input, validate it and potentially transform it into another value.

A basic form might look like this:

(define simple-form   (form     (lambda (name)       (and name (string-upcase name)))     (list (cons 'name binding/text))))

This form accepts an optional text value named "name" and returns its upper-cased version. To validate some data against this form we can call form-validate:

> (form-validate simple-form (hash))

'(ok . #f)

> (form-validate simple-form (hash "name" (make-binding:form #"name" #"Bogdan")))

'(ok . "BOGDAN")

Formlets can be chained in order to generate more powerful validations. If we wanted the above form to require the "name" field, we’d combine binding/text with required using ensure:

(define simple-form   (form     (lambda (name)       (string-upcase name))     (list (cons 'name (ensure binding/text (required))))))

If we validate the same data against simple-form now, our results differ slightly:

> (form-validate simple-form (hash))

'(err (name . "This field is required."))

> (form-validate simple-form (hash "name" (make-binding:form #"name" #"Bogdan")))

'(ok . "BOGDAN")

Notice how in the first example, an error was returned instead of #f and we no longer need to guard against false values in our lambda.

So far so good, but the syntax used to declare these forms can get unwieldy as soon as your forms grow larger than a couple fields. The library provides form*, which is a convenience macro to make writing large forms more manageable. In day-to-day use, you’d declare the above form like this:

(define simple-form   (form* ([name (ensure binding/text (required))])     (string-upcase name)))

If you’re thinking "Hey, that looks like a let"! You’re on the right track.

1.1.2 Presentation

Let’s take a slightly more complicated form:

(define login-form   (form* ([username (ensure binding/email (required) (shorter-than 150))]           [password (ensure binding/text (required) (longer-than 8))])     (list username password)))

This form expects a valid e-mail address and a password longer than 8 characters and it returns a list containing the two values on success. To render this form to HTML, we can define a function that returns an x-expression:

(define (render-login-form)   '(form      ((action "")       (method "POST"))      (label        "Username"        (input ((type "email") (name "username"))))      (label        (input ((type "password") (name "password"))))      (button ((type "submit")) "Login")))

This will do the trick, but it has two problems:

• if there are any validation errors and we re-display the form to the user, the previously-submitted values won’t show up,

• nor will any validation errors.

We can use "widgets" to fix both problems. First, we have to update render-login-form to take a widget rendering function as input:

(define (render-login-form render-widget)   '(form      ((action "")       (method "POST"))      (label        "Username"        (input ((type "email") (name "username"))))      (label        "Password"        (input ((type "password") (name "password"))))      (button ((type "submit")) "Login")))

Second, instead of rendering the input fields ourselves, we can tell render-widget to render the appropriate widgets for those fields:

(define (render-login-form render-widget)   `(form      ((action "")       (method "POST"))      (label        "Username"        ,(render-widget "username" (widget-email)))      (label        "Password"        ,(render-widget "password" (widget-password)))      (button ((type "submit")) "Login")))

Finally, we can also begin rendering errors:

(define (render-login-form render-widget)   `(form      ((action "")       (method "POST"))      (label        "Username"        ,(render-widget "username" (widget-email)))      ,@(render-widget "username" (widget-errors))      (label        "Password"        ,(render-widget "password" (widget-password)))      ,@(render-widget "password" (widget-errors))      (button ((type "submit")) "Login")))

To compose the validation and the presentation aspects, we can use form-run:

(define (make-request #:method [method #"GET"]                       #:url [url "http://example.com"]                       #:headers [headers null]                       #:bindings [bindings null])   (request method (string->url url) headers (delay bindings) #f "127.0.0.1" 8000 "127.0.0.1"))

> (form-run login-form (make-request))

'(pending #f #<procedure:...rivate/forms.rkt:101:2>)

form-run is smart enough to figure out whether or not the request should be validated based on the request method. Because we passed it a (fake) GET request above, it returned a 'pending result and a widget renderer. That same renderer can be passed to our render-login-form function:

> (match-define (list _ _ render-widget)     (form-run login-form (make-request)))

> (pretty-print (render-login-form render-widget))

'(form   ((action "") (method "POST"))   (label "Username" (input ((type "email") (name "username"))))   (label "Password" (input ((type "password") (name "password"))))   (button ((type "submit")) "Login"))

If we pass it an empty POST request instead, the data will be validated and a 'failed result will be returned:

> (form-run login-form (make-request #:method #"POST"))

'(failed ((username . "This field is required.") (password . "This field is required.")) #<procedure:...rivate/forms.rkt:101:2>)

Finally, if we pass it a valid POST request, we’ll get a 'passed result:

> (form-run login-form (make-request #:method #"POST"                                      #:bindings (list (make-binding:form #"username" #"bogdan@defn.io")                                                       (make-binding:form #"password" #"hunter1234"))))

'(passed ("bogdan@defn.io" "hunter1234") #<procedure:...rivate/forms.rkt:101:2>)

Putting it all together, we might write a request handler that looks like this:

(define (login req)   (match (form-run login-form req)     [(list 'passed (list username password) _)      (login-user! username password)      (redirect-to "/dashboard")]       [(list _ _ render-widget)      (response/xexpr (render-login-form render-widget))]))

1.1.3 Nested Validation

I left one thing out of the tutorial that you might be wondering about. Aside from plain values, forms can also return ok? or err? values. This makes it possible to do things like validate that two fields have the same value.

(define signup-form   (form* ([username (ensure binding/email (required) (shorter-than 150))]           [password (form* ([p1 (ensure binding/text (required) (longer-than 8))]                             [p2 (ensure binding/text (required) (longer-than 8))])                       (cond                         [(string=? p1 p2) (ok p1)]                         [else (err "The passwords must match.")]))])     (list username password)))

This form will validate that the two password fields contain the same value and then return the first value.

1.1.4 Next Steps

If the tutorial left you wanting for more, take a look at the reference documentation below and also check out the examples folder in the source code repository.

1.2 Limitations

The following features are not currently supported (and may never be):

• multi-valued form bindings

• dynamic lists of fields and forms – it is possible to dynamically manipulate forms, but there is no nice syntax for it

• default form values must be passed to form-run and cannot be encoded into the forms themselves – this is inconvenient for some use cases but it hugely simplifies the implementation and it makes it so that the same form can be used, for example, to create something and also to edit that thing

2 Reference

2.1 Formlets

2.1.1 Primitives

These functions produce formlets either by combining other formlets or by "lifting" normal values into the formlet space.

2.1.2 Validators

These functions produce basic validator formlets.

2.2 Forms

2.3 Widgets