Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add docs for creating a simple form #149

Merged
merged 2 commits into from
Jul 12, 2018

Conversation

dmethvin-gov
Copy link
Contributor

I'm not totally comfortable with this because it seems pretty extensive for a "simple" form. In particular:

  • If you leave the introduction page out the browser crashes with a "too much recursion" error so it's not really optional. It seems like there's some issue with it redirecting to /introduction which doesn't exist. I expected that if the intro was not specified it would go directly to the first page of the form. I wonder if confirmation is also crash-inducing since we haven't gotten to it in the starter app.

  • Even for a simple one-page form you end up having to create wrapper chapters and pages. I'm also not sure if review should be required on a simple one-page form. It's super easy to make mistakes when creating a deeply nested formConfig from scratch and get nonsensical errors because it looks like formConfig isn't checked against a JSON Schema itself. If you miss a level of nesting on something it really confuses the code.

  • There is a schema title and a uiSchema ui:title, it isn't clear to me when to use either although I used the uiSchema ones here so I'd have something in that object. However, it seems like using schema title would be a lot less typing and redundancy for this case. There's a similarly confused person who made a ticket in react-jsonschema-form. This particular case makes me think it would be super handy to have the code create a default title from the name of the field, e.g. email becomes Email.

  • The page title seems like it could be optional but the React component says that it is not. The React component throws a warning in the console based on propTypes defined.

  • The chapter title isn't required (no warnings) but has to be specified in practice. If it's not, the review page will show an empty untitled box in the accordion. Most likely we should require it, unless the review page can also be optional (if so, I don't know how yet).

  • When you get to the review page, the review component throws a propTypes warning because the trackingPrefix is not specified, this is related to the undocumented functionality mentioned in Document the ability to track form stats and errors via Google Analytics #134. I don't think we want to make Google Analytics a requirement.

I suspect this will need some changes, either to the text here in the PR, the code, or both. Fire away!

@dmethvin-gov
Copy link
Contributor Author

Addresses concerns in #79 and #128, maybe others.

Copy link
Contributor

@annekainicUSDS annekainicUSDS left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Generally looks great! One suggestion for some different wording.

All of the issues your mentioned in the PR description are really good for us to document, and I think we should probably create tickets for them to address separately.

- [Example `form.js` file](#example-form.js-file)
- [About the `schema` and `uiSchema` objects](#about-the-schema-and-uischema-objects)
- [Configuring `uiSchema` using rjsf options](#configuring-uischema-using-rjsf-options)
- [Configuring `uiSchema` using US Form System options](#configuring-uischema-using-us-form-system-options)

### Building a simple form

The US Forms System contains a `FormApp` component that you configure and control via a `formConfig` object. In the starter app, the file that exports this object is located in `/src/js/config/form.js` and included in `/src/components/Form.jsx`. where `FormApp`is used. When building an app from scratch you can define and include these components where it's convenient.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I might rephrase the opening paragraph here. I feel like the first concepts someone should understand before building a form is that they describe the form in formConfig and they need to render the top-level React component, FormApp, somewhere. I might write:

"In order to build a form, you'll use the configuration file to specify everything your form needs: questions, how questions are grouped together, content on the page, data validation, etc. In the starter app, the file that exports this configuration object is located at /src/js/config/form.js.

Most of the time you'll just be working within the config file to describe the form you need and you won't be writing React components. However, there are 2 cases where you'll need to work with React components directly:

  1. Rendering the top-level React component: US Forms System uses a top-level React component, FormApp, to pass the formConfig object, exported from your config file, down to the rest of the components that are rendered. In order for the React component hierarchy to properly render, you'll need to include FormApp in your app's top-level component, and pass it the formConfig object as a prop. See how the starter app does this for an example.
  2. Creating custom components: There may be times where you'll want to create your own custom React components to include in the form config. Examples may include creating a custom page you want to render (e.g., an introduction page), creating a component for content (e.g., a warning message) you want to render within a page, or creating a new component to override one of our default ones. In these cases you'll be building React components from scratch."

Something like that?

@dmethvin-gov dmethvin-gov merged commit de19648 into usds:master Jul 12, 2018
@dmethvin-gov dmethvin-gov deleted the simple-form branch July 12, 2018 16:55
@dmethvin-gov dmethvin-gov mentioned this pull request Jul 12, 2018
dmethvin-gov added a commit that referenced this pull request Jul 13, 2018
* Add docs for creating a simple form
bernars-usa added a commit that referenced this pull request Jul 13, 2018
* Add placeholder topic for available components

* Additional changes after discussion with @dmethvin-gov and @fatimanoorva

* Add a consoleSubmit option for debugging output (#153)

* Add a consoleSubmit option for debugging output

Fixes #135

* Use pre-push hook to ensure build artifacts are up to date (#151)

Fixes #97

* Add docs for creating a simple form (#149)

* Add docs for creating a simple form

* Add some code examples and explanations on components

* Better headings

* Revert "Better headings"

This reverts commit 66f40ae.

* Apply Dave's changes again because Git is hard
annekainicUSDS pushed a commit that referenced this pull request Aug 10, 2018
* Add docs for creating a simple form
annekainicUSDS pushed a commit that referenced this pull request Aug 10, 2018
* Add placeholder topic for available components

* Additional changes after discussion with @dmethvin-gov and @fatimanoorva

* Add a consoleSubmit option for debugging output (#153)

* Add a consoleSubmit option for debugging output

Fixes #135

* Use pre-push hook to ensure build artifacts are up to date (#151)

Fixes #97

* Add docs for creating a simple form (#149)

* Add docs for creating a simple form

* Add some code examples and explanations on components

* Better headings

* Revert "Better headings"

This reverts commit 66f40ae.

* Apply Dave's changes again because Git is hard
annekainicUSDS added a commit that referenced this pull request Aug 20, 2018
* Relative links will be the end of me

* Relative links to definitions directory

* Two more

* Add links to docs and starter app, tighten up other copy

* Significantly faster cc @annekainicUSDS

* Add a consoleSubmit option for debugging output (#153)

* Add a consoleSubmit option for debugging output

Fixes #135

* Use pre-push hook to ensure build artifacts are up to date (#151)

Fixes #97

* Add docs for creating a simple form (#149)

* Add docs for creating a simple form

* Fix link (#157)

* [WIP] Add placeholder topic for available components (#154)

* Add placeholder topic for available components

* Additional changes after discussion with @dmethvin-gov and @fatimanoorva

* Add a consoleSubmit option for debugging output (#153)

* Add a consoleSubmit option for debugging output

Fixes #135

* Use pre-push hook to ensure build artifacts are up to date (#151)

Fixes #97

* Add docs for creating a simple form (#149)

* Add docs for creating a simple form

* Add some code examples and explanations on components

* Better headings

* Revert "Better headings"

This reverts commit 66f40ae.

* Apply Dave's changes again because Git is hard

* Big reorg

* Add placeholder topic for available components

* fixes few relative links

* add "contributing to this project" section

include: links to code of conduct, CONTRIBUTING.md, and instructions on how to join the forms listserv

* Update shortdesc

* More line breaks 😩

* A bit more elaboration courtesy of Anne

* Field component props and what they do

* Clarify the purpose of this description once and for all

* Clarify this weird point

* What are "they"?

* Links back to README, fix markdown

* Better headings

* Add these links

* Add a hopefully better description of the keepInPageOnReview property

* Keep consistent with "review page"

* Use Anne's language, needs clarification on the second sentence

* Introduction component

* Form footer

* Prgoress bar

* Title and subtitle

* Update mini-toc with new combined section header

* For example

* Date fields

* Hidden contextual information - needs info on how to specify cc @dmethvin-gov

* Radio Button and Checkbox Group - needs a code sample cc @dmethvin-gov

* Password usage guidelines - what do we want to say about this?

* Just kidding, the previous commit was for required fields, this one's for password

* Duplicate field validation

* Conditional form fields

* Small reword

* Add widget descriptions (#166)

* Complete table with widget information

* Add more description for some components

* Add usage info for error messages

* Edits from review

* Remove password description

* Make review edits

* Add remaining descriptions (#174)

* Add remaining descriptions

* Make updates from review

* Update language

* Refactor from review comments

* Remove one word

* Rename components topic

* Remove hidden contextual information cc #173

* Minor cleanup

* Set the property to `true`

* Create the new individual files

* Move content, turn table rows into sections for linking

* Move content

* Add more descriptions for widgets

* Rename to "Available" rather than "Common"

* Edits from @dmethvin-gov

* Fix link to docs (#181)

* Widget links as appropriate

* Add guidance on using widgets

* currencyUI

* This is guidance for adding widgets, the previous commit was for definitions

* Combine info more coherently

* Remove less specific information

* Definitions for widgets and... definitions

* More verbose explanation of the example

* Remove AddressField per @annekainicUSDS

* Improve content on the form config (#186)

* Separate out advanced information on how the form config works, and create new content at a beginner level for basic information you need to know about creating a form config

* Move to new customization map

* Update links after move

* Rename new conceptual topic

* Rename map

* Update main README after renames and moves

* Rename again

* Copy edits

* Update shortdesc cc @annekainicUSDS

* Remove these sections

* Not "our"

* Small fixes

* Fix misspelling

* H1 header

* Fake breadcrumbs

* relative link

* 😩

* Once more

* Two dots

* Map topic readme links

* Relative links for every breadcrumb

* Topic links

* Add folder name

* This is broken

* Fix links

* All these commits are going to have the same commit message

* Add folder

* Once more

* All breadcrumbs

* Small link fixes here

* Fix relative link?

* Remove directory

* Add markdown extension

* Relative link

* One more level

* All small fixes for "Building a form"

* Small updates for "Customizing the library"

* Add react

* Lots of hardcoded links

* Remove containing directory

* Line link doesn't work

* Not plural

* Markdown extension

* MARKDOWN EXTENSION

* Fix the example for conditionally hiding fields (#183)

This is simplified from the big form I'm building.

* More detail on use of definitions (#188)

* [WIP] More detail on use of definitions

* Fix imports; further updates

* Add autosuggest section

* Add missing expandable group styles (#192)

* Add basic tutorial (#194)

* Add basic tutorial

* Fix language

* Add Dave's suggestions

* Add Sheri's suggestions

* More edits from Sheri

* Edit images

* Small edits

* No apostrophe (#197)

* Don't show back button on first page (#195)

Routes in `pageList` mocks now reflect the way they really look, using a leading slash.
Also cleans up FormPage/ReviewPage unit tests which had remnants of vets.gov user login.

Fixes #177

* TOC at the top of the tutorial

* Minor cleanup

* Add readme links

* Minor cleanup of review section

* Add breadcrumbs

* Add content to question issue template

* Clarify a couple of questions

* Typos

* Do not filter out properties on inactive pages that also appear on active pages (#155)

* Add functionality to not filter out properties on inactive pages that also appear on active pages

Refactor

Refactor

Remove duplicate properties from array

Return properties

* Write unit tests for new functionality

* Refactor from code review

* Change _.uniq to only be called once

* Run build on latest changes

* Clean up and dry out the FormPage unit tests (#202)

* Update node-sass to remove the node-gyp vuln (#213)

* 1.1.0

* Fix merge conflict
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants