|
| 1 | +--- |
| 2 | +description: Create UIs directly from TerminusDB's schema |
| 3 | +--- |
| 4 | + |
| 5 | +# Use the Document UI SDK |
| 6 | + |
| 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. |
| 8 | + |
| 9 | +### Install and import |
| 10 | + |
| 11 | +Install the utility from `npm`: |
| 12 | + |
| 13 | +``` |
| 14 | +npm install @terminusdb/terminusdb-documents-ui --save |
| 15 | +``` |
| 16 | + |
| 17 | +Import the `FrameViewer` component into your code: |
| 18 | + |
| 19 | +``` |
| 20 | +import {FrameViewer} from '@terminusdb/terminusdb-documents-ui' |
| 21 | +``` |
| 22 | + |
| 23 | +### The FrameViewer object |
| 24 | + |
| 25 | +Use the `FrameViewer` object of `terminusdb-documents-ui` to configure, customize, and display your forms. `FrameViewer` supports several parameters and functions. |
| 26 | + |
| 27 | +#### FrameViewer parameters |
| 28 | + |
| 29 | +| **Parameter** | **Description** | |
| 30 | +| ------------- | ------------------------------------------------------------------------------------------------------------ | |
| 31 | +| `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. | |
| 34 | +| `mode` | Form modes - `Create`, `Edit`, or `View`. | |
| 35 | +| `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. | |
| 37 | + |
| 38 | +#### FrameViewer functions |
| 39 | + |
| 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. | |
| 47 | + |
| 48 | +### FrameViewer common usage |
| 49 | + |
| 50 | +A common use of `terminusdb-documents-ui` is as follows: |
| 51 | + |
| 52 | +1. Set up a Webpack. |
| 53 | +2. Use the [TerminusDB JavaScript client](../../guides/reference-guides/javascript-client-reference/woqlclient.md). |
| 54 | +3. Use the client function `getSchemaFrame` to retrieve frame data from a TerminusDB database. |
| 55 | +4. Set custom values and behaviour for `FrameViewer` parameters and functions as required. |
| 56 | +5. Call `FrameViewer` to display frame data in the specified form. |
| 57 | + |
| 58 | +### Get schema frame data from a database |
| 59 | + |
| 60 | +A basic example below to get started with a TerminusDB JavaScript client. |
| 61 | + |
| 62 | +```javascript |
| 63 | +const TerminusDBClient = require("@terminusdb/terminusdb-client"); |
| 64 | + |
| 65 | +import {FrameViewer} from '@terminusdb/terminusdb-documents-ui' |
| 66 | + |
| 67 | +try { |
| 68 | + let type = "Person" // type is the a document class of interest |
| 69 | + let frames = await woqlClient.getSchemaFrame(type, woqlClient.db()) |
| 70 | + console.log(`Frames generated from ${woqlClient.db()}`, frames) |
| 71 | +} catch(err) { |
| 72 | + console.log("Error fetching frames", err) |
| 73 | +} |
| 74 | +``` |
| 75 | + |
| 76 | +### FrameViewer usage step-by-step |
| 77 | + |
| 78 | +Use three simple steps - input, configure, and output: |
| 79 | + |
| 80 | +[Step 1. Create frame data](./#step-1.-create-frame-data) |
| 81 | + |
| 82 | +[Step 2. Configure properties and functions](./#step-2.-configure-properties-and-functions) |
| 83 | + |
| 84 | +[Step 3. Generate the form](./#step-3.-generate-the-form) |
| 85 | + |
| 86 | +#### Step 1. Create frame data |
| 87 | + |
| 88 | +For simplicity, all examples use the `frames` definition below consisting of one document `Person`. |
| 89 | + |
| 90 | +```javascript |
| 91 | +let frames = { |
| 92 | + "@context": { |
| 93 | + "@base": "terminusdb:///data/", |
| 94 | + "@schema": "terminusdb:///schema#", |
| 95 | + "@type": "@context" |
| 96 | + }, |
| 97 | + "Person": { |
| 98 | + "@key": { |
| 99 | + "@type": "Random" |
| 100 | + }, |
| 101 | + "@type": "Class", |
| 102 | + "DOB": "xsd:dateTime", |
| 103 | + "active": "xsd:boolean", |
| 104 | + "age": "xsd:decimal", |
| 105 | + "name": "xsd:string" |
| 106 | + } |
| 107 | +} |
| 108 | + |
| 109 | +// The document to display the frame for. |
| 110 | + |
| 111 | +let type = "Person" |
| 112 | +``` |
| 113 | + |
| 114 | +#### Step 2. Configure properties and functions |
| 115 | + |
| 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. |
| 117 | + |
| 118 | +```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 | + |
| 127 | +// Mode "Create" displays an empty frame. |
| 128 | + |
| 129 | +let mode = "Create" |
| 130 | + |
| 131 | +// Callback to display form data. |
| 132 | + |
| 133 | +function handleSubmit(data) { |
| 134 | + console.log("Form data: ", data) |
| 135 | +} |
| 136 | +``` |
| 137 | + |
| 138 | +#### Step 3. Generate the form |
| 139 | + |
| 140 | +Generate the form using the properties and functions defined in the previous step. |
| 141 | + |
| 142 | +```javascript |
| 143 | +// Generate the form. |
| 144 | + |
| 145 | +return <FrameViewer |
| 146 | + frame = {frames} |
| 147 | + uiFrame = {uiFrames} |
| 148 | + type = {type} |
| 149 | + onSelect = {handleSelect} |
| 150 | + mode = {mode} |
| 151 | + onSubmit = {handleSubmit}/> |
| 152 | +``` |
| 153 | + |
| 154 | +**Screen-print/s of the output:** |
| 155 | + |
| 156 | + |
| 157 | + |
| 158 | +### FrameViewer modes |
| 159 | + |
| 160 | +The `FrameViewer` object supports three modes: |
| 161 | + |
| 162 | +* [Create](./#create-mode) |
| 163 | +* [Edit](./#edit-mode) |
| 164 | +* [View](./#view-mode) |
| 165 | + |
| 166 | +#### Create mode |
| 167 | + |
| 168 | +The `Create` mode displays an empty frame as demonstrated in the previous example. |
| 169 | + |
| 170 | +#### Edit mode |
| 171 | + |
| 172 | +The `Edit` mode displays populated and empty frames. This mode requires the `formData` parameter. |
| 173 | + |
| 174 | +```javascript |
| 175 | +// Mode "Edit" displays a frame with editable data. |
| 176 | + |
| 177 | +let mode = "Edit" |
| 178 | + |
| 179 | +// Add form data to populate the frame. |
| 180 | + |
| 181 | +let formData = { |
| 182 | + "@id": "Person/John%20Doe", |
| 183 | + "@type": "Person", |
| 184 | + first_name: "John", |
| 185 | + last_name: "Doe", |
| 186 | + age: "17", |
| 187 | + active: true, |
| 188 | + DOB: "2022-03-31T10:01:11.000Z" |
| 189 | +} |
| 190 | + |
| 191 | +// Callback to display form data. |
| 192 | + |
| 193 | +function handleSubmit(data) { |
| 194 | + console.log("Form data: ", data) |
| 195 | +} |
| 196 | + |
| 197 | +// Generate the form with formData paramter. |
| 198 | + |
| 199 | +return <FrameViewer |
| 200 | + frame = {frames} |
| 201 | + type = {type} |
| 202 | + onSelect = {handleSelect} |
| 203 | + mode = {mode} |
| 204 | + formData = {formData} |
| 205 | + onSubmit = {handleSubmit}/> |
| 206 | +``` |
| 207 | + |
| 208 | +**Screen-print/s of the output:** |
| 209 | + |
| 210 | +.PNG>) |
| 211 | + |
| 212 | +#### View Mode |
| 213 | + |
| 214 | +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. |
| 215 | + |
| 216 | +```javascript |
| 217 | +// Mode "View" displays populated frames. |
| 218 | + |
| 219 | +let mode = "View" |
| 220 | + |
| 221 | +// Add form data to populate the frame. |
| 222 | + |
| 223 | +let formData = { |
| 224 | + "@id": "Person/John%20Doe", |
| 225 | + "@type": "Person", |
| 226 | + first_name: "John", |
| 227 | + last_name: "Doe", |
| 228 | + age: "17", |
| 229 | + active: true, |
| 230 | + DOB: "2022-03-31T10:01:11.000Z" |
| 231 | +} |
| 232 | + |
| 233 | +// Callback to display form data. |
| 234 | + |
| 235 | +function handleSubmit(data) { |
| 236 | + console.log("Form data: ", data) |
| 237 | +} |
| 238 | + |
| 239 | +// Generate the form with formData paramter. |
| 240 | + |
| 241 | +return <FrameViewer |
| 242 | + frame = {frames} |
| 243 | + type = {type} |
| 244 | + onSelect = {handleSelect} |
| 245 | + mode = {mode} |
| 246 | + formData = {formData} |
| 247 | + onSubmit = {handleSubmit}/> |
| 248 | +``` |
| 249 | + |
| 250 | +**Screen-print/s of the output:** |
| 251 | + |
| 252 | +.PNG>) |
| 253 | + |
| 254 | +### Further Reading |
| 255 | + |
| 256 | +The Document UI SDK reference guide: |
| 257 | + |
| 258 | +[**Documents UI SDK data types**](documents-user-interface-data-types.md). |
| 259 | + |
| 260 | +[**Documents UI SDK customization**](documents-user-interface-customization.md)**.** |
| 261 | + |
| 262 | +[**Documents UI SDK Geographic Maps**](documents-user-interface-geographic-maps.md)**.** |
| 263 | + |
| 264 | +[**TerminusDB JavaScript client reference guide**](../../guides/reference-guides/javascript-client-reference/woqlclient.md)**.** |
0 commit comments