You are looking at historical revision 23632 of this page. It may differ significantly from its current revision.

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

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

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
[procedure] (make-db-field type maxlen mandatory?)

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