-
Notifications
You must be signed in to change notification settings - Fork 34
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
Docs: Getting Started content for Documentation #96
Merged
Merged
Changes from all commits
Commits
Show all changes
29 commits
Select commit
Hold shift + click to select a range
99dabfe
Getting started topics and links in readmes
bernars-usa 7e1d785
Remove old Getting Started topic
bernars-usa a6b6162
Getting Started short descriptions
bernars-usa 7083cc5
Map shortdescs
bernars-usa a5f1e12
Main content for starter app topic
bernars-usa d6ebe8d
Structure for existing app topic
bernars-usa 38c32c9
Installation instructions
bernars-usa e328112
Instructions for required files
bernars-usa dd2b2e6
Missing topic
bernars-usa f1d0385
A little more about the routes file
bernars-usa f48aae1
Spacing, does it matter?
bernars-usa 2bc4870
Apparently it's bash
bernars-usa 7272c08
Standardize on 'US Forms System'
bernars-usa 64444c1
Merge forms-docs into getting-started
bernars-usa d92a508
Add a link to React tutorial, weird tweak to app.js description?
bernars-usa 301761f
Merge forms docs into getting-started
bernars-usa 3315bf8
Add prereqs
bernars-usa 21cf015
Move this list into a separate file so it can be referenced in both o…
bernars-usa f8d03cc
Link to the new file at the top of the other two
bernars-usa 306c08c
Revised 'Creating a new app' with a lot more instructions, including …
bernars-usa ce5cac4
Add links to Getting Started articles
bernars-usa 260b607
React link is elsewhere now
bernars-usa 7ec572f
Someday I'll learn Markdown
bernars-usa d4d7361
Merge forms-docs into getting-started
bernars-usa c52261a
Merge forms-docs into getting-started
bernars-usa b39fd15
Talk about how to view output
bernars-usa 5467b2c
Formation not required
bernars-usa aa68e4c
Minimum node.js 8.0.0
bernars-usa a56de80
Link to USWDS for funsies
bernars-usa File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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 was deleted.
Oops, something went wrong.
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 |
---|---|---|
@@ -1,7 +1,17 @@ | ||
# Getting started with the Forms System Library | ||
# Getting started with the US Forms System | ||
|
||
### Creating a new application with the US Forms System Starter App | ||
Depending on your needs, you can either create a brand new application from scratch or install the US Forms System in an existing application. | ||
|
||
### Installing the library in an existing application | ||
### [Tools for getting started with the US Forms System](#tools-for-getting-started-with-the-us-forms-system) | ||
|
||
Building a form using the US Forms System requires some minimum front-end development tools, as well as general knowledge of those tools. Where possible, we'll provide links to information about getting started with these tools. | ||
|
||
### [Creating a new application with the US Forms System Starter App](creating-a-new-application-with-the-us-forms-system-starter-app.md) | ||
|
||
The US Forms System Starter App creates the initial files, configuration, build process, and web server you need to start building your form immediately. | ||
|
||
### [Installing the US Forms System in an existing application](installing-the-library-in-an-existing-application.md) | ||
|
||
If you're using an existing React application, you can install the US Forms System in that app. | ||
|
||
[Back to *US Forms System Documentation*](/docs/README.md) |
61 changes: 61 additions & 0 deletions
61
...ting-started/creating-a-new-application-with-the-us-forms-system-starter-app.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,61 @@ | ||
# Creating a new application with the US Forms System Starter App | ||
|
||
The US Forms System Starter App creates the initial files, configuration, build process, and web server you need to start building your form. | ||
|
||
Before you begin, review "[Tools for getting started with the US Forms System](getting-started/tools-for-getting-started-with-the-us-forms-system)." | ||
|
||
### In this guide | ||
|
||
- [Clone the Starter App repository and change the remote URL](#clone-the-starter-app-repository-and-change-the-remote-url) | ||
- [Install dependencies](#install-dependencies) | ||
- [Build and run your app](#build-and-run-your-app) | ||
|
||
### Clone the Starter App repository and change the remote URL | ||
|
||
1. Clone the us-forms-system-starter-app repository to your computer: | ||
```bash | ||
$ git clone https://github.com/usds/us-forms-system-starter-app.git | ||
``` | ||
2. Change the current directory to the new us-forms-system-starter-app directory: | ||
```bash | ||
$ cd us-forms-system-starter-app | ||
``` | ||
3. [On GitHub, create a new repository](https://help.github.com/articles/creating-a-new-repository/) named for your new forms app. | ||
4. From your new repository on GitHub, [copy the clone URL](https://help.github.com/articles/cloning-a-repository/). | ||
5. In Terminal (Mac and Linux) or the Command Prompt (Windows), review the current remote URL that's set to `origin`. The `fetch` and `push` URLs should be set to `https://github.com/usds/us-forms-system-starter-app.git`: | ||
```bash | ||
$ git remote -v | ||
# Lists all remote repositories, along with the URL for those remotes. | ||
origin https://github.com/usds/us-forms-system-starter-app.git (fetch) | ||
origin https://github.com/usds/us-forms-system-starter-app.git (push) | ||
``` | ||
6. Change your `origin` to use the URL for the new remote repository you created in Step 3 and copied in Step 4: | ||
```bash | ||
$ git remote set-url origin https://github.com/YOUR-USERNAME/YOUR-NEW-REPOSITORY-NAME.git | ||
# Changes 'origin' to the new remote's URL | ||
``` | ||
7. Review your current remote URL again. `origin` should be set to *your* repository on GitHub, not https://github.com/usds/us-forms-system-starter-app.git: | ||
```bash | ||
$ git remote -v | ||
# Lists all remote repositories, along with the URL for those remotes. | ||
origin https://github.com/YOUR-USERNAME/YOUR-NEW-REPOSITORY-NAME.git (fetch) | ||
origin https://github.com/YOUR-USERNAME/YOUR-NEW-REPOSITORY-NAME.git (push) | ||
``` | ||
|
||
### Install dependencies | ||
|
||
Use npm to install dependencies specified in `us-forms-system-starter-app/package-lock.json`. | ||
|
||
1. [Make sure Node and npm are installed](tools-for-getting-started-with-the-us-forms-system#node-js-and-npm). | ||
2. In Terminal (Mac and Linux) or the Command Prompt (Windows), use npm to install dependencies for the Starter App: | ||
```bash | ||
$ npm install | ||
``` | ||
|
||
### Build and run your app | ||
|
||
Once your repository is set up and dependencies are installed, you can begin building your app by editing `/js/config/form.js`. For more information, see "[Creating a form config file](building-a-form/creating-a-form-config-file.md)." | ||
|
||
To run your app locally, in Terminal (Mac and Linux) or the Command Prompt (Windows), type `npm start`. Once the server has started, you can view your form in a browser window at `localhost:8080`. | ||
|
||
[Back to *Getting Started with the US Forms System*](README.md) |
36 changes: 36 additions & 0 deletions
36
docs/getting-started/installing-the-us-forms-system-in-an-existing-application.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,36 @@ | ||
# Installing the US Forms System in an existing application | ||
|
||
If you're using an existing React application, you can install the US Forms System in that app. | ||
|
||
Before you begin, review "[Tools for getting started with the US Forms System](getting-started/tools-for-getting-started-with-the-us-forms-system)." | ||
|
||
### In this guide | ||
|
||
- [Install the library and dependencies](#install-the-library-and-dependencies) | ||
- [Create required files](#create-required-files) | ||
|
||
### Install the library and dependencies | ||
|
||
1. Install the library: | ||
```bash | ||
npm install --save https://github.com/usds/us-forms-system.git | ||
``` | ||
|
||
2. Install the [US Web Design System](https://github.com/uswds/uswds) and React dependencies: | ||
```bash | ||
npm install --save-dev uswds@^1.6.3 | ||
npm install --save-dev react@^15.5.4 | ||
npm install --save-dev react-dom@^15.6.2 | ||
``` | ||
|
||
### Create required files | ||
|
||
To enable your form, create the following files. For an example of these files, see the [us-forms-system-starter-app repository](https://github.com/usds/us-forms-system-starter-app). | ||
|
||
- A [form config file](https://github.com/usds/us-forms-system-starter-app/blob/master/js/config/form.js). For more information, see "Creating a form config file." | ||
- An entry [app.js](https://github.com/usds/us-forms-system-starter-app/blob/master/app.js) file. | ||
- A [React component](https://github.com/usds/us-forms-system-starter-app/blob/master/js/components/Form.jsx) to render the top-level us-forms-system component. | ||
- A [routes file](https://github.com/usds/us-forms-system-starter-app/blob/master/js/routes.jsx) that loads `createRoutes` from us-forms-system. This automatically creates the routes from the form config file. | ||
- A [reducers file](https://github.com/usds/us-forms-system-starter-app/blob/master/js/reducers.js) that loads `createSchemaFormReducer` from us-forms-system. This creates the app's reducer functions. | ||
|
||
[Back to *Getting Started with the US Forms System*](README.md) |
36 changes: 36 additions & 0 deletions
36
docs/getting-started/tools-for-getting-started-with-the-us-forms-system.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,36 @@ | ||
# Tools for getting started with the US Forms System | ||
|
||
Building a form using the US Forms System requires some minimum front-end development tools, as well as general knowledge of those tools. Where possible, we'll provide links to information about getting started with these tools. | ||
|
||
### In this guide | ||
|
||
- [Command line interface (CLI)](#command-line-interface-cli) | ||
- [JavaScript](#javascript) | ||
- [Node.js and npm](#node-js-and-npm) | ||
- [React](#react) | ||
- [JSON Schema](#json-schema) | ||
- [react-jsonschema-form (rjsf)](#react-jsonschema-form-rjsf) | ||
|
||
### Command line interface (CLI) | ||
|
||
You should be comfortable using command line tools such as Terminal (Mac and Linux) or Command Prompt (Windows). These tools come pre-installed on nearly all computers. There are several tutorials of various types available online to learn about the CLI. | ||
|
||
### JavaScript | ||
|
||
Most technologies the US Forms System uses, such as React, are centered around JavaScript. We recommend basic familiarity with JavaScript to build forms with the US Forms System. For more information about JavaScript, including tutorials for getting started, see [Pluralsight's JavaScript website](https://www.javascript.com/). | ||
|
||
### Node.js and npm | ||
|
||
Node.js is a JavaScript runtime environment that allows you to execute complete JavaScript programs. When you install Node.js, it automatically installs a package manager called npm. You need both Node.js (minimum version 8.0.0) and npm to develop using the US Forms System. For more information, including installation instructions, see the [Node.js website](https://nodejs.org). | ||
|
||
### React | ||
|
||
React is a JavaScript library for building user interfaces (UI). For more information, including tutorials for getting started, see the [React.js website](https://reactjs.org/). | ||
|
||
##### JSON Schema | ||
|
||
JSON Schema is a concise method of describing JSON data. We recommend basic familiarity with JSON Schema to build forms with the US Forms System. For more information about JSON Schema, see [Understanding JSON Schema](https://spacetelescope.github.io/understanding-json-schema/) by the Space Telescope Science Institute. | ||
|
||
##### react-jsonschema-form (rjsf) | ||
|
||
rjsf is a React component maintained by Mozilla that's used to build web forms based on JSON Schema. For more information, see the [react-jsonschema-form documentation](https://github.com/mozilla-services/react-jsonschema-form#react-jsonschema-form). |
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@annekainicUSDS - Is this an acceptable description?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yes I think so