Formbuilder.js
Update 9/26/14
I'm working on a new version of formbuilder that uses formrenderer-base as a dependency. This will make it so that rendering a form for a user to fill out is as simple as plugging in your data from the builder. It's a bit of a chore to extract this stuff from Screendoor, but I hope to make some progress in the next month.
-- @ajb
Formbuilder is a graphical interface for letting users build their own webforms. Think Wufoo or Google Forms, but a lightweight component that can be integrated into your application.
Formbuilder.js only handles the client-side logic of creating a form. It will output a structured JSON representation of your form, but saving the form, rendering it on the server, and storing users' responses is all up to you. If you're using Rails, there is also Formbuilder.rb, a Rails engine that's designed to provide this server-side functionality.
Demo
Click here to see Formbuilder in action.
Basic usage
<div id='formbuilder'></div>
<script>
var formbuilder = new Formbuilder({ selector: '#formbuilder' });
</script>
See more usage examples in the wiki.
Design & Dependencies
Formbuilder itself is a pretty small codebase (6kb gzip'd javascript) but it does rely on some external libraries, namely Backbone & Rivets. We use bower to manage our dependencies, which can be seen here. I'd like to reduce some of these in the future, (especially font-awesome, because that's just silly,) but for now that's what you'll have to include.
Formbuilder consists of a few different components that all live in the Formbuilder namespace:
-
Formbuilder.templatesare compiled Underscore.js templates that are used to render the Formbuilder interface. You can see these individual files in the./templatesdirectory, but if you're includingformbuilder.js, you don't need to worry about them. -
Formbuilder.fieldsare the different kinds of inputs that users can add to their forms. We expose a simple API,Formbuilder.registerField(), that allows you to add more kinds of inputs. -
Formbuilder.views
Because of its modular nature, Formbuilder is easy to customize. Most of the configuration lives in class variables, which means you can simply override a template or method. If you have questions, feel free to open an issue -- we've tried to bridge the gap between convention and configuration, but there's no guarantee that we were successful.
Data format
Keeping with the customizable nature of Formbuilder, you are also able to modify how Formbuilder structures its JSON output. The default keypaths are:
SIZE: 'field_options.size'
UNITS: 'field_options.units'
LABEL: 'label'
FIELD_TYPE: 'field_type'
REQUIRED: 'required'
ADMIN_ONLY: 'admin_only'
OPTIONS: 'field_options.options'
DESCRIPTION: 'field_options.description'
INCLUDE_OTHER: 'field_options.include_other_option'
INCLUDE_BLANK: 'field_options.include_blank_option'
INTEGER_ONLY: 'field_options.integer_only'
MIN: 'field_options.min'
MAX: 'field_options.max'
MINLENGTH: 'field_options.minlength'
MAXLENGTH: 'field_options.maxlength'
LENGTH_UNITS: 'field_options.min_max_length_units'
Which outputs JSON that looks something like:
[{
"label": "Please enter your clearance number",
"field_type": "text",
"required": true,
"field_options": {},
"cid": "c6"
}, {
"label": "Security personnel #82?",
"field_type": "radio",
"required": true,
"field_options": {
"options": [{
"label": "Yes",
"checked": false
}, {
"label": "No",
"checked": false
}],
"include_other_option": true
},
"cid": "c10"
}, {
"label": "Medical history",
"field_type": "file",
"required": true,
"field_options": {},
"cid": "c14"
}]
Events
More coming soon...
save
var builder = new Formbuilder({ selector: '#formbuilder' });
builder.on('save', function(payload){
...
});
Questions?
Have a question about Formbuilder? Feel free to open a GitHub Issue before emailing one of us directly. That way, folks who have the same question can see our communication.
Developing
You'll need node and npm installed.
npm installbower installgrunt watch- open
index.htmland you're all set!
License
MIT