source: project/wiki/eggref/4/autoform @ 32713

Last change on this file since 32713 was 32713, checked in by arthurmaciel, 4 years ago

Included a table of contents.

File size: 6.0 KB
Line 
1== autoform
2
3[[toc:]]
4
5=== Description
6
7Autoform generates [X]HTML forms with javascript validators out of database structures.
8
9Warning: this is alpha code.  The API and the behavior of this extension is subject to change.
10
11=== Author
12
13[[/users/mario-domenech-goulart|Mario Domenech Goulart]]
14
15
16=== Requirements
17
18None
19
20For real use, a javascript validator module and a database support module is required.  See [[/eggref/4/autoform-jquery|autoform-jquery]] and [[/eggref/4/autoform-jquery|autoform-postgresql]].
21
22
23=== Procedures
24
25<procedure>(autoform db-table conn #!key keyword-parameters)</procedure>
26
27The {{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).
28
29The following keyword parameters are available:
30
31; {{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 {{'()}}.
32
33; {{close-connection}} : a boolean which indicates whether the database connection should be closed by {{autoform}}.  The default value is {{#f}}.
34
35
36; {{labels}} : an alist mapping database field names (symbols) to more meaningful labels (strings).  Example:
37
38<enscript highlight=scheme>
39labels: '((user . "User name") (address . "Address"))
40</enscript>
41
42The default value is {{'()}}.
43
44; {{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.
45
46<enscript highlight=scheme>
47widgets: '((user . ,(lambda (var) var)))
48</enscript>
49
50The default value is {{'()}}.
51
52; {{default-values}} : an alist mapping database field names (symbols) to default values to be used when rendering the form.  The default value is {{'()}}.
53
54; 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 {{'()}}.
55
56
57; {{disabled-fields}} : a list of field names (symbols) to be rendered as disabled. The default value is {{'()}}.
58
59; {{read-only-fields}} : a list of field names (symbols) to be rendered as read-only. The default value is {{'()}}.
60
61; {{password-fields}} : a list of field names (symbols) to be rendered as password input boxes. The default value is {{'()}}.
62
63; {{form-method}} : the HTTP method (a symbol) to be used for the form submission.  The default value is {{'post}}.
64
65; {{form-action}} : the form action (a string or {{#f}}).  The default value is {{#f}}.
66
67; {{submit-label}} : the label (a string or {{#f}}) for the submit widget. The default value is {{#f}}.
68
69; {{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}}.
70
71; {{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}}.
72
73; {{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}}.
74
75; {{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 _ " (*)"))}}.
76
77
78Unless when explicitly set by the {{widgets}} keyword parameter, the database fields are rendered according to their types.  Autoform considers the following mapping:
79
80<table>
81<tr>
82<td>'''Database type'''</td>
83<td>'''Widget'''</td>
84</tr>
85
86<tr>
87<td>{{text}}</td>
88<td>[X]HTML textarea</td>
89</tr>
90
91<tr>
92<td>{{hidden}} (not actually a db type, but can be used by {{make-db-field}})</td>
93<td>[X]HTML hidden input</td>
94</tr>
95
96<tr>
97<td>{{password}} (not actually a db type, but can be used by {{make-db-field}})</td>
98<td>[X]HTML password input</td>
99</tr>
100
101<tr>
102<td>{{boolean}}</td>
103<td>[X]HTML checkbox input</td>
104</tr>
105
106<tr>
107<td>{{timestamp*}}, {{date*}}</td>
108<td>[X]HTML text input</td>
109</tr>
110
111<tr>
112<td>any other type</td>
113<td>[X]HTML text input</td>
114</tr>
115
116</table>
117
118Usage example:
119
120<enscript highlight=scheme>
121(use autoform autoform-jquery autoform-postgresql html-utils)
122
123...
124
125(let ((form-obj
126       (autoform "users" ;; the table name
127                 (db-connection) ;; the database connection
128                 labels: '((name . "Name: ") ;; pretty labels
129                           (gender . "Gender: "))
130                 widgets: `(gender . ,(lambda (var)  ;; HTML select for the gender field
131                                        (combo-box var '(Male Female))))
132                 layout: '(name gender)))) ;; tableless layout
133
134  (form-obj 'javascript) ;; return the javascript code to validate the form data
135  (form-obj 'html)) ;; return the HTML code for the form
136</enscript>
137
138<procedure>(make-db-field type maxlen mandatory?)</procedure>
139
140Return a db-field object which can be used with {{autoform}}'s {{extra-fields}} keyword parameter.
141
142{{type}} (a string) can be any valid database type (e.g., {{"boolean"}}, {{"text"}}) or the special ones: {{"password"}} and {{"hidden"}}.
143
144{{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.
145
146{{mandatory?}} is a boolean to indicate whether the field is mandatory.
147
148
149
150=== License
151
152BSD
153
154
155=== Version history
156
157; 0.2 : Added required eggs to the .meta file (thanks to Stephen Eilert for reporting this).
158; 0.1 : Initial release
Note: See TracBrowser for help on using the repository browser.