Updated documentation for the Form and MessageSystem (#217)
# Pull Request ## 📖 Description <!--- Provide some background and a description of your work. --> 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 <!--- Provide some notes for reviewers to help them provide targeted feedback and testing. --> 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 <!--- Review the list and put an x in the boxes that apply. --> - [ ] I have added tests for my changes. - [ ] I have tested my changes. - [x] I have updated the project documentation to reflect my changes.
This commit is contained in:
Jane Chu
GitHub
Родитель
39edee754c
Коммит
904ee3b834
|
|
@ -225,7 +225,7 @@ function convertMarkdownDocumentation(category, template, isVersionDoc) {
|
|||
html: templateResolver(template)({
|
||||
htmlWebpackPlugin: {
|
||||
options: {
|
||||
content: templateResolver(
|
||||
index: templateResolver(
|
||||
fs.readFileSync(categoryTemplate, "utf8")
|
||||
)({
|
||||
items,
|
||||
|
|
|
|||
|
|
@ -1,2 +1,65 @@
|
|||
# Form
|
||||
TBD
|
||||
|
||||
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";
|
||||
|
||||
<Form messageSystem={fastMessageSystem} />
|
||||
```
|
||||
|
||||
### 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";
|
||||
|
||||
<DndProvider backend={HTML5Backend}>
|
||||
<ModularForm messageSystem={fastMessageSystem} />
|
||||
</DndProvider>
|
||||
```
|
||||
|
||||
## 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";
|
||||
|
||||
<Form
|
||||
messageSystem={fastMessageSystem}
|
||||
controls={[
|
||||
new StandardControlPlugin({
|
||||
id: "foo",
|
||||
control: (config) => {
|
||||
return (
|
||||
<input
|
||||
value={config.value}
|
||||
/>
|
||||
)
|
||||
}
|
||||
})
|
||||
]}
|
||||
/>
|
||||
```
|
||||
|
|
@ -1,2 +1,49 @@
|
|||
# Data Format
|
||||
TBD
|
||||
|
||||
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<unknown> = [
|
||||
"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`
|
||||
|
|
@ -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
|
||||
## 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,
|
||||
});
|
||||
```
|
||||
|
|
@ -1,3 +1,7 @@
|
|||
# Introduction
|
||||
|
||||
Welcome to FAST tooling, an ecosystem of packages built for the purpose of live updating JSON data.
|
||||
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/).
|
||||
|
|
@ -33,11 +33,6 @@ export default {
|
|||
label: "Introduction",
|
||||
path: "introduction",
|
||||
},
|
||||
{
|
||||
type: "doc",
|
||||
label: "Examples",
|
||||
path: "examples",
|
||||
},
|
||||
{
|
||||
type: "category",
|
||||
label: "Message System",
|
||||
|
|
|
|||
|
|
@ -15,10 +15,11 @@
|
|||
<%= htmlWebpackPlugin.options.isFrontpage ? "" :
|
||||
htmlWebpackPlugin.options.sidebar %>
|
||||
|
||||
<div class="content">
|
||||
<div class="container">
|
||||
<%= htmlWebpackPlugin.options.versionInfo ?
|
||||
htmlWebpackPlugin.options.versionInfo : "" %> <%=
|
||||
htmlWebpackPlugin.options.content %>
|
||||
htmlWebpackPlugin.options.versionInfo : "" %>
|
||||
<div class="content"><%= htmlWebpackPlugin.options.content %></div>
|
||||
<div class="index"><%= htmlWebpackPlugin.options.index %></div>
|
||||
</div>
|
||||
</main>
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -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 {
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче