|
1 | 1 | # react-json-schema |
2 | 2 |
|
3 | | -This library builds React elements from JSON by mapping JSON definitions to React components that you expose. The interest behind making this library is to allow non-programmers whip up a view using JSON, which can be stored and retrieved in a database. Use it as you'd like. (JSX not required) |
| 3 | +This library builds React elements from JSON by mapping JSON definitions to React components that you expose. The interest behind making this library is to allow non-programmers to construct a view using JSON, which can be stored and retrieved in a database. Use it as you'd like. |
4 | 4 |
|
5 | | -### Documentation |
| 5 | +JSX is not a dependency for react-json-schema. |
| 6 | + |
| 7 | +For a quick reference, you can jump to [full example](#putting-it-all-together). |
6 | 8 |
|
7 | | -The first thing you'll need to do is define your schema in JSON (or a JavaScript object literal). When doing so, there are two things to note: |
8 | | -- A **component** key _must_ exist and be defined by a string or React Component |
9 | | -- A **children** key _may_ exist to define sub-components |
| 9 | +### Documentation |
10 | 10 |
|
11 | | -Next, we have to make sure that react-json-schema can create elements from component definitions. If a schema's **component** is defined by an string, you will need to expose the components included in the schema to react-json-schema. This can be done by calling `setComponentMap` with an object that has keys that match the strings in your schema, to the components are to be resolved by these strings. |
| 11 | +#### Schema |
12 | 12 |
|
13 | | -Finally, you'll need to call `parseSchema` to create elements from your schema. Now you have React elements at your disposal! |
| 13 | +The primary resource needed is a defined schema in JSON or a JavaScript object literal. It's recommended that schema attributes mainly define React component props. The parser explicitly handles the following attributes: |
| 14 | +- **component**: _MUST_ exist and be defined by a string or React component (must be a string if describing a native HTML tag) |
| 15 | +- **children**: _MAY_ exist to define sub-components |
| 16 | +- **text**: _MAY_ exist to as a string to define inner HTML text (overrides children) |
14 | 17 |
|
15 | | -Example (taken from /demo/index.jsx) |
| 18 | +Example JSON schema (ES6) |
16 | 19 | ```js |
17 | 20 | const schema = { |
18 | 21 | "component": "ContactForm", |
19 | 22 | "title": "Tell us a little about yourself...", |
20 | 23 | "children": [ |
21 | 24 | { |
22 | 25 | "component": "StringField", |
23 | | - "label": "What's your name", |
24 | | - "help": "It's okay, don't be shy :)" |
| 26 | + "label": "What's your name?" |
| 27 | + }, |
| 28 | + { |
| 29 | + "component": "a", |
| 30 | + "href": "#faq", |
| 31 | + "text": "I'm not sure why I'm filling this out" |
| 32 | + } |
| 33 | + ] |
| 34 | +} |
| 35 | +``` |
| 36 | + |
| 37 | +Example JS literal (ES6) |
| 38 | +```js |
| 39 | +const schema = { |
| 40 | + "component": ContactForm, |
| 41 | + "title": "Tell us a little about yourself...", |
| 42 | + "children": [ |
| 43 | + { |
| 44 | + "component": StringField, |
| 45 | + "label": "What's your name?" |
| 46 | + }, |
| 47 | + { |
| 48 | + "component": "a", |
| 49 | + "href": "#faq", |
| 50 | + "text": "I'm not sure why I'm filling this out" |
25 | 51 | } |
26 | 52 | ] |
27 | 53 | } |
| 54 | +``` |
| 55 | + |
| 56 | +##### Dynamic Children and Keys |
| 57 | + |
| 58 | +When arrays of components exist (like children), react-json-schema will resolve a key for the element based on the array index, which follows the rules for [dynamic children](https://facebook.github.io/react/docs/multiple-components.html#dynamic-children). Custom keys cannot be defined at this time. |
28 | 59 |
|
29 | | -/* es6 object literal shorthand */ |
| 60 | +#### Component Mapping |
| 61 | + |
| 62 | +React components need to be exposed to the react-json-schema so that the parser can create React elements. If the schema contains object literals with component references, the schema is exposing the React components and no additional configuration is needed. If the schema does not contain references to components, the components can be exposed via `setComponentMap`. |
| 63 | + |
| 64 | +Example for exposing non-exposed components (ES6) |
| 65 | +```js |
| 66 | +/* es6 object literal shorthand: { ContactForm } == { ContactForm: ContactForm } */ |
| 67 | +contactForm.setComponentMap({ ContactForm, StringField }); |
| 68 | +``` |
| 69 | + |
| 70 | +#### Parsing |
| 71 | + |
| 72 | +Use `parseSchema` to render React elements. It returns the root node. Note that if your schema's root is an array, you'll have to wrap the schema in an element. |
| 73 | + |
| 74 | +Example (ES6) |
| 75 | +```js |
| 76 | +/* If using ReactDOM (0.14+), else use React */ |
| 77 | +ReactDOM.render(contactForm.parseSchema(schema), |
| 78 | + document.getElementById('contact-form')); |
| 79 | +``` |
| 80 | + |
| 81 | +##### Rendering |
| 82 | + |
| 83 | +Also note react-json-schema also does not perform any rendering, so the method in which you want to render is up to you. For example, you can use ReactDOMServer.render, ReactDOM.renderToString, etc. if you'd like. |
| 84 | + |
| 85 | +#### Putting it All Together |
| 86 | + |
| 87 | +```js |
| 88 | +import ReactDOM from 'react-dom'; |
| 89 | +import ReactJsonSchema from 'react-json-schema'; |
| 90 | + |
| 91 | +import FormStore from './stores/FormStore'; |
| 92 | +import ContactForm from './components/ContactForm'; |
| 93 | +import StringField from './components/StringField'; |
| 94 | + |
| 95 | +// For this example, let's pretend I already have data and am ignorant of actions |
| 96 | +const schema = FormStore.getFormSchema(); |
30 | 97 | const componentMap = { ContactForm, StringField } |
| 98 | + |
31 | 99 | const contactForm = new ReactJsonSchema(); |
32 | 100 | contactForm.setComponentMap(componentMap); |
33 | 101 |
|
34 | | -React.render(contactForm.parseSchema(schema), |
35 | | - document.getElementById('json-react-schema')); |
| 102 | +ReactDOM.render(contactForm.parseSchema(schema), |
| 103 | + document.getElementById('contact-form')); |
36 | 104 | ``` |
37 | 105 |
|
38 | 106 | ### Try the Demo |
39 | 107 |
|
40 | 108 | To run the demo |
41 | | -* have webpack and webpack-dev-server globally installed |
42 | 109 | * `npm install` |
43 | 110 | * `npm run demo` |
44 | 111 | * The app will be served at http://localhost:8080 |
45 | 112 |
|
46 | 113 | ### Contribution and Code of Conduct |
47 | 114 |
|
48 | 115 | Please use a linter that recognizes eslint rules |
49 | | - |
50 | | -* have webpack, webpack-dev-server and jasmine globally installed |
51 | 116 | * `npm install` |
52 | 117 | * `npm test` (Jasmine's test report will output in /spec/index.html) |
53 | 118 | * `npm run build` |
54 | 119 |
|
55 | 120 | ### Roadmap |
56 | 121 |
|
57 | 122 | * Support custom keys for children |
58 | | -* Support native html tags as components, with the option to add custom tag definitions |
59 | | -* Drop lodash dependency? |
|
0 commit comments