bitovi / bitovi/canui

can.ui.Validate API

Open
#13 9 comments 0 reactions 1 assignee Claimed by @moschel View on GitHub
Dominant language
JavaScript
Stars
28
Forks
23
PR merge metrics
No merged PRs in 30d

Description

## Purpose
- create some form validation widgets that hook into model's validations.
## Learn from

https://github.com/jzaefferer/jquery-validation
http://activeform.rubyforge.org/
https://docs.djangoproject.com/en/dev/ref/forms/validation/
## Markup
## Options

_preventIncorrect_: **boolean** // if true, doesn't let user continue with form until validation is fixed
_validateOnlyOnSubmit_: **boolean** // if true, only perform validations when the user clicks submit, else while using the form
## Events

_validSubmit_: We can't know for sure we're preventing the submit event before another event handler gets to it. We trigger "validSubmit" event, which users bind to instead of submit. Perform AJAX save after this event.
## Methods
## Theming
## Examples

simple form:

```

// person is a can.Observe
var formValidator = new can.ui.FormValidator($('form'), {
mapTo: person
});
```

form where name to observe attribute isn't one to one mapping:

```
var formValidator = new can.ui.FormValidator($('form'), {
mapTo:{
// can.Observe attribute sets initial state, saved to after change, validation if exists
".player.email": {observe: person, attr: "email"},
// can.compute used for setting after change, getting for initial state, validate
".player.pct": percentDone,
".sex": {observe: person, attr: "sex"},
// doesn't correspond to any can.Observe, but still needs validation
".level": function(levelVal, formData){
// if level doesn't pass, return some validation failed message
}
}
});
```

The way I see it now, there are 4 different cases to cover:
1. A form element maps to a can.Observe attribute (which already has validations)
2. A form element maps indirectly to a combination of can.Observe attributes through a can.compute (which needs to support validations)
3. A form element maps to no can.Observe attributes, but still needs validation...in this case through a function. Its arguments include this el's value and the form's data as a whole.
4. Every element in a form directly maps to a can.Observe (through the name attribute). In this case, just pass the observe in mapTo.

Need API support for all 4 cases.
## Notes
- can.compute needs to add functionality to run validates on all attributes this can.compute contains
- To support non-input widgets like can.ui.slider, as long as they trigger change, it will still work fine, just like any other input el.
- Not really sure what to do to integrate with HTML5 validations.
- @justin, what do you mean by translations? Translating the validation strings?
- Also not sure what you mean by how this works with live-binding?
- Validations should definitely be a model thing. I think a very common type of form is one that maps 1:1 with a model instance and its attributes. We need to support both though (this and non-model forms).
## Requirements
1. Map form elements to can.Observe attributes (which have validations)
2. Provide logical validation behavior as user interacts with form (do validations on submit, keyup, blur)
3. Display errors near the relevant form element and remove them when not valid
4. Cancel form submit if validation fails
## API Problems
1. Problem: Forms might be complex and represent more than one can.Observe, so providing one can.Observe won't be sufficient. Also, form element name attributes might not match exactly with a can.Observe property name.

Solution: Should the options map each input to a can.Observe object and attribute name?

Con: This would make the API verbose. This makes the simple case (a form that directly corresponds with can.Observe) harder than it needs to be.
Pro: This would make usage flexible enough to cover complex cases.

3 options:

1) APi maps form to a single can.Observe (automatically each form element -> the can.Observe of the same name)
2) API maps to a single can.Observe, but maps each form element -> an attribute name on that can.Observe
3) API maps each form element -> a can.Observe instance and an attribute name on that instance
1. Forms might have inputs that don't correspond to any can.Observe, but still need validation. Should we support this? In this case, the API would accept a validation function.

Yes, we probably should let users map a form element -> a function in the options. It'll work like can.Observe.static.validate.
1. Should we provide lots of options for customizing the error display and placement? Or keep it simple?

By default just position the error to the right of the form element. If it finds something with class="error" put it there. Or let users provide that className.
1. Users can bind to form submit. We can't know for sure we're preventing the submit event before another event handler gets to it. Therefore we might have to trigger "validSubmit" event or something similar, which users bind to and submit on.
2. Should we support async validations (for making AJAX validation checks)? We'd need to provide callback funcs for validate methods. Probably don't support this at least for now.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.