-
Notifications
You must be signed in to change notification settings - Fork 215
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
7171 getting started with forms (#7192)
* developer contributions to "Getting started with VA.gov Forms"; * add teams/vsa/engineering/forms-system as a place to include VSA work-in-progress guidance on forms * video tutorial on forms
- Loading branch information
short000
authored
Mar 26, 2020
1 parent
d5a35b4
commit 75ceb2f
Showing
6 changed files
with
93 additions
and
20 deletions.
There are no files selected for viewing
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
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
Git LFS file not shown
20 changes: 20 additions & 0 deletions
20
teams/vsa/engineering/forms-system/2020-03-forms-doc-feedback.md
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| ## March 6, 2020 VSA Developer Feedback on Forms System | ||
| The documentation on VA<span/>.gov Forms System (VAFS) needs to be more accessible. | ||
| * Navigation: good information there, just really hard to find. | ||
| * Big gap in how to add to form builder. Ideally, every component in design.va.gov should be there, but we only get the bare minimum; primitives such as text fields. | ||
| * If we knew how to add a new component to form builder it would speed up our development processes and make the platform more cohesive across the board. | ||
| * The VAFS documentation does not contain a link to the VA fork of RJSF, even though the RJSF documentation is required to figure out most advanced things. | ||
| * This is the documentation we all have been using to learn VAFS: https://department-of-veterans-affairs.github.io/veteran-facing-services-tools/forms/. | ||
| * Here it mentions that VASF is based on RJSF: https://department-of-veterans-affairs.github.io/veteran-facing-services-tools/forms/creating-custom-fields-and-widgets/#how-vafs-uses-rjsf; | ||
| * However, you really need to go to the VA’s fork of RJSF at https://github.com/department-of-veterans-affairs/react-jsonschema-form to understand how to build/modify a form component. Many of our developers were not aware of this link (undocumented; it needs to be better disseminated). | ||
| * The original RJSF site (not the VA fork) had an interactive tool to demo or test your schemas (add data to see how things look): https://rjsf-team.github.io/react-jsonschema-form/; it would be awesome to have that in the VAFS documentation site. | ||
| * How to use the form builder (basics): the documentation is there (actually covered well) but hard to find, get around. | ||
| * The advanced parts, especially the internals of how it works, are not covered at all. | ||
| * Need lots of examples of different problems that people tried to solve, and how they solved them. | ||
| * Overall, there doesn’t seem to be a lot of documentation there beyond just setting things up. Once you get past the point of just setting things up, that’s where our documentation just falls off. | ||
| * Nothing there in terms of troubleshooting when things doesn’t work. The errors we get back from the forms system are generally worthless and while this means we also need better error handling we also need troubleshooting steps to use when things go wrong. Give a common set of scenarios and then what to look for in those scenarios. | ||
| * There may also be a disconnect between the actual steps you need to do to run the form generator vs the details you see under “getting started > common tasks” | ||
| * Need some opinionated standards around use of the form builder. | ||
| * We are all building the same things over and over again. Since this is the case we should have a set of opinionated “recipes” that serve as examples. | ||
| * Advice to “just look at the code and find examples” does not work because you’ll see different ways to accomplish the same thing. Which way is the right way? | ||
| * Documentation needs to be built for engineers so that it speaks to an engineering audience; our current documentation looks more like it is written for a design audience. |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,39 @@ | ||
|
|
||
| This page is for capturing potential known issues with forms. Some of these may just be gotchas, quirks, suggestions for enhancements. Some might turn out to be defects. Once the details have matured they may be written up as GitHub issues and taken up by the platform team (VSP). \ | ||
| <br/> | ||
| <br/> | ||
|
|
||
| ## Review Page Does Not Show Empty Field and Crashes if Sorted (ui:order) | ||
| ### Developer POC: Nick Sprinkle | ||
| ### GitHub Issue#: TBD | ||
| ### Problem | ||
| The review page does not show empty fields (appears to be by design, but undocumented). When we have empty fields, it also crashes when sorting (ui:order). | ||
|
|
||
| ### Details | ||
| Using the forms system, there is an issue with the review page when using ui:order in combination with a ui:description object field when defining a field in the schema like this: | ||
| ```json | ||
| { | ||
| type: 'object', | ||
| properties: {}, | ||
| } | ||
| ``` | ||
| and when defining that same field in the UI schema with only a *ui:description* field, that field will be automatically dropped from the review page. This is intentionally behavior as the idea is to drop fields that are empty objects. The field is removed from both the schema and the UI schema. However, if using *ui:order*, the field is not dropped from this array. This causes the review page to crash when the field would be rendered. The error outputted is: | ||
| ``` | ||
| uiSchema order list contains extraneous property 'propertyName' . | ||
| ``` | ||
| ### Commentary | ||
| There seems to be two issues: \ | ||
| (1) The documentation does not explicltly mention that empty items will not be shown on the review page. We suspect that may be by design; however, that default behavior might not be desirable in all cases. \ | ||
| (2) When sorting (ui:order) is also involved, the review page crashes. \ | ||
| <br/> | ||
| <br/> | ||
|
|
||
| ## Unable to Pre-Fill (pre-populate) Form | ||
| ### Developer POC: Amen Ra | ||
| ### GitHub Issue#: TBD | ||
| ### Problem | ||
| (vague) - was unable to pre-fill (pre-populate) data into a new form | ||
|
|
||
| ### Details | ||
| "Your Form ID has to match the in progess form endpoint in order to use the main form reducer. For instance form 2346 endpoint is /in_progress_forms/MDOT, the form id is MDOT" \ | ||
| TODO: need more context, an example. This statement is probably a tip or (undocumented?) solution. |
Empty file.