The whofields Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

The whofields Reference Manual

This is the whofields Reference Manual, version 1.0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Aug 15 06:11:20 2022 GMT+0.

Table of Contents


1 Introduction

whofields

Whofields is an HTML field rendering and input validation utility library written in Common Lisp.

Whofields depends on CL-WHO. Whofields is being developed with SBCL, CCL, and LispWorks on OS X. Whofields is being deployed with SBCL on Linux/AMD64.

Field Specifiers

Whofields defines the notion of a field specifier--a fieldspec--to specify the name, label, and control-specific properties of a field. Whofields currently supports :TEXT, :PASSWORD, :SELECT, :RADIO, and :CHECKBOX fieldspecs.

Whofields provides functions for rendering HTML form controls and for validating HTTP POST and GET parameter values according to fieldspecs. However, Whofields makes no assumptions about the means of obtaining HTTP parameters; Whofields accepts either single values or alists of parameter names and values.

Installation

(ql:quickload "whofields")

Example


(defun parse-string (x)
  (if (stringp x)
      (values (string-trim '(#\Space #\Tab #\Newline) x) t)
      (values nil nil)))

(defun parse-non-empty-string (x)
  (if (stringp x)
      (let ((x (string-trim '(#\Space #\Tab #\Newline) x)))
        (if (string/= "" x)
            (values x t)
            (values nil nil)))
      (values nil nil)))

(defparameter *provinces*
  '(("AB" . "Alberta)
    ("BC" . "British Columbia")
    ("MB" . "Manitoba")
    ("NB" . "New Brunswick")
    ("NL" . "Newfoundland and Labrador")
    ("NT" . "Northwest Territories")
    ("NS" . "Nova Scotia")
    ("NU" . "Nunavut")
    ("ON" . "Ontario")
    ("PE" . "Prince Edward Island")
    ("QC" . "Quebec")
    ("SK" . "Saskatchewan")
    ("YT" . "Yukon")))

(defparameter *registration-fieldspecs*
  (list (list 'username :text :label "Corporation" :validation-function #'parse-non-empty-string
              :placeholder "Corporation")
        (list 'full-name :text :label "Full Name" :validation-function #'parse-non-empty-string
              :placeholder "Full Name")
        (list 'email :text :label "Email" :validation-function #'parse-non-empty-string
               :placeholder "Email")
        (list 'email2 :text :label "Email (confirm)" :validation-function #'parse-non-empty-string
              :placeholder "Email (confirm)")
        (list 'phone :text :label "Phone" :validation-function #'parse-non-empty-string
              :placeholder "Phone")
        (list 'alt-phone :text :label "Alt. Phone" :validation-function #'parse-string
              :placeholder "Alt. Phone")
        (list 'address :text :label "Address" :validation-function #'parse-non-empty-string
              :placeholder "Address")
        (list 'city :text :label "City" :validation-function #'parse-non-empty-string
              :placeholder "City")
        (list 'province :select :label "Province"
              :options *provinces* :key #'car :label-function #'cdr :test #'string=)
        (list 'postal-code :text :label "Postal Code" :validation-function #'parse-non-empty-string
              :placeholder "Postal Code")
        (list 'agrees-to-mailing-list :label "I want to join the mailing list" :checkbox :truep t)))

(defparameter *registration-fieldvals*
  (list (cons 'username "")
        (cons 'full-name "")
        (cons 'email "")
        (cons 'email2 "")
        (cons 'phone "")
        (cons 'alt-phone "")
        (cons 'address "")
        (cons 'city "")
        (cons 'province "ON")
        (cons 'postal-code "")
        (cons 'agrees-to-mailing-list nil)))

(defun render-registration-page (fieldvals fielderrs &optional (stream *standard-output*))
  (with-html-page (stream)
    (:div :class "container"
          (when fielderrs
           (cl-who:htm
             (:div :class "alert alert-danger" "Please correct the issues highlighted below.")))
         (:form :action "/registration" :method "post"
                (dolist (fieldspec *registration-fieldspecs*)
                  (let ((name (whofields:fieldspec-name fieldspec))
                        (label (whofields:fieldspec-label fieldspec)))
                    (cl-who:htm
                     (:div :class (if (member name fielderrs) "form-group has-error" "form-group")
                           (:label :for (string-downcase name) :class "control-label col-sm-2"
                                   (cl-who:esc label))
                           (:div :class "col-sm-10"
                                 (whofields:render-field stream
                                                         fieldspec
                                                         (cdr (assoc name fieldvals))))))))
                (:div :class "form-group"
                      (:div :class "col-sm-12"
                            (:button :type "submit" :class "btn btn-primary" "Register")))))))

(hunchentoot:define-easy-handler (handle-registration :uri (princ-to-string "/registration"))
    ()
  (setf (hunchentoot:content-type*) "text/html; charset=utf-8")
  (cond ((equal (hunchentoot:request-method*) :post)
         (multiple-value-bind (fieldvals fielderrs)
             (whofields:validate-fields *registration-fieldspecs*
                                        (hunchentoot:post-parameters*))
           (unless (string= (hunchentoot:post-parameter "email")
                            (hunchentoot:post-parameter "email2"))
             (push 'email2 fielderrs))
           (if fielderrs
               (with-output-to-string (stream)
                 (render-registration-page fieldvals fielderrs stream))
               (progn
                 (model:register fieldvals)
                 (hunchentoot:redirect "/registration-complete")))))
        ((equal (hunchentoot:request-method*) :get)
         (with-output-to-string (stream)
           (render-registration-page *registration-fieldvals* '() stream)))))

License

Whofields is distributed under the MIT license. See LICENSE.


2 Systems

The main system appears first, followed by any subsystem dependency.


Next: , Previous: , Up: Systems   [Contents][Index]

2.1 whofields

HTML field rendering and input validation utilities written in Common Lisp

Author

Michael J. Forster <mike@forsterfamily.ca>

License

MIT

Version

1.0.1

Defsystem Dependency

asdf-package-system (system).

Dependency

whofields/core/all (system).

Source

whofields.asd.


2.2 whofields/core/all

Author

Michael J. Forster <mike@forsterfamily.ca>

License

MIT

Dependencies
Source

whofields.asd.


2.3 whofields/core/fieldspec

Author

Michael J. Forster <mike@forsterfamily.ca>

License

MIT

Source

whofields.asd.


2.4 whofields/core/render

Author

Michael J. Forster <mike@forsterfamily.ca>

License

MIT

Dependency

cl-who (system).

Source

whofields.asd.


2.5 whofields/core/validate

Author

Michael J. Forster <mike@forsterfamily.ca>

License

MIT

Dependency

whofields/core/fieldspec (system).

Source

whofields.asd.


3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


3.1.1 whofields/whofields.asd

Source

whofields.asd.

Parent Component

whofields (system).

ASDF Systems

3.1.2 whofields/core/all/file-type.lisp

Source

whofields.asd.

Parent Component

whofields/core/all (system).

Packages

whofields/core/all.


3.1.3 whofields/core/fieldspec/file-type.lisp

Source

whofields.asd.

Parent Component

whofields/core/fieldspec (system).

Packages

whofields/core/fieldspec.

Public Interface

3.1.4 whofields/core/render/file-type.lisp

Source

whofields.asd.

Parent Component

whofields/core/render (system).

Packages

whofields/core/render.

Public Interface

render-field (function).

Internals

3.1.5 whofields/core/validate/file-type.lisp

Source

whofields.asd.

Parent Component

whofields/core/validate (system).

Packages

whofields/core/validate.

Public Interface
Internals

4 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

4.1 whofields/core/fieldspec

Source

file-type.lisp.

Use List

common-lisp.

Used By List

whofields/core/all.

Public Interface

4.2 whofields/core/all

Source

file-type.lisp.

Nickname

whofields

Use List

4.3 whofields/core/render

Source

file-type.lisp.

Use List

common-lisp.

Used By List

whofields/core/all.

Public Interface

render-field (function).

Internals

4.4 whofields/core/validate

Source

file-type.lisp.

Use List

common-lisp.

Used By List

whofields/core/all.

Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Public Interface


5.1.1 Ordinary functions

Function: fieldspec-label (fieldspec)
Package

whofields/core/fieldspec.

Source

file-type.lisp.

Function: fieldspec-name (fieldspec)
Package

whofields/core/fieldspec.

Source

file-type.lisp.

Function: fieldspec-plist (fieldspec)
Package

whofields/core/fieldspec.

Source

file-type.lisp.

Function: render-field (stream fieldspec value)
Package

whofields/core/render.

Source

file-type.lisp.

Function: validate-field (fieldspec value)
Package

whofields/core/validate.

Source

file-type.lisp.

Function: validate-fields (fieldspecs fieldvals)
Package

whofields/core/validate.

Source

file-type.lisp.


5.2 Internals


Previous: , Up: Internals   [Contents][Index]

5.2.1 Ordinary functions

Function: escape-value (value)
Package

whofields/core/render.

Source

file-type.lisp.

Function: render-checkbox (stream name value &key &allow-other-keys)
Package

whofields/core/render.

Source

file-type.lisp.

Function: render-password-input (stream name value &key placeholder &allow-other-keys)
Package

whofields/core/render.

Source

file-type.lisp.

Function: render-select (stream name value &key options test key label-function &allow-other-keys)
Package

whofields/core/render.

Source

file-type.lisp.

Function: render-static (stream name value &key &allow-other-keys)
Package

whofields/core/render.

Source

file-type.lisp.

Function: render-text-input (stream name value &key placeholder &allow-other-keys)
Package

whofields/core/render.

Source

file-type.lisp.

Function: validate-boolean (value &key truep &allow-other-keys)
Package

whofields/core/validate.

Source

file-type.lisp.

Function: validate-option (value &key options test key &allow-other-keys)
Package

whofields/core/validate.

Source

file-type.lisp.

Function: validate-string (value &key validation-function &allow-other-keys)
Package

whofields/core/validate.

Source

file-type.lisp.


Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts


Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   E   F   R   V  
Index Entry  Section

E
escape-value: Private ordinary functions

F
fieldspec-label: Public ordinary functions
fieldspec-name: Public ordinary functions
fieldspec-plist: Public ordinary functions
Function, escape-value: Private ordinary functions
Function, fieldspec-label: Public ordinary functions
Function, fieldspec-name: Public ordinary functions
Function, fieldspec-plist: Public ordinary functions
Function, render-checkbox: Private ordinary functions
Function, render-field: Public ordinary functions
Function, render-password-input: Private ordinary functions
Function, render-select: Private ordinary functions
Function, render-static: Private ordinary functions
Function, render-text-input: Private ordinary functions
Function, validate-boolean: Private ordinary functions
Function, validate-field: Public ordinary functions
Function, validate-fields: Public ordinary functions
Function, validate-option: Private ordinary functions
Function, validate-string: Private ordinary functions

R
render-checkbox: Private ordinary functions
render-field: Public ordinary functions
render-password-input: Private ordinary functions
render-select: Private ordinary functions
render-static: Private ordinary functions
render-text-input: Private ordinary functions

V
validate-boolean: Private ordinary functions
validate-field: Public ordinary functions
validate-fields: Public ordinary functions
validate-option: Private ordinary functions
validate-string: Private ordinary functions

Jump to:   E   F   R   V  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables


Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   F   P   S   W  
Index Entry  Section

F
File, file-type.lisp: The whofields/core/all/file-type․lisp file
File, file-type.lisp: The whofields/core/fieldspec/file-type․lisp file
File, file-type.lisp: The whofields/core/render/file-type․lisp file
File, file-type.lisp: The whofields/core/validate/file-type․lisp file
File, whofields.asd: The whofields/whofields․asd file
file-type.lisp: The whofields/core/all/file-type․lisp file
file-type.lisp: The whofields/core/fieldspec/file-type․lisp file
file-type.lisp: The whofields/core/render/file-type․lisp file
file-type.lisp: The whofields/core/validate/file-type․lisp file

P
Package, whofields/core/all: The whofields/core/all package
Package, whofields/core/fieldspec: The whofields/core/fieldspec package
Package, whofields/core/render: The whofields/core/render package
Package, whofields/core/validate: The whofields/core/validate package

S
System, whofields: The whofields system
System, whofields/core/all: The whofields/core/all system
System, whofields/core/fieldspec: The whofields/core/fieldspec system
System, whofields/core/render: The whofields/core/render system
System, whofields/core/validate: The whofields/core/validate system

W
whofields: The whofields system
whofields.asd: The whofields/whofields․asd file
whofields/core/all: The whofields/core/all system
whofields/core/all: The whofields/core/all package
whofields/core/fieldspec: The whofields/core/fieldspec system
whofields/core/fieldspec: The whofields/core/fieldspec package
whofields/core/render: The whofields/core/render system
whofields/core/render: The whofields/core/render package
whofields/core/validate: The whofields/core/validate system
whofields/core/validate: The whofields/core/validate package

Jump to:   F   P   S   W