search

vazco / uniforms

A React library for building forms from any schema.
https://uniforms.tools
MIT License
1.94k stars 239 forks source link

New step-by-step guide #259

Closed radekmie closed 5 years ago

radekmie commented 7 years ago

As requested on many issues, Gitter room, Meteor forum or even direct messages, I'd like to collect ideas for a line-up of a step-by-step guide. I really encourage you to share your ideas for both order and additional points.

Most of it is already covered in the documentation and scattered in issues and/or Gitter. I'll start a new branch and PR for it in few days, where everybody could help.

Update 2018-01-10: The problem with new documentation is that I'd really like the live-preview demo. In order to have SimpleSchema@1 included, it has to be in Meteor. As for now, the only option is a full-blown Meteor app (as it is right now), but it's a demo, not docs. Meanwhile, I'm answering in issues (as in-depth as possible) and questions on Gitter.

Update 2019-02-10:

Some news here! I've spent too much time trying to do it with Docusaurus and few other projects, so it took that long. Last week I started a new version, now with Docz. It looks nice and works pretty well (although I still had some problems). For now, I've ported the whole INTRODUCTION.md and the playground. It's already on a branch called new-docs.

When it comes to the plan: it'll be on a separate branch for some time (I hope less than two years) and then became the main docs, including the playground (still available on uniforms.tools). For now, I'll gladly accept any PR regarding the docs.

Important things first: the playground in Docz is not 1-1 as it was (styling is a bit worse). As soon as this issue will be resolved, I'll setup the automatic deployment (so it'll be always up-to-date with the source). Splitting the whole docs would also be great - one big doc is loading a bit too much.

How it works: Docz uses MDX, so it's as easy as Markdown, but custom JSX is also possible, therefore even inline playgrounds will work.

Update 2019-02-14: New docs are available on vazco.github.io/uniforms/index.html. The URL is kind of weird, it's still not final.

Update 2019-03-03: The URL is already good: vazco.github.io/uniforms/#/introduction. The playground is also fixed and working as previously. There's a plan to make an internal hackathon just to finish the docs (or at least make a not-so-ready-but-already-deployed verion).

Update 2019-03-14: Work on uniforms v2 has started! New docs along with the new changes are now on branch v2.

Update 2019-03-25: New docz version has removed hash router support, which blocks us from deploying it to GitHub pages. We’re waiting up to the end of the month for Docusaurus 2 alpha (or any other release) and eventually start with Gatsby.

Update 2019-04-17: Docusaurus 2 alpha is already there but it's too soon to use it (yet). We plan to get back to it as soon as possible.

Update 2019-04-25: Almost there! Check out vazco.github.io/uniforms/uniforms/ . There are few problems left, like the URL, icons and GraphQL in the playground, but consider it done!

Update 2019-04-27: Ready! Now the content! Check out vazco.github.io/uniforms!

janowsiany commented 7 years ago

I tought about redux or MobX example as it might be a thing what people are willing to search here also, i can imagine that it might not be very complecated but anyway i would place such an example in the upcomming docs. I am willing to submit such redux example.

radekmie commented 7 years ago

@janowsiany and how about a more general example: using the form as an input? It will be library independent. Although, such example would be good.

cyclops24 commented 7 years ago

Thanks @radekmie , It's a very good news. I suggest below topic:

cyclops24 commented 7 years ago

@janowsiany MobX is extra simple and useful library for me. It's very good if we have a MobX example.

radekmie commented 7 years ago

@cyclops24 what example exactly you'd like to see on uniforms + MobX? I don't see nothing beside form as an input example.

janowsiany commented 7 years ago

