((section 2 "Outdated egg!" (p "This is an egg for CHICKEN 4, the unsupported old release.  You're almost certainly looking for " (int-link "/eggref/5/autoform" "the CHICKEN 5 version of this egg") ", if it exists.") (p "If it does not exist, there may be equivalent functionality provided by another egg; have a look at the " (link "https://wiki.call-cc.org/chicken-projects/egg-index-5.html" "egg index") ". Otherwise, please consider porting this egg to the current version of CHICKEN.")) (section 2 "autoform" (toc) (section 3 "Description" (p "Autoform generates [X]HTML forms with javascript validators out of database structures.") (p "Warning: this is alpha code.  The API and the behavior of this extension is subject to change.")) (section 3 "Author" (p (int-link "/users/mario-domenech-goulart" "Mario Domenech Goulart"))) (section 3 "Requirements" (p "None") (p "For real use, a javascript validator module and a database support module is required.  See " (int-link "/eggref/4/autoform-jquery" "autoform-jquery") " and " (int-link "/eggref/4/autoform-jquery" "autoform-postgresql") ".")) (section 3 "Procedures" (def (sig (procedure "(autoform db-table conn #!key keyword-parameters)" (id autoform))) (p "The " (tt "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): " (tt "'html") " or " (tt "'javascript") ".  When given " (tt "'html") ", it returns the [X]HTML code for the form.  When given " (tt "'javascript") ", it returns the javascript fields validators for the form (you'll need a javascript validator module for javascript validators).") (p "The following keyword parameters are available:") (dl (dt (tt "extra-fields")) (dd "a list of extra fields to be rendered (i.e., fields which don't exist in the given table).  See the " (tt "db-field") " record.  The default value is " (tt "'()") ".") (dt (tt "close-connection")) (dd "a boolean which indicates whether the database connection should be closed by " (tt "autoform") ".  The default value is " (tt "#f") ".") (dt (tt "labels")) (dd "an alist mapping database field names (symbols) to more meaningful labels (strings).  Example:")) (highlight scheme "labels: '((user . \"User name\") (address . \"Address\"))") (p "The default value is " (tt "'()") ".") (dl (dt (tt "widgets")) (dd "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.")) (highlight scheme "widgets: '((user . ,(lambda (var) var)))") (p "The default value is " (tt "'()") ".") (dl (dt (tt "default-values")) (dd "an alist mapping database field names (symbols) to default values to be used when rendering the form.  The default value is " (tt "'()") ".") (dt "force-mandatory") (dd "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 " (tt "'()") ".") (dt (tt "disabled-fields")) (dd "a list of field names (symbols) to be rendered as disabled. The default value is " (tt "'()") ".") (dt (tt "read-only-fields")) (dd "a list of field names (symbols) to be rendered as read-only. The default value is " (tt "'()") ".") (dt (tt "password-fields")) (dd "a list of field names (symbols) to be rendered as password input boxes. The default value is " (tt "'()") ".") (dt (tt "form-method")) (dd "the HTTP method (a symbol) to be used for the form submission.  The default value is " (tt "'post") ".") (dt (tt "form-action")) (dd "the form action (a string or " (tt "#f") ").  The default value is " (tt "#f") ".") (dt (tt "submit-label")) (dd "the label (a string or " (tt "#f") ") for the submit widget. The default value is " (tt "#f") ".") (dt (tt "layout")) (dd "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 " (tt "#f") ".") (dt (tt "list-layout")) (dd "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 " (tt "#f") ".") (dt (tt "tabular-layout")) (dd "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 " (tt "#f") ".") (dt (tt "mandatory-indicator")) (dd "an one-argument procedure (the field label) which generates text to indicate which fields are mandatory.  The default value is " (tt "(lambda (_) (string-append _ \" (*)\"))") ".")) (p "Unless when explicitly set by the " (tt "widgets") " keyword parameter, the database fields are rendered according to their types.  Autoform considers the following mapping:") (table (tr "\n" (td (b "Database type")) "\n" (td (b "Widget")) "\n") "\n\n" (tr "\n" (td (tt "text")) "\n" (td "[X]HTML textarea") "\n") "\n\n" (tr "\n" (td (tt "hidden") " (not actually a db type, but can be used by " (tt "make-db-field") ")") "\n" (td "[X]HTML hidden input") "\n") "\n\n" (tr "\n" (td (tt "password") " (not actually a db type, but can be used by " (tt "make-db-field") ")") "\n" (td "[X]HTML password input") "\n") "\n\n" (tr "\n" (td (tt "boolean")) "\n" (td "[X]HTML checkbox input") "\n") "\n\n" (tr "\n" (td (tt "timestamp*") ", " (tt "date*")) "\n" (td "[X]HTML text input") "\n") "\n\n" (tr "\n" (td "any other type") "\n" (td "[X]HTML text input") "\n") "\n") (p "Usage example:") (highlight scheme "(use autoform autoform-jquery autoform-postgresql html-utils)\n\n...\n\n(let ((form-obj\n       (autoform \"users\" ;; the table name\n                 (db-connection) ;; the database connection\n                 labels: '((name . \"Name: \") ;; pretty labels\n                           (gender . \"Gender: \"))\n                 widgets: `(gender . ,(lambda (var)  ;; HTML select for the gender field\n                                        (combo-box var '(Male Female))))\n                 layout: '(name gender)))) ;; tableless layout\n\n  (form-obj 'javascript) ;; return the javascript code to validate the form data\n  (form-obj 'html)) ;; return the HTML code for the form")) (def (sig (procedure "(make-db-field type maxlen mandatory?)" (id make-db-field))) (p "Return a db-field object which can be used with " (tt "autoform") "'s " (tt "extra-fields") " keyword parameter.") (p (tt "type") " (a string) can be any valid database type (e.g., " (tt "\"boolean\"") ", " (tt "\"text\"") ") or the special ones: " (tt "\"password\"") " and " (tt "\"hidden\"") ".") (p (tt "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., " (tt "\"boolean\"") "), " (tt "#f") " can be used.") (p (tt "mandatory?") " is a boolean to indicate whether the field is mandatory."))) (section 3 "License" (p "BSD")) (section 3 "Version history" (dl (dt "0.2") (dd "Added required eggs to the .meta file (thanks to Stephen Eilert for reporting this).") (dt "0.1") (dd "Initial release")))))