Skip to content
This repository was archived by the owner on Mar 7, 2024. It is now read-only.

Commit 5330ff8

Browse files
author
Morten Christensen
committed
Exported all gui model classes + added more doc
1 parent e05cec9 commit 5330ff8

File tree

6 files changed

+186
-8
lines changed

6 files changed

+186
-8
lines changed

‎README.md‎

Lines changed: 56 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,49 @@
11
# json-schema-js-gui-model
2-
Handy gui model and associated translator that can be used to construct javascript UI forms from json-schemas
2+
Handy framework-agnostic gui model and associated translator that can be used as a basis when constructing
3+
dynamic javascript UI forms (in any web framework) from json-schemas. For details, refer to the declared gui
4+
model [here](dist/lib/gui-model.d.ts) and the translator [here](dist/lib/gui-model.mapper.d.ts).
35

4-
WARNING: Work in progress.
6+
Clients of this library are themselves responsible for constructing a GUI using
7+
the gui model provided by this library. Such UI code will be different depending
8+
on the exact web framework used and this out of scope of this more
9+
fundamental and general project.
510

6-
Schemas can be translated using the exported GuiModelMapper class or by using the command line
7-
client linked by npm: ```mapToGuiModel sourceSchema destFile```
11+
This library is on purpose keept small with no runtime-dependencies. It can be used from both nodejs v6+
12+
and with a modern es6 capable browser.
13+
14+
## Getting started
15+
16+
Schemas can be translated using the exported GuiModelMapper class or by the the command line
17+
command *mapToGuiModel* when the library is installed with -g option by npm.
18+
19+
```npm install json-schema-js-gui-model```
20+
21+
Code:
22+
```typescript
23+
import { GuiModelMapper, GuiModel, JsonSchema } from 'json-schema-js-gui-model';
24+
25+
let mapper: GuiModelMapper = new GuiModelMapper();
26+
let input: JsonSchema = ... schema ...
27+
let output: GuiModel = mapper.mapToGuiModel(input);
28+
29+
```
30+
31+
Command-line: (requires global npm install)
32+
```
33+
mapToGuiModel sourceSchema destFile
34+
```
35+
36+
## The gui model and it's usage
37+
38+
The gui model is intended for easy consumption when visualizing a UI form. The gui model does not
39+
contain any validation elements.
40+
41+
The constructed UI should still use the json schema for validation purposes. If the form is
42+
carefully constructed the output will conform to the underlaying json schema when valid. A fast
43+
schema validator like [ajv](https://github.com/epoberezkin/ajv) can easily do validation of a from
44+
in realtime at each keypress if necessary.
45+
46+
## Example from schema to gui model to ui form:
847

948
**Example input schema:**
1049
```
@@ -202,3 +241,16 @@ client linked by npm: ```mapToGuiModel sourceSchema destFile```
202241
}
203242
```
204243

244+
**Example of a corresponding UI form (for illustration only - not provided by this library):**
245+
246+
![Example UI form](docs/example_form.png)
247+
248+
249+
## Status and future plans
250+
251+
The current version appears to work fine in my own project but has not been tested beyond that.
252+
253+
I am considering to support some kind of json schema ui extensions in order to construct a even more detailed gui model.
254+
255+
256+

‎docs/example.gui.model.json‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
{
2+
"kind": "group",
3+
"name": "",
4+
"controlType": "group",
5+
"settingsObjectPath": "",
6+
"label": "",
7+
"tooltip": "",
8+
"isRoot": true,
9+
"required": true,
10+
"elements": [
11+
{
12+
"kind": "group",
13+
"name": "authentication",
14+
"controlType": "group",
15+
"settingsObjectPath": "authentication",
16+
"label": "Authentication",
17+
"tooltip": "an authentication description here",
18+
"isRoot": false,
19+
"required": false,
20+
"elements": [
21+
{
22+
"kind": "field",
23+
"name": "user",
24+
"controlType": "input",
25+
"label": "User",
26+
"tooltip": "a username",
27+
"settingsObjectPath": "authentication.user",
28+
"defaultValue": "",
29+
"required": true,
30+
"type": "string",
31+
"subType": "none"
32+
},
33+
{
34+
"kind": "field",
35+
"name": "password",
36+
"controlType": "input",
37+
"label": "Password",
38+
"tooltip": "a password",
39+
"settingsObjectPath": "authentication.password",
40+
"defaultValue": "",
41+
"required": true,
42+
"type": "string",
43+
"subType": "none"
44+
},
45+
{
46+
"kind": "field",
47+
"name": "scheme",
48+
"controlType": "input",
49+
"label": "scheme",
50+
"tooltip": "",
51+
"settingsObjectPath": "authentication.scheme",
52+
"defaultValue": "basic",
53+
"required": false,
54+
"type": "string",
55+
"subType": "none"
56+
},
57+
{
58+
"kind": "field",
59+
"name": "preemptive",
60+
"controlType": "yesno",
61+
"label": "preemptive",
62+
"tooltip": "",
63+
"settingsObjectPath": "authentication.preemptive",
64+
"defaultValue": true,
65+
"required": false,
66+
"type": "boolean",
67+
"subType": "none"
68+
}
69+
]
70+
},
71+
{
72+
"kind": "group",
73+
"name": "server",
74+
"controlType": "group",
75+
"settingsObjectPath": "server",
76+
"label": "Server",
77+
"tooltip": "",
78+
"isRoot": false,
79+
"required": false,
80+
"elements": [
81+
{
82+
"kind": "field",
83+
"name": "host",
84+
"controlType": "input",
85+
"label": "host",
86+
"tooltip": "",
87+
"settingsObjectPath": "server.host",
88+
"defaultValue": "",
89+
"required": false,
90+
"type": "string",
91+
"subType": "none"
92+
},
93+
{
94+
"kind": "field",
95+
"name": "port",
96+
"controlType": "input",
97+
"label": "port",
98+
"tooltip": "",
99+
"settingsObjectPath": "server.port",
100+
"defaultValue": 80,
101+
"required": false,
102+
"type": "integer",
103+
"subType": "none"
104+
},
105+
{
106+
"kind": "field",
107+
"name": "protocol",
108+
"controlType": "dropdown",
109+
"label": "protocol",
110+
"tooltip": "",
111+
"settingsObjectPath": "server.protocol",
112+
"defaultValue": "http",
113+
"values": [
114+
"http",
115+
"ftp"
116+
],
117+
"required": false,
118+
"type": "string",
119+
"subType": "none"
120+
}
121+
]
122+
}
123+
],
124+
"errors": []
125+
}

‎src/examples/example.schema.json‎ renamed to ‎docs/example.schema.json‎

File renamed without changes.

‎docs/example_form.png‎

118 KB
Loading

‎package.json‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"name": "json-schema-js-gui-model",
3-
"version": "0.1.1",
4-
"description": "Handy gui model and associated translator that can be used to construct javascript UI forms from json-schemas",
3+
"version": "0.1.2",
4+
"description": "Handy gui model and associated translator that is useful when constructing javascript UI forms from json-schemas",
55
"main": "dist/index.js",
66
"types": "dist/index.d.ts",
77
"scripts": {
@@ -11,7 +11,8 @@
1111
"build": "tsc",
1212
"build:watch": "tsc -w",
1313
"clean": "rimraf dist",
14-
"lint": "tslint src/**/*.ts"
14+
"lint": "tslint src/**/*.ts",
15+
"mapToGuiModel": "node dist/cli/index.js"
1516
},
1617
"bin": {
1718
"mapToGuiModel": "dist/cli/index.js"

‎src/index.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
export { GuiModel } from './lib/gui-model';
1+
export * from './lib/gui-model';
22
export { JsonSchema } from './dependencies/json-schema';
33
export { GuiModelMapper } from './lib/gui-model.mapper';
44

0 commit comments

Comments
 (0)