One thing raised in one of the most recent issues(#278) is:

How to manipulate field value on change of other field?

This also might be a common problem so i think we should attach some explanation for this here.

thearabbit commented 7 years ago

Thanks @janowsiany for How to manipulate field value on change of other field?. Could somebody help me about this (now my project is pending)?

krishnapsms commented 7 years ago

Hi @radekmie I'd like to use uniforms in meteor-react project using material ui, where i can get the meteor-react example using quick forms to quick start.

radekmie commented 7 years ago

@krishnapsms in the documentation itself. If you'll have some quick questions, I encourage you to ping me on gitter - it's easier to communicate.

zeroasterisk commented 7 years ago

@cyclops24 one of the things I love about uniforms is that you don't have to integrate into other state systems. Using it with redux/mobx/whatever is automatic, because uniforms handles it's own state/context

micahalcorn commented 6 years ago

I started experimenting with Uniforms yesterday. Here are a few basic issues where I think I understand, but the answers were not obvious to me:

0) Am I required to write an onSubmit handler, even if my model is from a Meteor collection? 1) Apparently, an onSubmit is called after onValidate and only if the validation is successful? 2) Are there validation callbacks (pass/fail) that can be used without implementing my own onValidate? 3) If I do add my own onValidate, is it necessarily asynchronous? What is the callback that is passed to my onValidate function (the third parameter)? Is the default validation synchronous, and are there consequences to overriding it?

Thanks for all your efforts. 😊

zeroasterisk commented 6 years ago
  1. Yes, onSubmit is a required, react prop, independent of Meteor, but very easy to wire in.
  2. Yes, submitted only if valid.
  3. Sure, if you're using a schema which has validation baked in, they are already there, no custom validation needed
  4. Should be examples of this in the docs and maybe in the demo app... Consequences? No, just that validation failures would take time to resolve. No big deal.
CaptainN commented 6 years ago

Hi, I've also had some trouble implementing certain things. For example, I have one field which needs to do a remote check to make sure a value is unique in the database. But I can't get any error to display within the form, and the documentation doesn't really explain how to do that.

It does explain how to use onValidate to block validation (and there's enough there to infer that I need to always call callback - though an explicit note would be great). But it doesn't explain what the shape of that object should be, if you return an error object - it just returns the error from some remote API or null.

What should that error object be shaped like to get the ErrorsField or ErrorField to show up?

radekmie commented 6 years ago

@CaptainN: good point.

It's stated in the API:

    // Validation error.
    //   Current validation state. It should be either compatible with your
    //   schema or an Error object.
    error={new Error('Nope.')}

But it should be mentioned again in the asynchronous validation section.

Baudin999 commented 6 years ago

(Really sorry about the length of this comment)

Hi, I've been reading the docs and I might have some suggestions. I started using uniforms two days ago and as such might have a fresh look on the issues I ran into and how the docs might provide a bit more structure to help people along. (NOTE: even if some points I've listed aren't possible, add them to the list anyway and tell people they are not implemented yet. You can even link to future enhancements so people can engage with the features)

The second thing I'd like to say is that using something like Storybook JS can really help. You can create chapters and really show both the code and the result which is insightful.

Part 1 - Introduction

1 - 0) Explain a little bit about the goals of the project, explain the two paths, Meteor and plain old React. Make separate introductions and documentation for these two paths. Meteor people might know about React, but React people sure know nothing about Meteor.

1 - 1) Installation and setup. Quick guide to getting started. NPM installation guide for both the schemas and how to import them in your code with a small 1 field example of how to get crackin'. For example, I got set up but didn't know how to get SimpleSchema imported, when I did I later found out it was SimpleSchema@2 through the npm package.

1 - 2) Quick intro on every field-type. I still haven't figured out how to get a multiline textbox in my form...

1 - 3) Quick intro on styling. People always want to style their forms. Imagine a form for designing a RPG weapon. You'll want the field where you enter the dmg of the weapon to look something like:

screen shot 2018-03-04 at 08 50 54

It took me a full day to be able to add a className to sections of my form. I had to extend the SimpleSchema options SimpleSchema.extendOptions(["className"]);

Part 2 - Schemas

It was immediately clear that I needed to use a schema and the form would set up according to that schema.

2 - 0) Write a little introduction on which schema's are supported and what the difference is between these schema structures. Maybe even why these are supported and others aren't.

2 - 1) How do we extend these schemas and which properties are needed to get the full power out of uniforms. In other words, which properties does uniforms support but the schemas do not support out of the box. This is important because simple extensions to the schemas need to be made to get the most out of uniforms.

2 - 3) Other important functionality of uniforms in comparison to the schemas.

Part 3 - Uniform Events

There are events we can subscribe to, each event is either on the form itself or on the field. How do we subscribe to these events and how do these events work.

3 - 0) Describe the events and their properties.

Part 4 - Validation

How to validate the model. If your schema does not support validation, how to manually validate the model and inject error messages.

