From 904ee3b834ae7deafd5c565a5cf8a0058ce60b58 Mon Sep 17 00:00:00 2001 From: Jane Chu <7559015+janechu@users.noreply.github.com> Date: Tue, 24 May 2022 09:17:07 -0700 Subject: [PATCH] Updated documentation for the Form and MessageSystem (#217) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit # Pull Request ## 📖 Description This change updates the documentation for the `Form` react component and the `MessageSystem` as well as adding supporting documentation for the data formats used by the `MessageSystem`. ## 👩‍💻 Reviewer Notes A few stylistic tweaks had to be made for the content to sit on the page correctly, these will be applied to the FAST CLI as well to maintain consistency. ## ✅ Checklist ### General - [ ] I have added tests for my changes. - [ ] I have tested my changes. - [x] I have updated the project documentation to reflect my changes. --- website/build/docs.js | 2 +- .../fast-tooling-react/2.x/components/form.md | 65 ++++++++++++++++- .../0.x/message-system/data-format.md | 49 ++++++++++++- .../0.x/message-system/introduction.md | 71 ++++++++++++++++++- website/docs/introduction.md | 6 +- website/docs/sidebar.js | 5 -- website/src/index.html | 7 +- website/src/templates/style/index.html | 14 +++- 8 files changed, 201 insertions(+), 18 deletions(-) diff --git a/website/build/docs.js b/website/build/docs.js index c0101ea..c0a5da0 100644 --- a/website/build/docs.js +++ b/website/build/docs.js @@ -225,7 +225,7 @@ function convertMarkdownDocumentation(category, template, isVersionDoc) { html: templateResolver(template)({ htmlWebpackPlugin: { options: { - content: templateResolver( + index: templateResolver( fs.readFileSync(categoryTemplate, "utf8") )({ items, diff --git a/website/docs/fast-tooling-react/2.x/components/form.md b/website/docs/fast-tooling-react/2.x/components/form.md index 7a58904..00feca9 100644 --- a/website/docs/fast-tooling-react/2.x/components/form.md +++ b/website/docs/fast-tooling-react/2.x/components/form.md @@ -1,2 +1,65 @@ # Form -TBD \ No newline at end of file + +The `Form` is a React component that generates fields based on the JSON Schema, so if a JSON Schema specifies a "type" of "string", a text input will appear. + +The component is pluggable and stylable, so if there is a requirement to replace any fields or change the styling to match the rest of your application, this is easy to do. + +## Usage + +The basic usage only requires the passing of the `MessageSystem`. The component will then register itself and begin sending and recieving data. + +```tsx +import { Form } from "@microsoft/fast-tooling-react"; + +
+``` + +### Modular Usage + +There are two exports for the `Form`, the default `Form` and `ModularForm`. The `ModularForm` is for use with any React component that may share a dependency on `react-dnd` such as the `Navigation` component, or the `Viewer`. It's safe to assume that if you are using more than one React component from the `@microsoft/fast-tooling-react` package you must use the `ModularForm`. + +```tsx +import { DndProvider } from "react-dnd"; +import HTML5Backend from "react-dnd-html5-backend"; +import { ModularForm } from "@microsoft/fast-tooling-react"; + + + + +``` + +## Styling + +The `Form` leverages [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) and the following are available: + +- `--fast-tooling-accent-color` +- `--fast-tooling-l1-color` +- `--fast-tooling-l4-color` +- `--fast-tooling-text-color` +- `--fast-tooling-l3-fill-color` +- `--fast-tooling-error-color` +- `--fast-tooling-floating-color` + +## Adding a custom control + +There may be occasions where a custom control will serve better than the default form elements provided by the `Form`. For this situation a `StandardControlPlugin` is made available that will provide the surrounding UI for the `Form` but allow the form element or custom control to be created. + +```tsx +import { ModularForm, StandardControlPlugin } from "@microsoft/fast-tooling-react"; + + { + return ( + + ) + } + }) + ]} +/> +``` \ No newline at end of file diff --git a/website/docs/fast-tooling/0.x/message-system/data-format.md b/website/docs/fast-tooling/0.x/message-system/data-format.md index 31ff0e1..d0dc3f7 100644 --- a/website/docs/fast-tooling/0.x/message-system/data-format.md +++ b/website/docs/fast-tooling/0.x/message-system/data-format.md @@ -1,2 +1,49 @@ # Data Format -TBD \ No newline at end of file + +Data must be formatted as JSON, and descriptions of data must follow JSON Schema. + +## Data dictionary + +The data dictionary is an array of two items, the first being the root item and the second being the dictionary of data. This is done to enable data nesting behavior. + +Example: +```ts +import { DataDictionary } from "@microsoft/fast-tooling"; + +const myDataDictionary: DataDictionary = [ + "root", + { + root: { + schemaId: "myTextSchema", + data: "Hello world" + } + } +] +``` + +## Schema dictionary + +The schema dictionary is a dictionary of possible JSON schemas that the data can conform to. The `$id` is used as the `key` in the dictionary object. + +Example: +```ts +import { SchemaDictionary } from "@microsoft/fast-tooling"; + +const mySchemaDictionary: SchemaDictionary = { + myTextSchema: { + title: "Text", + type: "text" + }, + myNumberSchema: { + title: "Number", + type: "number" + } +} +``` + +## JSON Schema caveats + +For ease of use, keep JSON Schemas as simple as possible. Avoid use of the following keywords which are currently not supported by the `@microsoft/fast-tooling` or `@microsoft/fast-tooling-react` packages: + +- `allOf` +- `$ref` \ No newline at end of file diff --git a/website/docs/fast-tooling/0.x/message-system/introduction.md b/website/docs/fast-tooling/0.x/message-system/introduction.md index a48ff42..8b4867a 100644 --- a/website/docs/fast-tooling/0.x/message-system/introduction.md +++ b/website/docs/fast-tooling/0.x/message-system/introduction.md @@ -1,7 +1,72 @@ # Message System -FAST tooling components rely on including a secondary script which contains a [web worker](https://developer.mozilla.org/en-US/docs/Web/API/Worker) called the message system. +FAST tooling components rely on including a script which contains a [web worker](https://developer.mozilla.org/en-US/docs/Web/API/Worker) as well as a class to manipulate the data being sent to and from it called the `MessageSystem`. -This worker performs all of the data manipulation and provides a navigational data structure based on data passed. +The worker performs all of the data manipulation as well as a navigational data structure based on data passed. The `MessageSystem` class allow functionality to "register" itself to accept and send data. -TBD \ No newline at end of file +## Getting started + +Add the web worker to your project, it is located at `@microsoft/fast-tooling/dist/message-system.min.js`. + +To initialize the `MessageSystem`, a config must be passed that includes the data, schemas, and web worker. + +Example: +```ts +const fastMessageSystem: MessageSystem = new MessageSystem({ + webWorker: fastMessageSystemWorker, + dataDictionary: [ + "root", + { + root: { + schemaId: "myTextSchema", + data: "Hello world" + } + } + ], + schemaDictionary: { + myTextSchema: { + title: "Text", + type: "text" + }, + }, +}); +``` + +To understand how the data dictionary and schema dictionary are structured and why, check out the section on [data formats](../data-format). + +### Webpack + +It is recommended that the `worker-loader` be used in a webpack project. This can look like the following setup: + +`webpack.config.js` +```js +module.exports = { + ...yourConfig, + module: { + rules: [ + { + test: /message\-system\.min\.js/, + use: { + loader: "worker-loader", + }, + }, + ], + }, +}; +``` + +`index.ts` +```ts +import FASTMessageSystemWorker from "@microsoft/fast-tooling/dist/message-system.min.js"; +import { MessageSystem } from "@microsoft/fast-tooling"; + +// Activate the worker +const fastMessageSystemWorker = new FASTMessageSystemWorker(); + +// Create a new MessageSystem instance and pass the MessageSystem web worker to it +const fastMessageSystem: MessageSystem = new MessageSystem({ + webWorker: fastMessageSystemWorker, + dataDictionary: dataDictionaryConfig as any, + schemaDictionary, +}); +``` \ No newline at end of file diff --git a/website/docs/introduction.md b/website/docs/introduction.md index c39681a..58b5ae8 100644 --- a/website/docs/introduction.md +++ b/website/docs/introduction.md @@ -1,3 +1,7 @@ # Introduction -Welcome to FAST tooling, an ecosystem of packages built for the purpose of live updating JSON data. \ No newline at end of file +Welcome to FAST tooling, an ecosystem of packages built for the purpose of live updating JSON data. + +The backbone of this ecosystem is the `MessageSystem`, use this as a starting point. You can then register web components, React components, and other pieces of functionality. The `@microsoft/fast-tooling` and `@microsoft/fast-tooling-react` packages offer a selection of web components, React components, and other integrations with existing libraries that you may find useful. + +Consider making your own functionality as well! Get started with setting up the [MessageSystem](../fast-tooling/0.x/message-system/introduction/). \ No newline at end of file diff --git a/website/docs/sidebar.js b/website/docs/sidebar.js index bc0ece6..ab87c14 100644 --- a/website/docs/sidebar.js +++ b/website/docs/sidebar.js @@ -33,11 +33,6 @@ export default { label: "Introduction", path: "introduction", }, - { - type: "doc", - label: "Examples", - path: "examples", - }, { type: "category", label: "Message System", diff --git a/website/src/index.html b/website/src/index.html index 7f639e4..1585273 100644 --- a/website/src/index.html +++ b/website/src/index.html @@ -15,10 +15,11 @@ <%= htmlWebpackPlugin.options.isFrontpage ? "" : htmlWebpackPlugin.options.sidebar %> -
+
<%= htmlWebpackPlugin.options.versionInfo ? - htmlWebpackPlugin.options.versionInfo : "" %> <%= - htmlWebpackPlugin.options.content %> + htmlWebpackPlugin.options.versionInfo : "" %> +
<%= htmlWebpackPlugin.options.content %>
+
<%= htmlWebpackPlugin.options.index %>
diff --git a/website/src/templates/style/index.html b/website/src/templates/style/index.html index b90dc92..1662171 100644 --- a/website/src/templates/style/index.html +++ b/website/src/templates/style/index.html @@ -51,6 +51,10 @@ font-family: var(--font-family); } + p { + line-height: 24px; + } + .toolbar { position: sticky; top: 0; @@ -163,7 +167,7 @@ } main > div { - margin-inline-start: 25px; + padding: 25px; } main div a { @@ -175,8 +179,12 @@ padding-inline-end: 20px; } - .content { - width: 100%; + .container { + max-width: 900px; + } + + .content ul { + list-style: inherit; } .frontpage {