Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
springform - npm Package Compare versions
Comparing version 0.1.0 to 0.1.1
@@ -44,3 +44,3 @@ // Generated by CoffeeScript 1.7.1 | ||
| this.formError = errors.formError; | ||
| this.fieldErrors = errors.fieldErrors || []; | ||
| this.fieldErrors = errors.fieldErrors || {}; | ||
| return this; | ||
@@ -47,0 +47,0 @@ } else { |
| { | ||
| "name": "springform", | ||
| "version": "0.1.0", | ||
| "version": "0.1.1", | ||
| "description": "For cheesecake and full-stack form processing", | ||
@@ -5,0 +5,0 @@ "author": "Good Eggs <open-source@goodeggs.com>", |
116
README.md
@@ -1,9 +0,9 @@ | ||
| springform [](http://badge.fury.io/js/springform) [](https://travis-ci.org/goodeggs/springform) | ||
| Springform [](http://badge.fury.io/js/springform) [](https://travis-ci.org/goodeggs/springform) | ||
| ============== | ||
| For cheesecake and full-stack form processing. | ||
| Full-stack javascript form processing. | ||
| Spring form is minimial, it's mostly convetion. It supplies just the right hooks to validate forms in the browser, submit them to a server, validate in node, and show the resulting errors. | ||
| Springform is a minimial (mostly convetion) [Presenter](http://en.wikipedia.org/wiki/Model_View_Presenter) or [View Model](http://en.wikipedia.org/wiki/Model_View_ViewModel) with just the right hooks to validate forms in the browser, submit them to a server, validate in node, and show the resulting errors. | ||
| Create just one form: | ||
| Create just one form with a chainable interface: | ||
| ```js | ||
@@ -25,10 +25,5 @@ var Springform = require('springform') | ||
| Or setup a prototype chain for a whole class of forms: | ||
| Or setup a prototype chain for a whole class of forms using a declarative syntax: | ||
| ```coffee | ||
| class RobotForm extends Springform | ||
| fields: [ | ||
| {name: 'color'} | ||
| {name: 'sound', label: 'What noise does it make?'} | ||
| ] | ||
| validators: [ | ||
@@ -42,6 +37,6 @@ Springform.required 'color' | ||
| (form, done) -> | ||
| if Robot.count {sound: form.data.sound}, (err, count) -> | ||
| Robot.count {sound: form.data.sound}, (err, count) -> | ||
| if count | ||
| form.formError = 'Another robot already makes that sound' | ||
| done(err) | ||
| done() | ||
| ] | ||
@@ -80,2 +75,3 @@ ``` | ||
| } | ||
| done() | ||
| } | ||
@@ -90,3 +86,97 @@ }) | ||
| ------------------ | ||
| Springform doesn't do this. Form markup is usually application specific, so you'll likely need to roll your own template helpers, but [ribosprite](http://github.com/hurrymaplelad/ribosprite) should get you started. | ||
| Springform doesn't do this. You might think of a Springform as a [Presenter](http://en.wikipedia.org/wiki/Model_View_Presenter) or [View Model](http://en.wikipedia.org/wiki/Model_View_ViewModel) that you can use to generate application specific form markup, and that you can bind to. [Ribosprite](http://github.com/hurrymaplelad/ribosprite) is an example to get you started. | ||
| Error Representation | ||
| -------------------- | ||
| Springforms pass around error messages with this structure: | ||
| ```js | ||
| { | ||
| formError: < ... >, | ||
| fieldErrors: { | ||
| <fieldName>: < ... >, | ||
| <otherFieldName>: < ... > | ||
| } | ||
| } | ||
| ``` | ||
| You'll get an object like this representing the forms current errors by calling `form.errors()`. If you format a JSON response with this structure, you can pass the reponse directly to the the errors method (`form.errors(res.body)`) to set errors on the form. | ||
| There a couple useful conventions for the values in the errors object. The simplest is to set a user-facing error message: | ||
| ```js | ||
| {formError: "Oops... Something went wrong..."} | ||
| ``` | ||
| To flag a field as having problem without adding a message, use Boolean `true`: | ||
| ```js | ||
| {fieldErrors: {sound: true}} | ||
| ``` | ||
| If you need to localize later, or you'd rather just keep the messages client-side, send a code: | ||
| ```js | ||
| {fieldErrors: {sound: 'required'}} | ||
| ``` | ||
| Validators | ||
| ---------- | ||
| Validators are functions with the signature `(form, [done])`. Validators in Springform have two important responsiblities: | ||
| 1. They set or select a user-facing error messages. | ||
| 2. They decide if messages are displayed near a single field, or apply to the whole form. | ||
| These two reponsibilities are application specific. One app might list all required fields at the top of the form, another might flag each missing field individually. You should definitely compose your validators using existing libraries (like [chriso/validator.js](https://github.com/chriso/validator.js)), but you'll need to add the two responsibilities above following the conventions of your app. | ||
| Validators can by syncronous or asyncronous. | ||
| #### Simple | ||
| The simplest validators are syncronous. They just assign error messages to the passed in form: | ||
| ```js | ||
| function(form) { | ||
| if(form.data.color != 'red') { | ||
| form.fieldErrors.color = 'Pick a better color' | ||
| } | ||
| } | ||
| ``` | ||
| #### Async | ||
| If your validator does something slow like talk to the database or make a network request, accept a second `done` argument and call it when you're done: | ||
| ```js | ||
| function(form, done) { | ||
| Robot.count({sound: form.data.sound}, function(err, count) { | ||
| if(count) { | ||
| form.formError = 'Another robot already makes that sound' | ||
| } | ||
| done() | ||
| }); | ||
| } | ||
| ``` | ||
| API | ||
| --- | ||
| #### bind(data) | ||
| Chainable sugar to set `form.data`. Feel free to set form.data directly if you don't need chainability. | ||
| #### hasErrors() | ||
| Returns true if `formError` or any `fieldErrors[*]` is truthy. | ||
| #### validate([done]) | ||
| Clear `formError` and `fieldErrors` then run all the `validators`. You can always pass a callback, to be called when all validators have finished. It's an especially good idea if any of your validators are async. | ||
| #### validator(validatorFn) | ||
| Chainable sugar to push a [validator function](#validators) onto `validators` to be run when `validate()` is called. | ||
| #### validators | ||
| An array of [validator function](#validators) to run when `validate()` is called. You can set `validators` directly, set it on a prototype, or call `validator()` to add validators one at a time. | ||
| #### submit([event]) | ||
| Call `process()` and set the `processing` flag while it's running. Calls `preventDefault()` on the passed in event if used as an event listener. | ||
| #### process(done) | ||
| An async function that does the work of submitting the form. Could be an Ajax POST, a model.save(), or something else entirely. Be sure to call `done` if you want to unlock form re-submission. Processors frequently call some combination of `validate()`, `errors({...})`, and `hasErrors()`. Define this function on an instance, on a prototype, or pass it in to `processor()`. | ||
| #### processor(processorFn) | ||
| Chainable sugar to set `process`. | ||
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by25.89%
19979
- Number of lines in readme file
- increased by101.12%
179
No dependency changes