4 - 1) Validation through your schema. Give simple examples of validation per schema. This should not focus on how these schemas work but give a very simple example and link to the schema's documentation on validation.

4 - 2) Inline validation vs. the little box at the bottom of the form. How to toggle the two.

4 - 3) Custom validation messages.

4 - 4) Async Validation. Send the model to a server to be checked and return the validation result.

Part 5 - Reacting to field changes

A big part of using forms is the power to change your form as a reaction to someone doing something on in your form. For example, fill out some default values when you select a template model from a dropdown. Or add fields when you answer a boolean field with yes or no.

5 - 1) Dynamic forms, showing and hiding fields through other values in the model. This is where React shines. This is really important stuff.

5 - 2) Setting values in fields through a template

Part 6 - Redux

Redux is a big part of the React community. How can we set up our form to dispatch actions to our reducer. How can external processes influence the form. For example, when our model changes due to some external action we'd want our form or our data to change.

React works two ways, passing data down to the components and sending data to our reducer which triggers the cycle. These two things need to be explained. Before you can explain these things you'll want to briefly link to redux in a section I call "Connecting to our store".

6 - 1) Connecting to our store

6 - 2) Reacting to changes

6 - 3) dispatching events to our reducer

Part 7 - Meteor + MobX

I don't have any experience using Meteor and MobX so I can't really help here.

Part 8 - Connecting to backends

How to do we automatically push changes to a backend.

8 - 1) Simple example using NodeJS.

8 - 2) Simple example using Firebase

This should be enough to show how to connect to backends.

Part 9 - Further reading and References

I always like to end documentation things with further reading, here you can link to specific documentation on how to extend the forms. AutoForm vs ValidatedForms and the technical stuff behind it. How to extend fields and how to implement your own bridges to Schemas. People need to know these things, but only after working with the library for some time. I tend to extend the library only when I've noticed that there is no default way to do things. Giving insight on the default way to do things is really important.

radekmie commented 6 years ago

Thank you very much @Baudin999, I really appreciate such suggestions!

Few answers in the meantime:

I still haven't figured out how to get a multiline textbox in my form...

Use LongTextField.

It took me a full day to be able to add a className to sections of my form. I had to extend the SimpleSchema options SimpleSchema.extendOptions(["className"]);

There's no such need - simply define an uniforms in your field definition: fieldA: {type: Number, uniforms: {className: 'a b'}}.

Describe the events and their properties.

Events? What events? All on* props, right?

Baudin999 commented 6 years ago

@radekmie thank you so much for your input.

I still can't seem to render a LongTextField. I have a SimpleSchema@2 definition. What can I add in order to make my description field a LongTextField? My schema looks something like:

import SimpleSchema from "simpl-schema";

const BaseSchema = new SimpleSchema({
    name: { type: String },
    description: {
        type: String,
        optional: true
    }
});

I have temporarily solved it by explicitly importing the LongTextField and setting that as a Component like so:

import LongTextField from "uniforms-antd/LongTextField";

const BaseSchema = new SimpleSchema({
    name: { type: String },
    description: {
        type: String,
        optional: true,
        uniforms: {
              component: LongTextField
        }
    }
});

On the className thank you for the tip! Now that you mention it, I found it in the Documentation. Must have skipped it in when reading it the first time, sorry for missing that!

One more question on the className:

If I add a className with the value is-shield I get something like this as a result:

<div class="ant-row ant-form-item" style="margin-bottom: 12px;">
   <div class="ant-form-item-label"><label class="ant-form-item-required" title=""><span>Is shield</span></label></div>
   <div class="ant-form-item-control-wrapper">
      <div class="ant-form-item-control">
           <span class="ant-form-item-children">
                <span id="uniforms-0000-000n" name="isShield" required="" 
                           class="**is-shield** ant-switch" tabindex="0">
                     <span class="ant-switch-inner"><i class="anticon anticon-cross"></i></span>
                </span>
           </span>
       </div>
   </div>
</div>

Is there also a way to add a className to the root of the element? So on the ant-row ant-form-item?

On the documentation in general. I see that you would like some help with the Documentation. If you want I could take a stab at it? For some strange reason I really like writing documentation :) I have almost no experience with Meteor though, but I could help write the normal React docs if you want.

