Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Formbuilder is a small graphical interface for letting users build their own webforms.
JavaScript CoffeeScript CSS

This branch is 8 commits behind dobtco:gh-pages

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
dist
src
test
vendor
.gitignore
Gruntfile.coffee
LICENSE.md
README.md
bower.json
formbuilder.sublime-project
index.html
mobile_friendly.html
package.json

README.md

Formbuilder.js

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.templates are compiled Underscore.js templates that are used to render the Formbuilder interface. You can see these individual files in the ./templates directory, but if you're including formbuilder.js, you don't need to worry about them.

  • Formbuilder.fields are 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.

  1. npm install
  2. bower install
  3. grunt watch
  4. open index.html and you're all set!

License

MIT

Something went wrong with that request. Please try again.