Improve content on the form config #186
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…reate new content at a beginner level for basic information you need to know about creating a form config
annekainicUSDS
commented
Jul 23, 2018
| @@ -246,7 +246,7 @@ Require any field. Validation is included. | |||
|
|
|||
| #### Usage guidelines | |||
|
|
|||
| For guidance on requiring fields or components, see the example in "[Building a simple form](https://github.com/usds/us-forms-system/blob/master/docs/building-a-form/creating-a-form-config-file.md#building-a-simple-form)." | |||
| For guidance on requiring fields or components, refer to "[About the schema and uiSchema objects](https://github.com/usds/us-forms-system/blob/master/docs/building-a-form/about-the-schema-and-uischema-objects)." | |||
There was a problem hiding this comment.
I wasn't really sure what this was linking to, I'm guessing an outdated link? Because the link didn't actually exist. So I changed it to the thing I found that made the most sense, but let me know if you think it should link to something different.
There was a problem hiding this comment.
I have a ticket about validating links in #145 which I hope will make it harder for broken links to exist.
There was a problem hiding this comment.
I must have created this at some point very early on just based on the outline I did... thanks for catching it!
annekainicUSDS
commented
Jul 23, 2018
| - *Fields* generally match the `type` attribute in a `schema` object. There are object fields, array fields, number fields, boolean fields, and string fields. Except for arrays and objects, the fields render a label (via `FieldTemplate`) and a widget. To specify a particular field, set the `ui:field` property to a specific field. | ||
| - A *widget* is the html input element that accepts data from the user. To specify a particular widget, set the `ui:widget` property to `text`, `email`, `checkbox`, `radio`, `select`, and `textarea`. While there are many widgets provided by rjsf, the defaults are overwritten with these versions. | ||
|
|
||
| The only React component you need to manually render in your application is the `Form` component. All other components are automatically determined based on the form config. For more information about how to include the `Form` component in your application, read about the [required files needed](../getting-started/installing-the-us-forms-system-in-an-existing-application#create-required-files). |
There was a problem hiding this comment.
For the most part, this entire file is just copied over from the original version of creating-a-form-config. The only addition I made was this particular paragraph.
There was a problem hiding this comment.
Since the Introduction and Confirmation are also React components at the moment, you'd need to do those as well. They're optional so it's not required, but if they're needed they have to be React.
dmethvin-gov
approved these changes
Jul 24, 2018
| - *Fields* generally match the `type` attribute in a `schema` object. There are object fields, array fields, number fields, boolean fields, and string fields. Except for arrays and objects, the fields render a label (via `FieldTemplate`) and a widget. To specify a particular field, set the `ui:field` property to a specific field. | ||
| - A *widget* is the html input element that accepts data from the user. To specify a particular widget, set the `ui:widget` property to `text`, `email`, `checkbox`, `radio`, `select`, and `textarea`. While there are many widgets provided by rjsf, the defaults are overwritten with these versions. | ||
|
|
||
| The only React component you need to manually render in your application is the `Form` component. All other components are automatically determined based on the form config. For more information about how to include the `Form` component in your application, read about the [required files needed](../getting-started/installing-the-us-forms-system-in-an-existing-application#create-required-files). |
There was a problem hiding this comment.
Since the Introduction and Confirmation are also React components at the moment, you'd need to do those as well. They're optional so it's not required, but if they're needed they have to be React.
| @@ -246,7 +246,7 @@ Require any field. Validation is included. | |||
|
|
|||
| #### Usage guidelines | |||
|
|
|||
| For guidance on requiring fields or components, see the example in "[Building a simple form](https://github.com/usds/us-forms-system/blob/master/docs/building-a-form/creating-a-form-config-file.md#building-a-simple-form)." | |||
| For guidance on requiring fields or components, refer to "[About the schema and uiSchema objects](https://github.com/usds/us-forms-system/blob/master/docs/building-a-form/about-the-schema-and-uischema-objects)." | |||
There was a problem hiding this comment.
I have a ticket about validating links in #145 which I hope will make it harder for broken links to exist.
|
This is GREAT, @annekainicUSDS! I'll dig into this now.
I'll go this route to save all of us some time! 👍 |
[Ready for review] Edit conceptual info
|
@bernars-usa thanks for your edits! Can I go ahead and merge this now |
bernars-usa
approved these changes
Jul 24, 2018
annekainicUSDS
added a commit
that referenced
this pull request
Aug 10, 2018
* 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"
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
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
I felt that the existing file, creating-a-form-config-file, on the form config included information that was not particularly useful to a beginning user just trying to understand what the form config is about. I pulled out the existing content and in that file and moved it into a new topic under how-the-library-works. I then created entirely new content for creating-a-form-config-file.
I'm guessing a lot of my wording is not ideal, @bernars-usa, so if the easiest way to review and edit specific wording is for you to create a PR into this one and make those changes yourself that would be fine! Otherwise, if you want to just leave feedback in this PR I can make those edits too.