Update docs for next version

Author: bhch

docs/docs/schema.md

@@ -23,5 +23,12 @@ Also, checkout the [playground]({{ '/playground' | url }}).
 
 Documented here: <https://django-jsonform.readthedocs.io/en/latest/guide/upload.html>
 
+Although the code examples in the document is for Django (Python) backend, but
+the concept can be adapted to any language.
+
+## Autocomplete input
+
+Documented here: <https://django-jsonform.readthedocs.io/en/latest/guide/autocomplete.html>
+
 Although the code examples in the document is for Django (Python) backend, but
 the concept can be adapted to any language.

docs/docs/usage/browser.md

@@ -25,7 +25,7 @@ You'll also need to have a `textarea` where the form will save the data.
 <script type="text/javascript">
 var form = reactJsonForm.createForm({
     containerId: 'formContainer',
-    containerId: 'formData',
+    dataInputId: 'formData',
     schema: {
         type: 'object',
         keys: {
@@ -51,6 +51,39 @@ form.addEventListener('change', function(e) {
 See [`addEventListener()`](#forminstance.addeventlistener(event%2C-callback)) section for 
 further details about handling events.
 
+
+## Data validation
+
+*New in version 2.1*
+
+The form component provides basic data validation.
+
+Usage example:
+
+```js
+var validation = form.validate();
+
+var isValid = validation.isValid; // it will be false if data is not valid
+
+var errorMap = validation.errorMap; // object containing error messages
+
+if (!isValid) {
+     // notify user
+    alert('Please correct the errors');
+
+    // update the form component
+    // it will display error messages below each input
+    form.update({errorMap: errorMap});
+}
+
+```
+
+You can adopt the above code example to validate the data before a form is submitted.
+
+You can also implement custom validation instead of calling `.validate()`. In that
+case, you'll have to manually create an [`errorMap` object]({{ '/docs/usage/node/#data-validation' | url }})
+for displaying error messages.
+
 ## API reference
 
 ### Library functions
@@ -65,6 +98,9 @@ which may contain these keys:
  - `schema`: The schema of the form.
  - `data` *(Optional)*: The initial data of the form.
  - `fileHandler` *(Optional)*: URL for the common file handler endpoint for all file fields.
+ - `errorMap` *(Optional)*: An object containing error messages for fields.
+
+*Changed in version 2.1*: `errorMap` option was added.
 
 
 ##### `reactJsonForm.getFormInstance(containerId)`
@@ -90,26 +126,54 @@ The following methods, attributes & events are available on a form instance.
 
 Register a callback for a given event ([see available events](#events)).
 
-The callback function will be passed an `Object` with the following keys:
+##### `formInstance.render()`
+
+Function to render the form.
+
+##### `formInstance.update(config)`
+
+Re-render the form with the given `config`.
+
+
+##### `formInstance.validate()`
+
+*New in version 2.1*
+
+Validates the current data against the instance's schema.
+
+Returns a *validation* object with following keys:
+
+ - `isValid`: It will be `true` if data is valid, else `false`.
+ - `errorMap`: An object containing field names and validation errors.
+
+##### `formInstance.getData()`
+
+*New in version 2.1*
+
+Returns the current data of the form instance.
+
+##### `formInstance.getSchema()`
+
+*New in version 2.1*
+
+Returns the current schema of the form instance.
+
+
+#### Events
+
+Following is the list of currently available events:
+
+##### `change`
+
+This event is fired for every change in the form's data.
+
+The callback for this event will be passed an `Object` with the following keys:
 
  - `data`: Current data of the form.
  - `prevData`: Previous data of the form (before the event).
  - `schema`: Current schema of the form.
  - `prevSchema`: Previous schema of the form (before the event).
 
-<div class="alert alert-info">
-    <p><strong>Attention!</strong></p>
-    <p>
-        If you want to call the <a href="#forminstance.update(config)"><code>update()</code></a>
-        method from within an event listener, <strong>you must call it conditionally</strong>
-        or else it might cause an infite loop.
-    </p>
-    <p>
-        For example, only call the <code>update()</code> after checking that the
-        current <code>data</code> and <code>prevData</code> are not same.
-    </p>
-</div>
-
 Example:
 
 ```js
@@ -125,17 +189,15 @@ form.addEventListener('change', function(e) {
 });
 ```
 
-##### `formInstance.render()`
-
-Function to render the form.
-
-##### `formInstance.update(config)`
-
-Re-render the form with the given `config`.
-
-
-#### Events
-
-Following is the list of currently available events:
-
- - `change`
+<div class="alert alert-info">
+    <p><strong>Attention!</strong></p>
+    <p>
+        If you want to call the <a href="#forminstance.update(config)"><code>update()</code></a>
+        method from the <code>change</code> event listener, <strong>you must call it conditionally</strong>
+        or else it might cause an infite loop.
+    </p>
+    <p>
+        For example, only call the <code>update()</code> after checking that the
+        current <code>data</code> and <code>prevData</code> are not same.
+    </p>
+</div>

docs/docs/usage/node.md

@@ -64,11 +64,15 @@ class MyComponent extends React.Component {
 
 ### Props
 
- - `editorState`: Instance of [`EditorState`](#editorstate) containing the schema and data.
- - `onChange`: Callback function for handling changing. This function will receive a new instance of 
+ - `editorState`: Instance of [`EditorState`](#editorstate-api-reference) containing the schema and data.
+ - `onChange`: Callback function for handling changes. This function will receive a new instance of 
  `EditorState` (because `EditorState` is immutable, instead of modifying the previous instance, we
  replace it with a new one).
  - `fileHandler`: A URL to a common file handler endpoint for all file input fields.
+ - `errorMap`: An object containing error messages for input fields. [See data validation section](#data-validation)
+ for more.  
+
+*Changed in version 2.1*: `errorMap` prop was added.
 
 ## `EditorState` API reference
 
@@ -132,3 +136,89 @@ declared in the schema.
 ##### `EditorState.getSchema()`
 
 This method returns the schema.
+
+
+#### Data validation
+
+*New in version 2.1*
+
+**React JSON Form** comes with some basic data validator called [`DataValidator`](#datavalidator-api-reference).
+But you are free to validate the data however you want.
+
+After the validation, you may also want to display error messages below the
+input fields. For this purpose, the `ReactJSONForm` component accepts an `errorMap`
+prop which is basically a mapping of field names in the data and error messages.
+
+An `errorMap` looks like this:
+
+```js
+let errorMap = {
+    'name': 'This field is required',
+
+    // multiple error messages
+    'age': [
+        'This field is required',
+        'This value must be greater than 18'
+    ]
+
+    // nested arrays and objects
+
+    // first item in array
+    '0': 'This is required',
+
+    // first item > object > property: name
+    '0-name': 'This is required'
+}
+```
+
+##### `DataValidator` API reference
+
+##### Constructor
+
+##### `new DataValidator(schema)`
+
+**Returns**: An instance of `DataValidator`
+
+**Arguments**:
+
+ - `schema`: Schema object (not JSON string).
+
+##### Instance methods
+
+Following methods must be called form the instance of `DataValidator`.
+
+##### `validatorInstance.validate(data)`
+
+**Returns**: A *validation* object containing these keys:
+
+ - `isValid`: A boolean denoting whether the data is valid or not.
+ - `errorMap`: An object containing error messages for invalid data fields.
+
+**Arguments**:
+
+ - `data`: The data to validate against the `schema` provided to the constructor.
+
+Example:
+
+```jsx
+import {DataValidator} from '@bhch/react-json-form';
+
+const validator = new DataValidator(schema);
+const validation = validator.validate(data);
+
+const isValid = validation.isValid;
+const errorMap = validation.errorMap;
+
+if (isValid)
+    alert('Success');
+else
+    alert('Invalid');
+
+// pass the errorMap object to ReactJSONForm
+// and error messages will be displayed under
+// input fields
+<ReactJSONForm
+    editorState={...}
+    errorMap={errorMap}
+/>
+```

docs/src/demos.js

@@ -225,6 +225,23 @@ const DEMOS = [
         }
     },
 
+    {
+        name: 'Autocomplete',
+        slug: 'autocomplete',
+        schema: {
+            type: 'object',
+            keys: {
+                country: {type: 'string', widget: 'autocomplete', handler: '/'},
+            }
+        },
+        description: () => (
+            <div>
+                Autocomplete widget sends AJAX request to a server. Hence, this demo will
+                not show any options because there's no server.
+            </div>
+        )
+    },
+
     {
         name: 'Textarea',
         slug: 'textarea',
@@ -237,6 +254,18 @@ const DEMOS = [
         }
     },
 
+    {
+        name: 'Range input',
+        slug: 'range',
+        schema: {
+            type: 'object',
+            title: 'Range input',
+            properties: {
+                volume: {type: 'number', widget: 'range', minimum: 0, maximum: 10}
+            }
+        }
+    },
+
     {
         name: 'Placeholder & Help text',
         slug: 'placehlder-help-text',
@@ -276,10 +305,22 @@ const DEMOS = [
             keys: {
                 email: {type: 'string', format: 'email'},
                 password: {type: 'string', format: 'password'},
-                range: {type: 'string', format: 'range'},
                 colour: {type: 'string', format: 'color'},
             }
         }
+    },
+
+    {
+        name: 'Validation',
+        slug: 'validation',
+        schema: {
+            type: 'object',
+            title: 'Press "Submit" to validate data',
+            keys: {
+                name: {type: 'string', required: true},
+                age: {type: 'number', required: true, minimum: 50},
+            }
+        }
     }
 ];