Skip to content

Commit 6bfd402

Browse files
OJ423gitbook-bot
OJ423
authored and
gitbook-bot
committed
GITBOOK-142: Updated Doc SDK UI
1 parent 6fb0433 commit 6bfd402

File tree

1 file changed

+57
-73
lines changed
  • document-ui-sdk/use-the-document-ui-sdk

1 file changed

+57
-73
lines changed

‎document-ui-sdk/use-the-document-ui-sdk/README.md‎

Lines changed: 57 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,9 @@ description: Create UIs directly from TerminusDB's schema
44

55
# Use the Document UI SDK
66

7-
Use the TerminusDB documents User Interface (UI) utility `terminusdb-documents-ui` to automatically generate customizable user interfaces for the document definitions in your TerminusDB schema. The utility takes frames as input and outputs forms in HTML format. A frame is the JSON structure of a JSON document, including the document's inherited properties and IRIs.
7+
Use the TerminusDB documents User Interface (UI) utility `terminusdb-documents-ui` to automatically generate user interfaces for the document definitions in your TerminusDB schema. The utility takes frames as input and outputs forms in HTML format. A frame is the JSON structure of a JSON document, including the document's inherited properties and IRIs.
88

9-
### Install and import
9+
#### Install and import
1010

1111
Install the utility from `npm`:
1212

@@ -20,48 +20,68 @@ Import the `FrameViewer` component into your code:
2020
import {FrameViewer} from '@terminusdb/terminusdb-documents-ui'
2121
```
2222

23-
### The FrameViewer object
23+
Import the `FrameViewer` css into your code:
2424

25-
Use the `FrameViewer` object of `terminusdb-documents-ui` to configure, customize, and display your forms. `FrameViewer` supports several parameters and functions.
25+
For dark mode include the below css
2626

27-
#### FrameViewer parameters
27+
```
28+
import '@terminusdb/terminusdb-documents-ui/dist/css/terminusdb__darkly.css'
29+
```
30+
31+
light mode
32+
33+
```
34+
import '@terminusdb/terminusdb-documents-ui/dist/css/terminusdb__light.css'
35+
```
36+
37+
#### The FrameViewer object
38+
39+
Use the `FrameViewer` object of `terminusdb-documents-ui` to configure and display your forms. `FrameViewer` supports several parameters and functions.
40+
41+
**FrameViewer parameters**
2842

2943
| **Parameter** | **Description** |
3044
| ------------- | ------------------------------------------------------------------------------------------------------------ |
3145
| `frame` | The JSON frame structure of a TerminusDB schema. |
32-
| `uiFrame` | JSON UI properties to customize the appearance of a form. |
33-
| `type` | The document type definition in your schema to display the form for. |
3446
| `mode` | Form modes - `Create`, `Edit`, or `View`. |
3547
| `formData` | The data entered into or provided for a form. Specify `formData` in `Edit` and `View` modes to display data. |
36-
| `hideSubmit` | Hide the `Submit` button to show view-only data. |
48+
| `type` | document type of interest to be displayed in form. |
49+
| `language` | language code parameters to support a wide variety of languages in UI as defined in schema |
50+
51+
**FrameViewer functions**
3752

38-
#### FrameViewer functions
53+
| **Function** | **Description** |
54+
| ------------ | ---------------------------------------------------------------------------------------------------- |
55+
| `onSubmit` | A customizable JavaScrpt (JS) callback function to process data submitted via a form. |
56+
| `onSelect` | JS callback function to retrieve the selected values from a `Select` component. |
57+
| `onTraverse` | Return the ID of a document on a click event. Useful for binding an `onClick` event with a document. |
3958

40-
| **Function** | **Description** |
41-
| --------------- | ---------------------------------------------------------------------------------------------------- |
42-
| `onSubmit` | A customizable JavaScrpt (JS) callback function to process data submitted via a form. |
43-
| `onChange` | A customizable JS callback function to process data when form data is changed. |
44-
| `onSelect` | JS callback function to retrieve the selected values from a `Select` component. |
45-
| `onTraverse` | Return the ID of a document on a click event. Useful for binding an `onClick` event with a document. |
46-
| `FieldTemplate` | Customize the appearance of a form. |
59+
**FrameViewer Mandatory props**
4760

48-
### FrameViewer common usage
61+
| props | Mandatory |
62+
| -------- | ------------------------------------------------------------------------------------------------ |
63+
| frame | true |
64+
| type | true |
65+
| mode | true |
66+
| formData | formData has to be mandatory in Edit or View mode. If nothing to display then pass empty json {} |
67+
68+
#### FrameViewer common usage
4969

5070
A common use of `terminusdb-documents-ui` is as follows:
5171

5272
1. Set up a Webpack.
53-
2. Use the [TerminusDB JavaScript client](../../guides/reference-guides/javascript-client-reference/woqlclient.md).
73+
2. Use the TerminusDB JavaScript client.
5474
3. Use the client function `getSchemaFrame` to retrieve frame data from a TerminusDB database.
5575
4. Set custom values and behaviour for `FrameViewer` parameters and functions as required.
5676
5. Call `FrameViewer` to display frame data in the specified form.
5777

58-
### Get schema frame data from a database
78+
#### Get schema frame data from a database
5979

60-
A basic example below to get started with a TerminusDB JavaScript client.
80+
A basic example below to get started with a [TerminusDB JavaScript client](../../guides/reference-guides/javascript-client-reference/woqlclient.md).
6181

6282
```javascript
6383
const TerminusDBClient = require("@terminusdb/terminusdb-client");
64-
84+
import '@terminusdb/terminusdb-documents-ui/dist/css/terminusdb__darkly.css'
6585
import {FrameViewer} from '@terminusdb/terminusdb-documents-ui'
6686