radekmie commented 6 years ago

@Baudin999

I have temporarily solved it by explicitly importing the LongTextField and setting that as a Component like so:

It's a desired solution, no a temporary one. Another one is to use <LongTextField /> inside your form.

Is there also a way to add a className to the root of the element?

Simply check the source.

On the documentation in general. I see that you would like some help with the Documentation. If you want I could take a stab at it? For some strange reason I really like writing documentation :) I have almost no experience with Meteor though, but I could help write the normal React docs if you want.

Two things here. One, I'd love you to help us with that, really. Two, the reason, why I haven't started doing it for such along time is that I wanted to have both demo and docs in the same place. Now I see it's impossible. In the meantime, a friend of mine started to work on it, but I don't know, what's the status there - I've already asked him. I'll let you (all of you) know as soon as I'll know something.

Baudin999 commented 6 years ago

@radekmie Great that you've planned the docs out this carefully! Thank you again for the help and if you need some help just let me know; I love the repo and would gladly help out.

kiran-mysore commented 6 years ago
Hi, I am trying to integrate this awesome package which has awesome reviews. Unfortunately, I am not able to test a simple form. I am using create-react-app and trying to create a simple form using Uniforms based on simpleschema. I am getting following error ` ./node_modules/uniforms-semantic/src/ListItemField.js Module parse failed: Unexpected token (10:4) You may need an appropriate loader to handle this file type. const ListItem = props =>

`

radekmie commented 6 years ago

@kiran-mysore please, file an issue or ask us on Gitter - there's a bunch of people watching this issue and your comment is not anyhow related.

ayhid commented 6 years ago

It will be great to have examples of DisplayIf inside a lis of nested fields. I know it's very specific. I have lot of forms with dependant nested fields and I am struggling to get this working.

Thanks for the awesome work

santosh18deligence commented 6 years ago

test

vfonic commented 5 years ago

I'd suggest adding documentation piece by piece. This issue is almost two years old. I understand it takes time, therefore, maybe it's best to update the documentation gradually.

Speak of how to organize the structure, I prefer having everything in one Readme.

Table of Contents on top, and user can search for some special keywords if he doesn't see what he's looking for within the ToC. Would be great to have more examples of how to do certain things, or what's available in the API. For example, I just found out about this functionality in this issue:

There's no such need - simply define an uniforms in your field definition: fieldA: {type: Number, uniforms: {className: 'a b'}}.

radekmie commented 5 years ago

Eh, now there won't be any surprise... You are right, @vfonic. A plan for now (it's actually in progress), is to create a setup of the new documentation (including a migration of the current demo, which is why Docusaurus is not working here, as the playground would require a workaround, and I've lost quite a lot of time on that), merge it, and let it develop with time (including my coworkers and my own work, but also accepting PRs).

TL;DR; It's actually happening at the time of writing.

vfonic commented 5 years ago

Sounds great! :)

I understand it takes a lot of time and I'm amazed by your availability. Thank you!

radekmie commented 5 years ago

Some news here! I've spent too much time trying to do it with Docusaurus and few other projects, so it took that long. Last week I started a new version, now with Docz. It looks nice and works pretty well (although I still had some problems). For now, I've ported the whole INTRODUCTION.md and the playground. It's already on a branch called new-docs.

When it comes to the plan: it'll be on a separate branch for some time (I hope less than two years) and then became the main docs, including the playground (still available on uniforms.tools). For now, I'll gladly accept any PR regarding the docs.

Important things first: the playground in Docz is not 1-1 as it was (styling is a bit worse). As soon as this issue will be resolved, I'll setup the automatic deployment (so it'll be always up-to-date with the source). Splitting the whole docs would also be great - one big doc is loading a bit too much.

How it works: Docz uses MDX, so it's as easy as Markdown, but custom JSX is also possible, therefore even inline playgrounds will work.

radekmie commented 5 years ago

Finally! After over two years (760 days) new documentation is merged into the master branch and hosted on vazco.github.io/uniforms. As we are still working on the content, everyone is very welcome to help! I'll try to incorporate the above ideas and topics as much as possible, but if you have any idea on how to tackle any of these - please, let me know. Our gitter channel is still alive and well and issues are still a viable way to discuss such. Pull requests are, as always, very welcome.

Thank you for all the ideas!