Skip to content

Commit f48344b

Browse files
committed
Improve the formatting of code blocks in the README. Closes #139.
1 parent 2919817 commit f48344b

File tree

1 file changed

+123
-102
lines changed

1 file changed

+123
-102
lines changed

README.md

Lines changed: 123 additions & 102 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,9 @@ Constructing a good form by hand is a lot of work. Popular frameworks like
88
Ruby on Rails and Django contain code to make this process less painful.
99
This 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

3739
Creating 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

5357
Rendering a HTML representation of the form:
5458

55-
reg_form.toHTML();
59+
```javascript
60+
reg_form.toHTML();
61+
```
5662

5763
Would 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

7684
You'll notice you have to provide your own form tags and submit button, its
7785
more flexible this way ;)
7886

7987
Handling 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

99107
That's it! For more detailed / working examples look in the example folder.
100108
An 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
105115
For 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

137147
And 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
209221
you will not need to use directly.
210222

211223
### forms.create(fields)
224+
212225
Converts a form definition (an object literal containing field objects) into a
213226
form object.
214227

215228
#### forms.create(fields, options)
229+
216230
Forms 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+
231247
Inspects a request or object literal and binds any data to the correct fields.
232248

233249
#### form.bind(data)
250+
234251
Binds data to correct fields, returning a new bound form object.
235252

236253
#### form.toHTML(iterator)
254+
237255
Runs toHTML on each field returning the result. If an iterator is specified,
238256
it is called for each field with the field name and object as its arguments,
239257
the 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+
254273
Calls validate on each field in the bound form and returns the resulting form
255274
object to the callback.
256275

257276
#### form.isValid()
277+
258278
Checks all fields for an error attribute. Returns false if any exist, otherwise
259279
returns true.
260280

261281
#### form.toHTML(iterator)
282+
262283
Runs toHTML on each field returning the result. If an iterator is specified,
263284
it is called for each field with the field name and object as its arguments,
264285
the 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

Comments
 (0)