6787
try {
@@ -73,17 +93,17 @@ try {
7393
}
7494
```
7595

76-
### FrameViewer usage step-by-step
96+
#### FrameViewer usage step-by-step
7797

7898
Use three simple steps - input, configure, and output:
7999

80-
[Step 1. Create frame data](./#step-1.-create-frame-data)
100+
[Step 1. Create frame data](..#step-1.-create-frame-data)
81101

82-
[Step 2. Configure properties and functions](./#step-2.-configure-properties-and-functions)
102+
[Step 2. Configure properties and functions](..#step-2.-configure-properties-and-functions)
83103

84-
[Step 3. Generate the form](./#step-3.-generate-the-form)
104+
[Step 3. Generate the form](..#step-3.-generate-the-form)
85105

86-
#### Step 1. Create frame data
106+
**Step 1. Create frame data**
87107

88108
For simplicity, all examples use the `frames` definition below consisting of one document `Person`.
89109

@@ -111,19 +131,11 @@ let frames = {
111131
let type = "Person"
112132
```
113133

114-
#### Step 2. Configure properties and functions
134+
**Step 2. Configure properties and functions**
115135

116-
The example below generates an empty frame for the attributes of the `Person` document. The callback function `handleSubmit` displays any user-entered form data. Add functionality to `handleSubmit` to suit your requirements. The `uiFrames` parameter in the example adds customizations for your forms. See Customize the looks and feel of frames for details.
136+
The example below generates an empty frame for the attributes of the `Person` document. The callback function `handleSubmit` displays any user-entered form data. Add functionality to `handleSubmit` to suit your requirements.
117137

118138
```javascript
119-
// Create a place holder for the "Person" "name" property.
120-
121-
let uiFrames = {
122-
"name" : {
123-
"placeholder": "Please enter a name ..."
124-
}
125-
}
126-
127139
// Mode "Create" displays an empty frame.
128140

129141
let mode = "Create"
@@ -135,7 +147,7 @@ function handleSubmit(data) {
135147
}
136148
```
137149

138-
#### Step 3. Generate the form
150+
**Step 3. Generate the form**
139151

140152
Generate the form using the properties and functions defined in the previous step.
141153

@@ -144,30 +156,24 @@ Generate the form using the properties and functions defined in the previous ste
144156

145157
return <FrameViewer
146158
frame = {frames}
147-
uiFrame = {uiFrames}
148159
type = {type}
149-
onSelect = {handleSelect}
150160
mode = {mode}
151161
onSubmit = {handleSubmit}/>
152162
```
153163

154-
**Screen-print/s of the output:**
155-
156-
![](../../.gitbook/assets/documents-ui-get-started-01.PNG)
157-
158-
### FrameViewer modes
164+
#### FrameViewer modes
159165

160166
The `FrameViewer` object supports three modes:
161167

162-
* [Create](./#create-mode)
163-
* [Edit](./#edit-mode)
164-
* [View](./#view-mode)
168+
* [Create](..#create-mode)
169+
* [Edit](..#edit-mode)
170+
* [View](..#view-mode)
165171

166-
#### Create mode
172+
**Create mode**
167173

168174
The `Create` mode displays an empty frame as demonstrated in the previous example.
169175

170-
#### Edit mode
176+
**Edit mode**
171177

172178
The `Edit` mode displays populated and empty frames. This mode requires the `formData` parameter.
173179

@@ -199,17 +205,12 @@ function handleSubmit(data) {
199205
return <FrameViewer
200206
frame = {frames}
201207
type = {type}
202-
onSelect = {handleSelect}
203208
mode = {mode}
204209
formData = {formData}
205210
onSubmit = {handleSubmit}/>
206211
```
207212

208-
**Screen-print/s of the output:**
209-
210-
![](<../../.gitbook/assets/documents-ui-get-started-02 (2).PNG>)
211-
212-
#### View Mode
213+
**View Mode**
213214

214215
The `View` mode displays populated frames for view-only - the **Submit** button is automatically hidden. If the `formData` parameter is omitted, an empty form is displayed.
215216

@@ -241,24 +242,7 @@ function handleSubmit(data) {
241242
return <FrameViewer
242243
frame = {frames}
243244
type = {type}
244-
onSelect = {handleSelect}
245245
mode = {mode}
246246
formData = {formData}
247-
onSubmit = {handleSubmit}/>
247+
onSubmit = {handleSubmit}/>v
248248
```
249-
250-
**Screen-print/s of the output:**
251-
252-
![](<../../.gitbook/assets/documents-ui-get-started-03 (1).PNG>)
253-
254-
### Further Reading
255-
256-
The Document UI SDK reference guide:
257-
258-
[**Documents UI SDK data types**](ui-sdk-data-types/).
259-
260-
[**Documents UI SDK GeoJSON**](../ui-geoJSON/documents-user-interface-geoJSON.md)**.**
261-
262-
[**UI SDK Demo Playground**](https://documents-ui-playground.terminusdb.com/)**.**
263-
264-
[**TerminusDB JavaScript client reference guide**](../../guides/reference-guides/javascript-client-reference/woqlclient.md)**.**

0 commit comments

Comments
 (0)