@@ -8,7 +8,9 @@ Constructing a good form by hand is a lot of work. Popular frameworks like
88Ruby on Rails and Django contain code to make this process less painful.
99This module is an attempt to provide the same sort of helpers for node.js.
1010
11- npm install forms
11+ ``` shell
12+ $ npm install forms
13+ ```
1214
1315## Contribute
1416
@@ -30,113 +32,123 @@ bug reports, or advice. Especially on the following key areas:
3032* [ ivanquirino] ( https://github.com/ivanquirino )
3133* [ richardngn] ( https://github.com/richardngn )
3234* [ caulagi] ( https://github.com/caulagi )
33- * …and 27 more
35+ * …and [ many more] ( https://github.com/caolan/forms/graphs/contributors )
3436
3537## Example
3638
3739Creating an example registration form:
3840
39- var forms = require('forms'),
40- fields = forms.fields,
41- validators = forms.validators;
42-
43- var reg_form = forms.create({
44- username: fields.string({ required: true }),
45- password: fields.password({ required: validators.required('You definitely want a password') }),
46- confirm: fields.password({
47- required: validators.required('don\'t you know your own password?'),
48- validators: [validators.matchField('password')]
49- }),
50- email: fields.email()
51- });
41+ ``` javascript
42+ var forms = require (' forms' );
43+ var fields = forms .fields ;
44+ var validators = forms .validators ;
45+
46+ var reg_form = forms .create ({
47+ username: fields .string ({ required: true }),
48+ password: fields .password ({ required: validators .required (' You definitely want a password' ) }),
49+ confirm: fields .password ({
50+ required: validators .required (' don\' t you know your own password?' ),
51+ validators: [validators .matchField (' password' )]
52+ }),
53+ email: fields .email ()
54+ });
55+ ```
5256
5357Rendering a HTML representation of the form:
5458
55- reg_form.toHTML();
59+ ``` javascript
60+ reg_form .toHTML ();
61+ ```
5662
5763Would produce:
5864
59- <div class="field required">
60- <label for="id_username">Username</label>
61- <input type="text" name="username" id="id_username" value="test" />
62- </div>
63- <div class="field required">
64- <label for="id_password">Password</label>
65- <input type="password" name="password" id="id_password" value="test" />
66- </div>
67- <div class="field required">
68- <label for="id_confirm">Confirm</label>
69- <input type="password" name="confirm" id="id_confirm" value="test" />
70- </div>
71- <div class="field">
72- <label for="id_email">Email</label>
73- <input type="text" name="email" id="id_email" />
74- </div>
65+ ``` html
66+ <div class =" field required" >
67+ <label for =" id_username" >Username</label >
68+ <input type =" text" name =" username" id =" id_username" value =" test" />
69+ </div >
70+ <div class =" field required" >
71+ <label for =" id_password" >Password</label >
72+ <input type =" password" name =" password" id =" id_password" value =" test" />
73+ </div >
74+ <div class =" field required" >
75+ <label for =" id_confirm" >Confirm</label >
76+ <input type =" password" name =" confirm" id =" id_confirm" value =" test" />
77+ </div >
78+ <div class =" field" >
79+ <label for =" id_email" >Email</label >
80+ <input type =" text" name =" email" id =" id_email" />
81+ </div >
82+ ```
7583
7684You'll notice you have to provide your own form tags and submit button, its
7785more flexible this way ;)
7886
7987Handling a request:
8088
81- function myView(req, res) {
82-
83- reg_form.handle(req, {
84- success: function (form) {
85- // there is a request and the form is valid
86- // form.data contains the submitted data
87- },
88- error: function (form) {
89- // the data in the request didn't validate,
90- // calling form.toHTML() again will render the error messages
91- },
92- empty: function (form) {
93- // there was no form data in the request
94- }
95- });
96-
97- }
89+ ``` javascript
90+ function myView ( req , res ) {
91+ reg_form .handle (req, {
92+ success : function (form ) {
93+ // there is a request and the form is valid
94+ // form.data contains the submitted data
95+ },
96+ error : function (form ) {
97+ // the data in the request didn't validate,
98+ // calling form.toHTML() again will render the error messages
99+ },
100+ empty : function (form ) {
101+ // there was no form data in the request
102+ }
103+ });
104+ }
105+ ```
98106
99107That's it! For more detailed / working examples look in the example folder.
100108An example server using the form above can be run by doing:
101109
102- node example/simple.js
110+ ``` shell
111+ $ node example/simple.js
112+ ```
103113
104114### Bootstrap compatible output
105115For integrating with Twitter bootstrap 3 (horizontal form), this is what you need to do:
106116
107- var my_form = forms.create({
108- title: fields.string ({
109- required: true,
110- widget: widgets.text({ classes: ['input-with-feedback'] }) ,
111- errorAfterField: true ,
112- cssClasses: {
113- label: ['control-label col col-lg-3']
114- }
115- }),
116-
117- description: fields.string({
118- errorAfterField: true,
119- widget: widgets.text({ classes: ['input-with-feedback'] }),
120- cssClasses: {
121- label: ['control-label col col-lg-3']
122- }
123- })
124- });
125-
126- var bootstrapField = function (name, object) {
127-
128- object.widget.classes = object.widget.classes || [] ;
129- object.widget.classes.push('form-control');
130-
131- var label = object.labelHTML(name) ;
132- var error = object.error ? '<div class="alert alert-error">' + object.error + '</div>' : '' ;
133- var widget = object.widget.toHTML(name, object) ;
134- return '<div class="form-group">' + label + widget + error + '</div>' ;
135- };
117+ ``` javascript
118+ var my_form = forms . create ({
119+ title : fields . string ({
120+ required : true ,
121+ widget : widgets . text ({ classes : [ ' input-with-feedback ' ] }) ,
122+ errorAfterField : true ,
123+ cssClasses : {
124+ label : [ ' control-label col col-lg-3 ' ]
125+ }
126+ }),
127+ description: fields .string ({
128+ errorAfterField: true ,
129+ widget: widgets .text ({ classes: [' input-with-feedback' ] }),
130+ cssClasses: {
131+ label: [' control-label col col-lg-3' ]
132+ }
133+ })
134+ });
135+
136+ var bootstrapField = function (name , object ) {
137+ object . widget . classes = object . widget . classes || [];
138+ object .widget .classes . push ( ' form-control ' ) ;
139+
140+ var label = object . labelHTML (name);
141+ var error = object . error ? ' <div class="alert alert-error"> ' + object .error + ' </div> ' : ' ' ;
142+ var widget = object .widget . toHTML (name, object) ;
143+ return ' <div class="form-group"> ' + label + widget + error + ' </div> ' ;
144+ } ;
145+ ```
136146
137147And while rendering it:
138148
139- form.toHTML(bootstrapField);
149+ ``` javascript
150+ form .toHTML (bootstrapField);
151+ ```
140152
141153## Available types
142154
@@ -209,31 +221,37 @@ A more detailed look at the methods and attributes available. Most of these
209221you will not need to use directly.
210222
211223### forms.create(fields)
224+
212225Converts a form definition (an object literal containing field objects) into a
213226form object.
214227
215228#### forms.create(fields, options)
229+
216230Forms can be created with an optional "options" object as well.
231+
217232#### Supported options:
218233* ` validatePastFirstError ` : ` true ` , otherwise assumes ` false `
219- * If ` false ` , the first validation error will halt form validation.
220- * If ` true ` , all fields will be validated.
234+ * If ` false ` , the first validation error will halt form validation.
235+ * If ` true ` , all fields will be validated.
221236
222237
223238### Form object
224239
225240#### Attributes
226241
227- * fields - Object literal containing the field objects passed to the create
242+ * `` fields `` - Object literal containing the field objects passed to the create
228243 function
229244
230245#### form.handle(req, callbacks)
246+
231247Inspects a request or object literal and binds any data to the correct fields.
232248
233249#### form.bind(data)
250+
234251Binds data to correct fields, returning a new bound form object.
235252
236253#### form.toHTML(iterator)
254+
237255Runs toHTML on each field returning the result. If an iterator is specified,
238256it is called for each field with the field name and object as its arguments,
239257the iterator's results are concatenated to create the HTML output, allowing
@@ -246,19 +264,22 @@ Contains the same methods as the unbound form, plus:
246264
247265#### Attributes
248266
249- * data - Object containing all the parsed data keyed by field name
250- * fields - Object literal containing the field objects passed to the create
267+ * `` data `` - Object containing all the parsed data keyed by field name
268+ * `` fields `` - Object literal containing the field objects passed to the create
251269 function
252270
253271#### form.validate(callback)
272+
254273Calls validate on each field in the bound form and returns the resulting form
255274object to the callback.
256275
257276#### form.isValid()
277+
258278Checks all fields for an error attribute. Returns false if any exist, otherwise
259279returns true.
260280
261281#### form.toHTML(iterator)
282+
262283Runs toHTML on each field returning the result. If an iterator is specified,
263284it is called for each field with the field name and object as its arguments,
264285the iterator's results are concatenated to create the HTML output, allowing
@@ -269,17 +290,17 @@ for highly customised markup.
269290
270291#### Attributes
271292
272- * label - Optional label text which overrides the default
273- * required - Boolean describing whether the field is mandatory
274- * validators - An array of functions which validate the field data
275- * widget - A widget object to use when rendering the field
276- * id - An optional id to override the default
277- * choices - A list of options, used for multiple choice fields
278- * cssClasses - A list of CSS classes for label and field wrapper
279- * hideError - if true, errors won't be rendered automatically
280- * errorAfterField - if true, the error message will be displayed after the field, rather than before
281- * fieldsetClasses - for widgets with a fieldset (multipleRadio and multipleCheckbox), set classes for the fieldset
282- * legendClasses - for widgets with a fieldset (multipleRadio and multipleCheckbox), set classes for the fieldset's legend
293+ * `` label `` - Optional label text which overrides the default
294+ * `` required `` - Boolean describing whether the field is mandatory
295+ * `` validators `` - An array of functions which validate the field data
296+ * `` widget `` - A widget object to use when rendering the field
297+ * `` id `` - An optional id to override the default
298+ * `` choices `` - A list of options, used for multiple choice fields
299+ * `` cssClasses `` - A list of CSS classes for label and field wrapper
300+ * `` hideError `` - if true, errors won't be rendered automatically
301+ * `` errorAfterField `` - if true, the error message will be displayed after the field, rather than before
302+ * `` fieldsetClasses `` - for widgets with a fieldset (multipleRadio and multipleCheckbox), set classes for the fieldset
303+ * `` legendClasses `` - for widgets with a fieldset (multipleRadio and multipleCheckbox), set classes for the fieldset's legend
283304
284305#### field.parse(rawdata)
285306
@@ -324,9 +345,9 @@ _same as field object, but with a few extensions_
324345
325346#### Attributes
326347
327- * value - The raw value from the request data
328- * data - The request data coerced to the correct format for this field
329- * error - An error message if the field fails validation
348+ * `` value `` - The raw value from the request data
349+ * `` data `` - The request data coerced to the correct format for this field
350+ * `` error `` - An error message if the field fails validation
330351
331352#### validate(callback)
332353
@@ -339,9 +360,9 @@ fails, the resulting message is stored in the field's error attribute.
339360
340361#### Attributes
341362
342- * classes - Custom classes to add to the rendered widget
343- * labelClasses - Custom classes to add to the choices label when applicable (multipleRadio and multipleCheckbox)
344- * type - A string representing the widget type, e.g. 'text' or 'checkbox'
363+ * `` classes `` - Custom classes to add to the rendered widget
364+ * `` labelClasses `` - Custom classes to add to the choices label when applicable (multipleRadio and multipleCheckbox)
365+ * `` type `` - A string representing the widget type, e.g. 'text' or 'checkbox'
345366
346367#### toHTML(name, field)
347368
0 commit comments