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

Update documentation for definitions #231

Closed
annekainicUSDS opened this issue Aug 20, 2018 · 3 comments
Closed

Update documentation for definitions #231

annekainicUSDS opened this issue Aug 20, 2018 · 3 comments
Assignees
Labels
[type] documentation Documentation related work

Comments

@annekainicUSDS
Copy link
Contributor

Now that we merged this PR, which changes how the definitions are used, we need to update our documentation.

There were a few main changes to how definitions work that we need to address:

  1. For the remaining definitions (I also deleted some), they used to just include uiSchema. I added the schema as well, so they now export an object with both the schema and uiSchema.
  2. The naming convention I've followed for all definitions is each one exports an object which is the name of the definition + Config. Example: the currency definition exports an object called currencyConfig. You can verify what each exported object is called by looking at the bottom of each definition file. The exported object returns 2 things: the schema and uiSchema, which are named the same for each definition.
  3. I made all schema and uiSchema functions, whereas before some were functions and some were just objects. This means that the way you use them is slightly different. When they were just objects, you would use them in the config by just listing the name (e.g., for the ssn field (https://github.com/usds/us-forms-system/blob/master/docs/building-a-form/common-definitions.md#social-security-number), after importing the uiSchema at the top of the file, you would call it in the config by writing ssnUI. Now, you need to call it by first referring to the exported object (ssnConfig), calling the schema or uiSchema within it using dot notation (ssnConfig.uiSchema), and then adding parens to the end (ssnConfig.uiSchema()).
  4. Some uiSchema take optional arguments in the function (e.g., ssnConfig.uiSchema optionally takes a title, so if you wanted to change the title from the default you would pass your title to the function like so: ssnConfig.uiSchema('New title')). Not all schema and uiSchema take optional arguments though. You can see which ones do and what their arguments are by referring to the definition files and seeing which functions include an argument in the parens for schema and uiSchema.

For the new documentation, I don't think you need to include the level of detail I included above; that was mainly to make sure it's clear to who will be documenting this! I think just describing that each definition exports an object that includes both schema and uiSchema, and that both schema and uiSchema are functions will be sufficient. Then showing with a code sample how you call those schema and uiSchema for each definition will be useful, and including info on which ones take optional arguments.

For an example of how they're all called, you can look at this test branch on the starter-app: https://github.com/usds/us-forms-system-starter-app/compare/test-new-schema-additions-to-usfs?expand=1.

Let me know if there are any questions!

@annekainicUSDS annekainicUSDS added the [type] documentation Documentation related work label Aug 20, 2018
@bernars-usa bernars-usa self-assigned this Aug 21, 2018
@bernars-usa
Copy link
Contributor

For the remaining definitions (I also deleted some)

Are you saying you deleted definitions in #225? I'm not seeing them, but I could be missing... a lot of things. 😉

@annekainicUSDS
Copy link
Contributor Author

Ah sorry, I deleted them in a separate PR (#214), but I think you had already updated the docs to reflect this.

@bernars-usa
Copy link
Contributor

Cool, that's what I thought! Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
[type] documentation Documentation related work
Projects
None yet
Development

No branches or pull requests

2 participants