Add widget descriptions #166

annekainicUSDS · 2018-07-16T23:17:02Z

Description

In this PR I completed the table of widgets and added more usage detail for radio button groups and checkbox groups. I'm not sure if the way I've included that detail is in the format you're looking for, @bernars-usa and @dmethvin-gov, so let me know what you think!

annekainicUSDS · 2018-07-17T12:56:50Z

If the format and content looks good, I can continue with the remaining items that need additional info!

bernars-usa

Thank you SO MUCH for filling these in! Let me know if you have any questions about my comments, or if I interpreted anything incorrectly.

bernars-usa · 2018-07-17T15:49:29Z

docs/building-a-form/adding-widgets-and-definitions.md

@@ -13,19 +13,21 @@ These common widgets are included in the us-forms-system by default. Set these w

 To use a widget, set `ui:widget` for a field to the name of the widget. Widgets are located in [/src/js/widgets](../src/js/widgets).

-Widget       | Default schema type or format
+Widget       | How it is used


How it is used

Let's opt for contractions when reasonable: "How it's used"

bernars-usa · 2018-07-17T15:56:54Z

docs/building-a-form/adding-widgets-and-definitions.md

+`TextWidget` | Default widget for a schema that specifies `type: 'string'`
+`YesNoWidget` | In the `uiSchema`, specify `'ui:widget': 'yesNo'` for the given field
+
+** Note: some widgets are specified as a string (e.g., `'ui: widget': 'date'`) and some you pass the actual widget to the config (e.g., `'ui:widget': 'CurrencyWidget'`). This is because the [react-jsonschema-form library](./about-the-us-forms-system-library#understanding-react-jsonschema-form-rjsf) includes some widgets already that have string mappings. Widgets that we created specifically for us-forms-system do not have these mappings, and therefore must be specified by passing the widget directly to the config.


some widgets are specified as a string (e.g., 'ui: widget': 'date') and some you pass the actual widget to the config (e.g., 'ui:widget': 'CurrencyWidget'). This is because the react-jsonschema-form library includes some widgets already that have string mappings. Widgets that we created specifically for us-forms-system do not have these mappings, and therefore must be specified by passing the widget directly to the config.

What about:

"Widgets from the react-jsonschema-form library include string mappings, such as 'ui: widget': 'date', while those created specifically for US Forms System do not have these mappings, such as 'ui:widget': 'CurrencyWidget'. To specify US Forms System widgets, pass the widget directly to the config."

I also think this information could be skipped over underneath the table, so it would be best to place it before the table.

Yes, I was conflicted about where to place this information because it's not critical for someone to know about in order to use widgets. As long as they go by what's listed in the table, they'll be fine. I just figured the explanation would be helpful because I could imagine some people wondering, "Why are some widgets specified as strings and others as components?" I wanted to answer that question in case it seemed confusing once they read the table.

It's definitely useful context! I'm glad you included it.

bernars-usa · 2018-07-17T15:58:53Z

docs/building-a-form/available-components.md


-For the code implementation, see [`RadioWidget`](https://github.com/usds/us-forms-system/blob/master/src/js/widgets/RadioWidget.jsx).
+In order to override the `SelectWidget`, you must pass `'ui:widget': 'radio'` to your `uiSchema` for that field. If you also want to specify different label text for each option, you would pass `'ui:options'` to `uiSchema`.


In order to override the SelectWidget, you must pass 'ui:widget': 'radio' to your uiSchema for that field. If you also want to specify different label text for each option, you would pass 'ui:options' to uiSchema.

A little tighter:

"To override the SelectWidget, pass 'ui:widget': 'radio' to your uiSchema for that field. To specify different label text for each option, pass 'ui:options' to uiSchema."

bernars-usa · 2018-07-17T16:17:42Z

docs/building-a-form/available-components.md

+}
+```
+
+For more information about this widget, see [`RadioWidget`](https://github.com/usds/us-forms-system/blob/master/src/js/widgets/RadioWidget.jsx).


For more information about this widget, see...

I've been using this text to be really explicit about why you'd want to view it: "For the code implementation, see..."

I just don't want people to go there thinking they need to review that in order to implement it.

Gotcha. I wasn't sure the point of redirecting them to the widgets page because this section basically contains all the info they need. We may want to reorganize some of the content here, and create a separate file for widgets and move the functionality in this file that pertains to widgets into the new one. What do you think?

We may want to reorganize some of the content here, and create a separate file for widgets and move the functionality in this file that pertains to widgets into the new one. What do you think?

Yeah, I actually had a thought about combining this with what's left of the old "Creating a form config file" topic I tore up over in https://github.com/usds/us-forms-system/pull/167/files#diff-8dbd886edc52aa4c211a3838bff6dfbcR1 (see my comment in https://github.com/usds/us-forms-system/pull/167/files#r203158103).

bernars-usa · 2018-07-17T16:19:01Z

docs/building-a-form/available-components.md


 ### Checkbox group

-A group of options where the user can select multiple items.
+Each individual checkbox is used to store `boolean` data. If you want to include a group of checkboxes, you would include separate fields for each checkbox, with `type: 'boolean'` passed to the `schema`.


Can we include this information under "Usage guidelines" instead?

bernars-usa · 2018-07-17T16:21:20Z

docs/building-a-form/available-components.md


 ![A multiple choice question with two options selected](https://raw.githubusercontent.com/wiki/usds/us-forms-system/images/Boolean-checkbox.jpg)

 #### Usage guidelines

 In `formConfig`, define this in the data definition.

-For the code implementation, see [`CheckboxWidget`](https://github.com/usds/us-forms-system/blob/master/src/js/widgets/CheckboxWidget.jsx).
+For more information about this widget, see [`CheckboxWidget`](https://github.com/usds/us-forms-system/blob/master/src/js/widgets/CheckboxWidget.jsx).


Ah, I see you intentionally changed this... happy to discuss!

bernars-usa · 2018-07-17T17:23:42Z

docs/building-a-form/available-components.md

@@ -204,7 +266,32 @@ This indicates to the user that they have either not filled out a required field

 #### Usage guidelines

- ?
+Adding a field to the `required` property in `schema` will automatically render an error on the field if it is blank. There are [default error messages](/src/js/validations.js#L24) for different situations. If you want to display a custom error message, add the message you want to the `ui:errorMessages` object in the `uiSchema`. You must add the error message as a key value pair: the key is the `schema` property that the data is in violation of (e.g., the entry doesn't match the requirements of the `pattern` property), and the value is the text of the error message. You may have more than 1 message in the `ui:errorMessages` object; they will be evaluated in order.


Adding a field to the required property in schema will automatically render an error on the field if it is blank. There are default error messages for different situations. If you want to display a custom error message, add the message you want to the ui:errorMessages object in the uiSchema. You must add the error message as a key value pair: the key is the schema property that the data is in violation of (e.g., the entry doesn't match the requirements of the pattern property), and the value is the text of the error message. You may have more than 1 message in the ui:errorMessages object; they will be evaluated in order.

How about:

If you add a blank field to the required property in schema, one of several default error messages will render. To show a custom error message, add the message to the ui:errorMessages object in the uiSchema as a key value pair:

The key is the schema property that the data is in violation of (e.g., the entry doesn't match the requirements of the pattern property)

The value is the text of the error message.

When you include multiple messages in the ui:errorMessages object, they're evaluated in order.

It's not that you add a blank field, but rather adding the name of the field to the required property will trigger an error if that field is blank when the user tries to go to the next page. I think I can rephrase that part slightly, but keep the rest of your wording.

bernars-usa

Just a few more comments here. Once those are addressed, this is ready to roll! Thanks again for your help here, Anne!

bernars-usa · 2018-07-18T14:01:15Z

docs/building-a-form/adding-widgets-and-definitions.md

-`SSNWidget` |
-`TextWidget` | type: `string`
-`YesNoWidget` |
+`ArrayCountWidget` | In the 'uiSchema', specify `'ui:widget': ArrayCountWidget` for the given field


Some of these descriptions are using straight quotes and some backticks. I think they all need to be backticks.

good catch!

bernars-usa · 2018-07-18T14:02:37Z

docs/building-a-form/available-components.md

@@ -170,9 +169,35 @@ A group of options where the user can only select a single item.

 #### Usage guidelines

-In `formConfig`, define this in the data definition.
+The data for a group of radio buttons will be quite similar to the data for a select field (i.e., `string` type with an `enum` property), which means the `SelectWidget` will by default be rendered.


... which means the SelectWidget will by default be rendered.

"... which means the SelectWidget will be rendered by default."

bernars-usa · 2018-07-18T14:06:01Z

docs/building-a-form/available-components.md


-For the code implementation, see [`RadioWidget`](https://github.com/usds/us-forms-system/blob/master/src/js/widgets/RadioWidget.jsx).
+For more information about this widget, see [`RadioWidget`](https://github.com/usds/us-forms-system/blob/master/src/js/widgets/RadioWidget.jsx).


Were you for or against my reasoning for using the explicit "For the code implementation..." phrasing in #166 (comment)? I'm guessing this doesn't feel explicit to you, in which case, do you want to just remove the links to these files altogether? It's entirely possible it's just too much information in this context.

Ah no sorry I just misread what these links were! I can change that

bernars-usa · 2018-07-18T14:11:32Z

docs/building-a-form/available-components.md

@@ -182,9 +207,45 @@ A group of options where the user can select multiple items.

 #### Usage guidelines

-In `formConfig`, define this in the data definition.
+Each individual checkbox is used to store `boolean` data. If you want to include a group of checkboxes, you would include separate fields for each checkbox, with `type: 'boolean'` passed to the `schema`.


If you want to include a group of checkboxes, you would include separate fields for each checkbox, with type: 'boolean' passed to the schema.

A little tighter: "To include a group of checkboxes, include separate fields for each checkbox, with type: 'boolean' passed to the schema."

bernars-usa · 2018-07-18T14:12:36Z

docs/building-a-form/available-components.md

+}
+```
+
+For more information about this widget, see [`CheckboxWidget`](https://github.com/usds/us-forms-system/blob/master/src/js/widgets/CheckboxWidget.jsx).


Same question here (I wish I could link to a pending comment!):

Were you for or against my reasoning for using the explicit "For the code implementation..." phrasing in #166 (comment)? I'm guessing this doesn't feel explicit to you, in which case, do you want to just remove the links to these files altogether? It's entirely possible it's just too much information in this context.

bernars-usa · 2018-07-18T14:20:19Z

docs/building-a-form/available-components.md


-### Password
+To show an error on a blank field that is required, include the field in the array under the `required` property in the `schema`. An error on that field will automatically be rendered if the field is blank.


To tie these two points (lines 270 and 272) more closely to the expository paragraph in 268, can you make them bullets under that paragraph, like so?

There are several ways in which form fields can be invalid, such as a blank required field, the entry is too short or long, or the entry does not satisfy a specific format.

To show an error on a blank field that is required, include the field in the array under the required property in the schema. An error on that field will automatically be rendered if the field is blank.

To show an error on a field for any other reason (e.g., it has not met certain data requirements), pass a validation function to the array for the ui:validations property under that field in uiSchema.

☝️ I added the bold there to further differentiate between the two options; let me know if that seems like too much.

yep that makes sense!

dmethvin-gov

Looks good to me!

* 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

@annekainicUSDS

* 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

annekainicUSDS requested review from bernars-usa and dmethvin-gov July 16, 2018 23:17

bernars-usa suggested changes Jul 17, 2018

View reviewed changes

bernars-usa approved these changes Jul 18, 2018

View reviewed changes

dmethvin-gov approved these changes Jul 18, 2018

View reviewed changes

Kainic added 6 commits July 18, 2018 11:04

Complete table with widget information

545585c

Add more description for some components

878e2aa

Add usage info for error messages

4eb11e4

Edits from review

312f07e

Remove password description

da719bb

Make review edits

9e191af

annekainicUSDS force-pushed the add-widget-descriptions branch from 25aecf9 to 9e191af Compare July 18, 2018 15:05

annekainicUSDS merged commit e13e95a into component-cleanup Jul 18, 2018

annekainicUSDS deleted the add-widget-descriptions branch July 18, 2018 15:21

annekainicUSDS mentioned this pull request Jul 19, 2018

Surface more information about widgets #138

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add widget descriptions #166

Add widget descriptions #166

annekainicUSDS commented Jul 16, 2018

annekainicUSDS commented Jul 17, 2018

bernars-usa left a comment

bernars-usa Jul 17, 2018

bernars-usa Jul 17, 2018

annekainicUSDS Jul 17, 2018 •

edited

Loading

bernars-usa Jul 17, 2018

bernars-usa Jul 17, 2018

bernars-usa Jul 17, 2018

annekainicUSDS Jul 17, 2018

bernars-usa Jul 18, 2018

bernars-usa Jul 17, 2018

annekainicUSDS Jul 17, 2018

bernars-usa Jul 17, 2018

bernars-usa Jul 17, 2018

annekainicUSDS Jul 17, 2018

bernars-usa left a comment

bernars-usa Jul 18, 2018

annekainicUSDS Jul 18, 2018

bernars-usa Jul 18, 2018

bernars-usa Jul 18, 2018

annekainicUSDS Jul 18, 2018

bernars-usa Jul 18, 2018

bernars-usa Jul 18, 2018

bernars-usa Jul 18, 2018

annekainicUSDS Jul 18, 2018

dmethvin-gov left a comment


		For the code implementation, see [`RadioWidget`](https://github.com/usds/us-forms-system/blob/master/src/js/widgets/RadioWidget.jsx).
		In order to override the `SelectWidget`, you must pass `'ui:widget': 'radio'` to your `uiSchema` for that field. If you also want to specify different label text for each option, you would pass `'ui:options'` to `uiSchema`.


		### Password
		To show an error on a blank field that is required, include the field in the array under the `required` property in the `schema`. An error on that field will automatically be rendered if the field is blank.

Add widget descriptions #166

Add widget descriptions #166

Conversation

annekainicUSDS commented Jul 16, 2018

Description

annekainicUSDS commented Jul 17, 2018

bernars-usa left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

annekainicUSDS Jul 17, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bernars-usa left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dmethvin-gov left a comment

Choose a reason for hiding this comment

annekainicUSDS Jul 17, 2018 •

edited

Loading