Red Tape

Red Tape is a Clojure library for processing user-submitted data. It's heavily inspired by Django's forms (the good parts).

License: MIT/X11
Documentation: http://sjl.bitbucket.org/red-tape/
Changelog: http://sjl.bitbucket.org/red-tape/changelog/
Issues: http://github.com/sjl/red-tape/issues/
Mercurial: http://bitbucket.org/sjl/red-tape/
Git: http://github.com/sjl/red-tape/

What Does it Look Like?

You'll need to read the docs to really understand what's going on, but here's a quick example so you can see the shape of the code.

First you'll define a form:

(ns my-web-app
    (:require [red-tape.core :refer [defform]]
              [red-tape.cleaners :as cleaners]))

(defform comment-form
  {:arguments [user]
   :initial {:email (:email-address user)}}

  :email ^:red-tape/optional
         [#(cleaners/matches #"\S+@\S+" %
                             "Enter a valid email (or leave it blank).")]
  :comment [clojure.string/trim
            cleaners/non-blank
            #(cleaners/max-length 2000 %)])

A form can have some arguments, initial data, as well as some fields. Fields have functions for validating data and massaging it into what you need.

Now we can use the form to create an initial form (which we'll display to the user so they can fill it in):

(def steve {:email "steve@stevelosh.com"})
(def anon {:email ""})

(comment-form steve)
; =>
{:fresh true
 :valid nil
 :results nil
 :errors nil
 :data {:email "steve@stevelosh.com" :comment ""}
 :arguments {:user {:email "steve@stevelosh.com"}}}

(comment-form anon)
; =>
{:fresh true
 :valid nil
 :results nil
 :errors nil
 :data {:email "" :comment ""}
 :arguments {:user {:email ""}}}

And once they submit it we use the form once again to validate and transform the data:

(comment-form steve {:email "steve+nospam@stevelosh.com"
                     :comment "    Hello!"})
; =>
{:fresh false
 :valid true
 :results {:email "steve+nospam@stevelosh.com"
           :comment "Hello!"}
 :errors nil
 :data {:email "steve+nospam@stevelosh.com"
        :comment "    Hello!"}
 :arguments {:user {:email "steve@stevelosh.com"}}}

If there are errors, we know the data was bad and we need to show the form to the user again so they can fix it:

(comment-form anon {:email ""
                    :comment ""})
; =>
{:fresh false
 :valid false
 :results nil
 :errors {:comment "This field is required."}
 :data {:email ""
        :comment ""}
 :arguments {:user {:email ""}}}

But you'll really need to read the docs to understand what's happening here.

Why Red Tape?

There are a lot of other Clojure "validation" libraries out there. I wasn't happy with any of them for a few reasons:

In a nutshell, Red Tape was made by someone who used Django's forms in client sites for years and knows all the rough edges that needed sanding.

Get Started

Get started by installing Red Tape, then move on to the basics.

Table of Contents

  1. Installation
  2. Basics
  3. Form Input
  4. Cleaners
  5. Result Maps
  6. Initial Data
  7. Form Arguments
  8. Rendering
  9. Reference
  10. Changelog