chickadee » autoform

autoform

Description

Autoform generates [X]HTML forms with javascript validators out of database structures.

Warning: this is alpha code. The API and the behavior of this extension is subject to change.

Author

Mario Domenech Goulart

Requirements

None

For real use, a javascript validator module and a database support module is required. See autoform-jquery and autoform-postgresql.

Procedures

(autoform db-table conn #!key keyword-parameters) procedure

The autoform procedure takes as mandatory arguments the database table (s atring) and either a database connection object or a database credentials object (see the egg documentation for the database support module you're using). It returns an one-argument procedure which accepts two arguments (symbols): 'html or 'javascript. When given 'html, it returns the [X]HTML code for the form. When given 'javascript, it returns the javascript fields validators for the form (you'll need a javascript validator module for javascript validators).

The following keyword parameters are available:

extra-fields
a list of extra fields to be rendered (i.e., fields which don't exist in the given table). See the db-field record. The default value is '().
close-connection
a boolean which indicates whether the database connection should be closed by autoform. The default value is #f.
labels
an alist mapping database field names (symbols) to more meaningful labels (strings). Example:
labels: '((user . "User name") (address . "Address"))

The default value is '().

widgets
an alist mapping database field names (symbols) to widgets (one-argument procedures). Autoform tries to pick the best widget for fields based on their type, but if you want to change it, you can use this keyword parameter.
widgets: '((user . ,(lambda (var) var)))

The default value is '().

default-values
an alist mapping database field names (symbols) to default values to be used when rendering the form. The default value is '().
force-mandatory
a list of fields (symbols) to be considered mandatory, even if the database structure doesn't require them to be mandatory. The default value is '().
disabled-fields
a list of field names (symbols) to be rendered as disabled. The default value is '().
read-only-fields
a list of field names (symbols) to be rendered as read-only. The default value is '().
password-fields
a list of field names (symbols) to be rendered as password input boxes. The default value is '().
form-method
the HTTP method (a symbol) to be used for the form submission. The default value is 'post.
form-action
the form action (a string or #f). The default value is #f.
submit-label
the label (a string or #f) for the submit widget. The default value is #f.
layout
when set, indicates that no explicit layout markup should be used (the layout will be set by CSS). Its value is a list of field names representing what fields and the order they should be rendered. The default value is #f.
list-layout
when set, indicates that an unordered [X]HTML list should be used to layout the form fields. Its value a list of field names representing what fields and the order they should be rendered. The default value is #f.
tabular-layout
when set, indicates that an [X]HTML table should be used to layout the form fields. Its value is a list of lists ofield names. The default value is #f.
mandatory-indicator
an one-argument procedure (the field label) which generates text to indicate which fields are mandatory. The default value is (lambda (_) (string-append _ " (*)")).

Unless when explicitly set by the widgets keyword parameter, the database fields are rendered according to their types. Autoform considers the following mapping:

Database type Widget
text [X]HTML textarea
hidden (not actually a db type, but can be used by make-db-field) [X]HTML hidden input
password (not actually a db type, but can be used by make-db-field) [X]HTML password input
boolean [X]HTML checkbox input
timestamp*, date* [X]HTML text input
any other type [X]HTML text input

Usage example:

(use autoform autoform-jquery autoform-postgresql html-utils)

...

(let ((form-obj
       (autoform "users" ;; the table name
                 (db-connection) ;; the database connection
                 labels: '((name . "Name: ") ;; pretty labels
                           (gender . "Gender: "))
                 widgets: `(gender . ,(lambda (var)  ;; HTML select for the gender field
                                        (combo-box var '(Male Female))))
                 layout: '(name gender)))) ;; tableless layout

  (form-obj 'javascript) ;; return the javascript code to validate the form data
  (form-obj 'html)) ;; return the HTML code for the form
(make-db-field type maxlen mandatory?) procedure

Return a db-field object which can be used with autoform's extra-fields keyword parameter.

type (a string) can be any valid database type (e.g., "boolean", "text") or the special ones: "password" and "hidden".

maxlen is the maximum length of the input for the field (for those which length makes sense). When it doesn't make sense (e.g., "boolean"), #f can be used.

mandatory? is a boolean to indicate whether the field is mandatory.

License

BSD

Version history

0.2
Added required eggs to the .meta file (thanks to Stephen Eilert for reporting this).
0.1
Initial release

Contents »