The form/view API

[mchapman]

Carrying on from posts in #2 - should we / how should we share underlying data schemas across multiple forms?

Some prior art at https://github.com/Textalk/angular-schema-form/blob/development/docs/index.md#form-definitions

[bvaughn]

This is another reason I like formFor's approach of working with a POJO for validation.

• If external code wants to "extend" or override validation rules- that's fine. Just use Object.create to merge the two. We allow you to be very flexible while at the same time not having to care about how.
• If external code wants to share (global) validation rules between multiple forms or define one-offs- that's fine. Do it. So long as we get a POJO we're happy.

It seems more straight forward.

[davidlgj]

Ok so I'm not sure if this is the right issue, but I feel that I some ideas that I would like to lay out for you.

So this is my basic idea:

I'd like form-js to have a core part in vanilla-js and several "adaptors" (as @kentcdodds called them) that renders the actual forms, and it's in these adaptors that I see frameworks playing a role, with Angular 2 being the first target (The adaptors can probably be layered as well, ie. Angular2+bootstrap, Angular2+Material etc)

So what should go into core and what should go into an adaptor? This is kind of my take on it:

In core:

• A "schema" or form config that describes the fields and their validations (something like @bvaughn gist although I personally would like a list instead of an object) and a parser for it that normalizes it.
• A factory function that takes the normalized form config and creates a validation object for the adaptor to use.
• Default values creator, i.e. if we have "default" values for form fields in the config we like to create/extend the model where saving to.
• (Extended) JSON Schema to form config to transformer function.
• Form config extender, a function that uses the forms in one config but uses defaults for fields from another. This together with the JSON Schem transformer covers a lot of use cases. It can also be used to re-use validation between forms.
• Submit hook with possible validation outcome for the adaptor to call. So we can have backend errors come back.

In adaptors

• Rendering function that takes a form config and renders it. This could vary wildly depending on the adaptor.
• Hooks for calling core validation and error messages. (In Angular 1.x this would be directives)
• Hook for initiating it all by calling the core functions (In Angular 1.x this would be a directive)

Custom forms

I also believe that it is important that it's easy for the user to extend the form with it's own templates and we should think about that when designing the adaptor, but it's in the adaptor this belongs not in core so we can make use of the framework the adaptor uses (i.e. Angular 2) as much as possible (I think @kentcdodds said something like that?)

I would love to hear what you think about this, and I'm open to discussing all of it :)

[bvaughn]

Couple of questions. (This type of discussion may actually be better suited for a shared Drive document so we can comment inline.)

A factory function that takes the normalized form config and creates a validation object for the adaptor to use.

Not initially sure why we need this. Might our validator just (directly) consume a config object?

Default values creator, i.e. if we have "default" values for form fields in the config we like to create/extend the model where saving to.

Don't understand. I think you're saying we need to have something that handles the case of filling in values for form data that is empty (or sparse) initially?

Form config extender, a function that uses the forms in one config but uses defaults for fields from another. This together with the JSON Schem transformer covers a lot of use cases. It can also be used to re-use validation between forms.

Not sure I agree here. There are several ways people could choose to mixin or extend their own configurations if sharing is a goal. I don't know if I agree that we need to build another one.

For example, formFor only validates fields that have been declared via form-input (markup) elements. This means you could have a global config that defines 100 attributes and then many small forms that only validate using a small portion of it. Or you could have one validation object per form. Or you could do a hybrid approach where you extend shared validation objects but override a few properties for individual forms. I think these are powerful options and are (relatively) easy to implement. Again, not sure if we need to reinvent the wheel here. (But maybe I'm misunderstanding your meaning.)

[mchapman]

@davidlgj I have copied your adaptor / core split into my Drive doc (which Brian and I are finding a bit easier to make progress with, particularly when supplemented by the occasional hangout). I may have got the concepts (as far as I have got) right, but would like a "nomenclature map" between your bullet points and the jargon I have used.

Update the doc yourself or we can have a hangout (so I can be sure I understand it and can go through it with Brian late at night if anything is still unclear in the doc).

[davidlgj]

@mchapman excellent! I'll go through during the day today.

[davidlgj]

I don't have time to read and edit the drive document right now, but I'd like to just answer some of @bvaughn questions. I promise I'll move over to the document later today!

Ok, so here it goes:

Not initially sure why we need this. Might our validator just (directly) consume a config object?

It's not strictly necessary but it lets us have shorthands in the form config. Let's say a config attribute can either be a string or a list of objects. By normalizing it to a list of objects adaptors and other functions that need to use the config object can trust what they get.

Don't understand. I think you're saying we need to have something that handles the case of filling in
values for form data that is empty (or sparse) initially?

Yes! Maybe I'm still to used to JSON Schemas, but often a form needs some initial data, select and checkboxes prechecked. One solution is to offer the user a possibility to set "defaults" in the config object. But we don't need to support that. It can also be added later.

Not sure I agree here. There are several ways people could choose to mixin or extend their own
configurations if sharing is a goal. I don't know if I agree that we need to build another one.

Mixins is one goal, but it's also a way to support both the people who like to separate the validation of the form and the form configs into two objects (as we do n schema form) or like to have it all in one object.

[bvaughn]

RE: shorthands in the form config - Makes sense. Sounds good.

RE: setting defaults: Yes, this functionality is important. What I was questioning was the need to have a separate thing - a "default values creator" - to do this. Let's not worry about this now. Sounds like I was just snagged on wording.

Mixins is one goal, but it's also a way to support both the people who like to separate the validation of the form and the form configs into two objects (as we do n schema form) or like to have it all in one object.

I think we need to talk more about this, perhaps even via Hangout. The "form extender" you'er describing above doesn't sound the same as separation of validation and form-configs. I'm not sure I understand what a "form config" is aside from validation. Are you talking about things like default values? Also still not sure we need to build merging/inheritance logic into forms-js either.

[bvaughn]

PS. RE: shorthands in the form config Whatever does the normalizing of our configs will have to be sure to listen for changes in the original config. formFor commonly gets questions about whether certain parts of the config can be bindable (e.g. a field that's required under certain conditions only).

[davidlgj]

@bvaughn I'm definitely up for a hangout again, we just have to sync up everyones times.

I guess you're like 9 hours behind me? Times like now works, 8 pm for me and I guess something like 11 am for you? I'm quite an early bird in the morning (unwillingly I might add), so something like 8-9 pm PST would be 5 or 6 in the morning for me, which is when I trudge up from bed anyway. So that works for me as well.

[bvaughn]

It is currently 12pm for me (I'm on Pacific time) which normally works well for me, provided I have enough advanced notice to plan a desk lunch or something. My weekends are also usually very open, although this weekend will be busy because I'm traveling to Virginia.

[davidlgj]

Regarding shorthands and watching the form config for changes. This is one of the hard things.

Angular Schema Form is set up in a way that we don't really watch for changes in the json schema or the form definition, they have to change instance or the user has to tell us that they have changed by an event. If that happens the entire form is redrawn.

This has both negative and positive effects, the positive is that the complexity goes down as well as the number of watches. The negative is that changes to the form that should occur when the users does something, like populating a "state" select when selecting a a country, has to be implemented as specialized form "types". And it has become apparent in several issues that that is perceived as a hard thing. (This might be a documentation issue as well). Basically people like to change the form definition on a "onChange" event and then get bummed out when it doesn't update the form.

On the other hand I've got issues with people that have several hundred fields in their forms, so doing any kind deep watch may end up costing a lot in performance.