Skip to content
A javascript form generation library for node and the browser that won't get in your way.
JavaScript
Find file
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
demo
lib
test
vendor
.gitignore
.travis.yml
LICENSE
README.md
build.js
package.json

README.md

Performer Build Status

DRY up your forms like never before.

Performer has no external dependencies, works in Node or the browser (with AMD, or as an inline script), ships with full test coverage, and adheres to semantic versioning. The implementation is simple, elegant and powerful. Plugins for integration with Backbone coming soon.

v0.0.1: this is *alpha** quality software, the API is changing regularly, it is not ready for public use.*

Concepts

Blueprint: Commonly used form elements, described in JSON.

Schema: A specific form, described in JSON (referencing Blueprints).

Transformer: Functions that can modify or otherwise interact with form tags during generation (e.g. wrap with a div).

Pipeline: An array of of transformers to apply to a given HTML fragment.

Usage

Blueprints

Easily define and extend Blueprints for global re-use in your Schemas (ships with blueprint for HTML5 forms).

Create your Blueprint:
var blueprint = new Performer.Blueprints.html5();

You can skip the blueprinting process for simple forms—the built-in HTML5 blueprint has definitions for most common form elements.

Add Blueprints one at a time, or in bulk:
blueprint.add("text", {
  "tag": "input",
  "attributes": {
    "type": "text"
  }
});

blueprint.add("address", {
  "addr1": { "blueprint": "text" },
  "addr2": { "blueprint": "text" },
  "city": { "blueprint": "text" },
  "state": { "blueprint": "select" },
  "zip": { "blueprint": "number" },
});

var data = {
  "number": {
    "tag": "input",
    "attributes": {
      "type": "number"
    }
  },
  "email": {
    "tag": "input",
    "attributes": {
      "type": "email"
    }
  }
};
// WARNING: this will replace any existing blueprints that share the same key
blueprint.add_many(data);
Modify, replace, or remove an existing Blueprint:
blueprint.modify("text", {
  "attributes": {
    "className": "text_field"
  }
});

blueprint.replace("text", {"replaced": "yup"})

blueprint.remove("text");

Blueprint Usage Notes:

Anything you can put in a Schema (defined below) can be stored in a Blueprint for use across multiple forms. In the example above, a series of common fields used to display an address has been added. This can be included in any form by referencing the blueprint by name (shown below).


Schemas

Describe your form once, referencing blueprints to do the heavy lifting.

Create your Schema:
var data = {
  "contact": {
    "first": { "blueprint": "text" },
    "last": { "blueprint": "text" },
    "address": { "blueprint": "address" }
  }
};
var schema = new Performer.Schema(data);

Schema Usage Notes:

...fill this out.


Transformers

Generate form elements any way you please.

Transformers are easy to write:
var wrapper = new Performer.Transformer(function(input, helpers) {
  return input.write("<div>"+input.read()+"</div>");
});

Transformer Usage Notes:

Explain how transformers can reference attributes in schemas.

Performer ships with these transformers:

  • Performer.Transformers.Wrap
    • fieldset, label, ol, ul, li, div, p, span
  • Performer.Transformers.Sibling
    • label, legend

Pipelines

Package your transformations for re-use.

Example:
// examples here
var options = {
  pipelines: {
    tag: [
      Performer.Transformers.Sibling.label,
      Performer.Transformers.Wrap.li
    ],
    set: [
      Performer.Transformers.Wrap.ol,
      Performer.Transformers.Sibling.legend,
      Performer.Transformers.Wrap.fieldset
    ]
  }
}

Pipeline Usage Notes:

A pipeline is nothing more than an array of Transformers.


Form

Generate your forms however you like; on the server, in a browser, in conjuction with a templating engine, directly into the DOM, whatever! Build the whole thing with a single call, in sections, or tag-by-tag.

Example:
// examples here

Form Usage Notes:

...fill this out.

Something went wrong with that request. Please try again.