The carbon-form module provides easy-to-use forms in your projects. It is a complete solution which not only provides rendering but filtering and validation too. It packs all the logic behind HTML forms and it abstracts a lot of work so that you can focus on building awesome web applications and best of all it allows you to define the layout and style your forms any way you want them.
If you have ever used Zend_Form before you're going to be familiar with the syntax and if not just keep reading.
npm install carbon-form [--save]
The usage is pretty simple. You create a form and then add elements to it. For each element you define a set of options such as name, label, filters, validators, HTML attributes etc. The following example should present most of carbon-form features.
First you need to define your form and elements that it will contain.
var Form = require("carbon-form");
var Filter = require("carbon-filter");
var Validate = require("carbon-validate");
module.exports = exports = function(options) {
var form = new Form(options);
form.setAction("/signup");
form.setViewScriptFile("forms/signup.jade");
form.addElements([
new Form.Element.Text("name", {
label: "Name",
attribs: {
class: "text-field"
},
filters: [
new Filter.StringTrim()
],
validators: [
new Validate.NotEmpty({
messages: {
"is_empty": "Name is required"
});
]
}),
new Form.Element.Text("email_address", {
label: "Email address",
attribs: {
class: "text-field"
},
filters: [
new Filter.StringTrim()
],
validators: [
new Validate.NotEmpty({
messages: {
"is_empty": "Email address is required"
}
}),
new Validate.StringLength({
max: 255,
messages: {
"too_long": "Email address can't be longer than %max% characters"
}
}),
new Validate.EmailAddress(),
new Validate.DbNoRecordExists({
adapter: "mongoose",
collection: "users",
field: "email_address",
messages: {
"record_found": "Email address is already in the database"
}
})
]
}),
new Form.Element.Password("password1", {
label: "Password",
attribs: {
class: "text-field"
},
validators: [
new Validate.NotEmpty({
messages: {
"is_empty": "Password is required"
}
}),
new Validate.StringLength({
min: 6,
messages: {
too_short: "Password must be at least %min% characters long"
}
})
]
}),
new Form.Element.Password("password2", {
label: "Repeat password",
attribs: {
class: "form-control"
},
validators: [
new Validate.NotEmpty({
messages: {
"is_empty": "Repeated password is required"
}
}),
new Validate.Identical({
token: "password1",
messages: {
"not_same": "Passwords do not match"
}
})
]
}),
new Form.Element.Button("submit", {
content: "Sign up",
attribs: {
class: "btn btn-red",
type: "submit"
}
})
]);
return form;
}Since carbon-form gives you freedom to style your own forms any way you wish, you can define form layout in the separate file and then tell to carbon-form where to look for this file. When the form renders it will use this layout as a template.
.form-group
div
label(for="#{elements.name.getName()}")
!= elements.name.getLabel()
div
!= elements.name.render()
.form-group
div
label(for="#{elements.email_address.getName()}")
!= elements.email_address.getLabel()
div
!= elements.email_address.render()
.form-group
div
label(for="#{elements.password1.getName()}")
!= elements.password1.getLabel()
div
!= elements.password1.render()
.form-group
div
label(for="#{elements.password2.getName()}")
!= elements.password2.getLabel()
div
!= elements.password2.render()
.form-group
div
!= elements.submit.render() This example features carbon-framework just to make it easier for you to understand how carbon-form works in reality. Of course you can use carbon-form with any other Node.js framework or no framework at all.
module.exports = function() {
return {
signupAction: {
post: function(req, res) {
var postData = req.body;
var form = require("./forms/signup-form")({
viewiewScriptPaths: res.viewPaths
});
form.isValid(postData, function(err, values) {
if (err)
{
form.render(function(err) {
// Now in the view all you have to do is call `!= form.render()`
// (if you're using Jade engine) and it will return rendered form
// as HTML all together with all errored fields
res.render("scripts/signup", {
formSignup: form
});
});
}
else
{
// Form validation is successful and argument `values` now contains all
// field values which are filtered and validated and therefor safe
// to be inserted into the database
res.redirect("/signup-success");
}
});
}
}
}
}The carbon-form currently supports 6 HTML form elements (Button, Checkbox, Hidden, Password, Text, Textarea) and 4 extended elements (EmailAddress, Link, Recaptcha, Switch).
Depending on how you organize your forms you can nest one or more forms within a single form.
var Form = require("carbon-form");
var form = new Form();
var buttons = new Form();
parentForm.addSubForm("buttons", buttons);If you're willing to contribute to this project feel free to report issues, send pull request, write tests or simply contact me - Amir Ahmetovic
This software is available under the following licenses:
- MIT