|
| 1 | +# JSON Forms HTML Renderer Web App |
| 2 | + |
| 3 | +A web application that converts JSON Forms schemas (uischema + schema) into semantic HTML forms. Built with Go and Echo framework. |
| 4 | + |
| 5 | +## Features |
| 6 | + |
| 7 | +- **Web Interface**: Paste your JSON schemas and instantly see the rendered HTML form |
| 8 | +- **Live Preview**: View the rendered form in real-time |
| 9 | +- **HTML Source**: Copy the generated HTML source code |
| 10 | +- **Example Templates**: Quick-start with built-in examples |
| 11 | +- **Complete JSON Forms Support**: Handles all standard UI schema elements (Control, VerticalLayout, HorizontalLayout, Group, Categorization, Category, Label) |
| 12 | +- **JSON Schema Validation**: Automatically generates HTML5 validation attributes |
| 13 | +- **Responsive Design**: Mobile-friendly forms with modern CSS |
| 14 | + |
| 15 | +## Quick Start |
| 16 | + |
| 17 | +### Prerequisites |
| 18 | + |
| 19 | +- Go 1.25 or higher |
| 20 | + |
| 21 | +### Installation |
| 22 | + |
| 23 | +```bash |
| 24 | +git clone https://github.com/tinybluerobots/jsonforms-html |
| 25 | +cd jsonforms-html |
| 26 | +go mod download |
| 27 | +``` |
| 28 | + |
| 29 | +### Running the Server |
| 30 | + |
| 31 | +```bash |
| 32 | +go run main.go |
| 33 | +``` |
| 34 | + |
| 35 | +The server will start on `http://localhost:8082` |
| 36 | + |
| 37 | +### Usage |
| 38 | + |
| 39 | +1. Open your browser and navigate to `http://localhost:8082` |
| 40 | +2. Paste your JSON Schema in the first textarea |
| 41 | +3. Paste your UI Schema in the second textarea |
| 42 | +4. Click "Generate HTML" |
| 43 | +5. View the rendered form in the Preview tab or copy the HTML source |
| 44 | + |
| 45 | +### Example Input |
| 46 | + |
| 47 | +**JSON Schema:** |
| 48 | +```json |
| 49 | +{ |
| 50 | + "type": "object", |
| 51 | + "properties": { |
| 52 | + "name": { |
| 53 | + "type": "string", |
| 54 | + "title": "Full Name" |
| 55 | + }, |
| 56 | + "email": { |
| 57 | + "type": "string", |
| 58 | + "format": "email", |
| 59 | + "title": "Email Address" |
| 60 | + }, |
| 61 | + "age": { |
| 62 | + "type": "integer", |
| 63 | + "minimum": 0, |
| 64 | + "maximum": 120, |
| 65 | + "title": "Age" |
| 66 | + } |
| 67 | + }, |
| 68 | + "required": ["name", "email"] |
| 69 | +} |
| 70 | +``` |
| 71 | + |
| 72 | +**UI Schema:** |
| 73 | +```json |
| 74 | +{ |
| 75 | + "type": "VerticalLayout", |
| 76 | + "elements": [ |
| 77 | + { |
| 78 | + "type": "Control", |
| 79 | + "scope": "#/properties/name" |
| 80 | + }, |
| 81 | + { |
| 82 | + "type": "Control", |
| 83 | + "scope": "#/properties/email" |
| 84 | + }, |
| 85 | + { |
| 86 | + "type": "Control", |
| 87 | + "scope": "#/properties/age" |
| 88 | + } |
| 89 | + ] |
| 90 | +} |
| 91 | +``` |
| 92 | + |
| 93 | +## API Endpoints |
| 94 | + |
| 95 | +### `GET /` |
| 96 | +Returns the web interface |
| 97 | + |
| 98 | +### `POST /render` |
| 99 | +Renders JSON Forms to HTML |
| 100 | + |
| 101 | +**Request Body:** |
| 102 | +```json |
| 103 | +{ |
| 104 | + "schema": { /* JSON Schema */ }, |
| 105 | + "uischema": { /* UI Schema */ } |
| 106 | +} |
| 107 | +``` |
| 108 | + |
| 109 | +**Response:** |
| 110 | +HTML string containing the rendered form |
| 111 | + |
| 112 | +**Example:** |
| 113 | +```bash |
| 114 | +curl -X POST http://localhost:8082/render \ |
| 115 | + -H "Content-Type: application/json" \ |
| 116 | + -d '{ |
| 117 | + "schema": {"type": "object", "properties": {"name": {"type": "string"}}}, |
| 118 | + "uischema": {"type": "VerticalLayout", "elements": [{"type": "Control", "scope": "#/properties/name"}]} |
| 119 | + }' |
| 120 | +``` |
| 121 | + |
| 122 | +## Supported Input Types |
| 123 | + |
| 124 | +The renderer automatically maps JSON Schema types and formats to appropriate HTML input types: |
| 125 | + |
| 126 | +| Schema Type | Schema Format | HTML Input Type | |
| 127 | +|-------------|---------------|-----------------| |
| 128 | +| `string` | - | `text` | |
| 129 | +| `string` | `email` | `email` | |
| 130 | +| `string` | `uri`, `url` | `url` | |
| 131 | +| `string` | `date` | `date` | |
| 132 | +| `string` | `time` | `time` | |
| 133 | +| `string` | `date-time` | `datetime-local` | |
| 134 | +| `string` | `color` | `color` | |
| 135 | +| `string` | `tel` | `tel` | |
| 136 | +| `string` with `multiLine: true` | - | `textarea` | |
| 137 | +| `string` with `enum` | - | `select` | |
| 138 | +| `integer`, `number` | - | `number` | |
| 139 | +| `boolean` | - | `checkbox` | |
| 140 | + |
| 141 | +## Validation Attributes |
| 142 | + |
| 143 | +The renderer automatically generates HTML5 validation attributes from JSON Schema: |
| 144 | + |
| 145 | +- `required` → `required` attribute |
| 146 | +- `minLength`, `maxLength` → `minlength`, `maxlength` |
| 147 | +- `minimum`, `maximum` → `min`, `max` |
| 148 | +- `pattern` → `pattern` |
| 149 | + |
| 150 | +## UI Schema Elements |
| 151 | + |
| 152 | +### Control |
| 153 | +Renders a single form field: |
| 154 | +```json |
| 155 | +{ |
| 156 | + "type": "Control", |
| 157 | + "scope": "#/properties/name", |
| 158 | + "label": "Your Name" |
| 159 | +} |
| 160 | +``` |
| 161 | + |
| 162 | +### VerticalLayout |
| 163 | +Stacks elements vertically: |
| 164 | +```json |
| 165 | +{ |
| 166 | + "type": "VerticalLayout", |
| 167 | + "elements": [...] |
| 168 | +} |
| 169 | +``` |
| 170 | + |
| 171 | +### HorizontalLayout |
| 172 | +Arranges elements horizontally (responsive, wraps on mobile): |
| 173 | +```json |
| 174 | +{ |
| 175 | + "type": "HorizontalLayout", |
| 176 | + "elements": [...] |
| 177 | +} |
| 178 | +``` |
| 179 | + |
| 180 | +### Group |
| 181 | +Creates a fieldset with legend: |
| 182 | +```json |
| 183 | +{ |
| 184 | + "type": "Group", |
| 185 | + "label": "Personal Information", |
| 186 | + "elements": [...] |
| 187 | +} |
| 188 | +``` |
| 189 | + |
| 190 | +### Categorization & Category |
| 191 | +Renders categories as fieldsets: |
| 192 | +```json |
| 193 | +{ |
| 194 | + "type": "Categorization", |
| 195 | + "elements": [ |
| 196 | + { |
| 197 | + "type": "Category", |
| 198 | + "label": "Basic Info", |
| 199 | + "elements": [...] |
| 200 | + } |
| 201 | + ] |
| 202 | +} |
| 203 | +``` |
| 204 | + |
| 205 | +### Label |
| 206 | +Renders static text: |
| 207 | +```json |
| 208 | +{ |
| 209 | + "type": "Label", |
| 210 | + "text": "Please fill out all required fields." |
| 211 | +} |
| 212 | +``` |
| 213 | + |
| 214 | +## Project Structure |
| 215 | + |
| 216 | +``` |
| 217 | +jsonforms-html/ |
| 218 | +├── main.go # Web server and HTTP handlers |
| 219 | +├── renderer/ # HTML rendering package |
| 220 | +│ ├── parser.go # Main renderer logic |
| 221 | +│ ├── generator.go # HTML element generation |
| 222 | +│ └── schema_helper.go # JSON Schema utilities |
| 223 | +├── go.mod |
| 224 | +└── README.md |
| 225 | +``` |
| 226 | + |
| 227 | +## Architecture |
| 228 | + |
| 229 | +The application consists of: |
| 230 | + |
| 231 | +- **Echo Web Server** (`main.go`): Handles HTTP requests and serves the web interface |
| 232 | +- **Renderer Package** (`renderer/`): Converts JSON Forms AST to HTML |
| 233 | + - `parser.go`: Main renderer that traverses the AST |
| 234 | + - `generator.go`: Low-level HTML element generation utilities |
| 235 | + - `schema_helper.go`: JSON Schema introspection and validation |
| 236 | + |
| 237 | +## Dependencies |
| 238 | + |
| 239 | +- [Echo](https://echo.labstack.com/) - High performance Go web framework |
| 240 | +- [jsonforms-parser](https://github.com/TinyBlueRobots/jsonforms-parser) - JSON Forms AST parser |
| 241 | + |
| 242 | +## Related Projects |
| 243 | + |
| 244 | +- [jsonforms-parser](https://github.com/TinyBlueRobots/jsonforms-parser) - The AST parser this renderer is built on |
| 245 | +- [JSON Forms](https://jsonforms.io/) - The official JavaScript implementation |
| 246 | + |
| 247 | +## License |
| 248 | + |
| 249 | +[Same license as jsonforms-parser] |
0 commit comments