Merge pull request #371 from rvsia/updateDoc

[V2] Update doc

Author: Hyperkid123

packages/react-renderer-demo/src/app/pages/index.js

@@ -45,8 +45,7 @@ const LandingPage = () => {
       <div className={classes.landingPageContainer}>
         <LandingPageTitle />
         <Typography className={classes.landingPageText}>
-          Data Driven Forms is a component designed for ManageIQ and Red&nbsp;Hat&nbsp;Cloud&nbsp;Services projects that takes JSON form definitions
-          and renders them into react components.
+          Data Driven Forms converts JSON form definitions into fully functional React forms.
         </Typography>
         <div className={classes.getStartedLink}>
           <Link href="/renderer/installation">

packages/react-renderer-demo/src/app/pages/renderer/action-mapper.md

@@ -0,0 +1,77 @@
+import Grid from '@material-ui/core/Grid'
+import RouterLink from 'next/link';
+import Link from '@material-ui/core/Link';
+import ListOfContents from '../../src/helpers/list-of-contents';
+
+<Grid container item>
+<Grid item xs={12} md={10}>
+
+# Action Mapper
+
+The <RouterLink href="/renderer/renderer-api#optionalprops"><Link href="/renderer/renderer-api#optionalprops">ActionMapper</Link></RouterLink> allows you to map schema props to functions. This is useful when your schema is not written in JavaScript and you cannot use function inside of it, especially for schemas stored in databases.
+
+## Mapper
+
+```jsx
+{
+    [actionName]: (...args) => {}
+}
+```
+
+## Schema
+
+```jsx
+{
+    component: component,
+    name: name,
+    actions: {
+        [props]: [actionName, ...args]
+    }
+}
+```
+
+Do not forget to keep order of args or use object with keys as named arguments.
+
+# Example
+
+So, let's say you need to translate labels of fields using your translate function `translate(id)` and the schema has no access to use JavaScript code.
+
+Firstly, define a action mapper object.
+
+```jsx
+const actionMapper = {
+    translateLabel: (id) => translate(id)
+}
+```
+
+Add this object as a prop to FormRenderer.
+
+```jsx
+<FormRenderer
+  {...props}
+  schema={schema}
+  actionMapper={actionMapper}
+/>
+```
+
+Then, in your schema you can map `translateLabel` action to a prop:
+
+```js
+{
+    "fields": [
+        {
+            "component": "text-field",
+            "name": "translate-me",
+            "actions": {
+                "label": ["translateLabel", "translate_label_id"]
+            }
+        }
+    ]
+}
+```
+
+</Grid>
+<Grid item xs={false} md={2}>
+  <ListOfContents file="renderer/action-mapper" />
+</Grid>
+</Grid>

packages/react-renderer-demo/src/app/pages/renderer/component-api.md

@@ -20,7 +20,9 @@ There is very short list of that can be applied to every form field
 |component|string|Component identifier from componentMapper. Rendered component is chosen by this value|
 |hideField|boolean|Equivalent to html attribute `hidden`. Hides the field but it remains in DOM. Note that the field is still impacted by the form state. Validation will still apply on hidden field but the error message will not be displayed.|
 
-Each mapper provided in `react-forms` provides a default API for standard components. Standard components are:
+Each mapper provided in `react-forms` provides a default API for standard components. If you want to keep compatibility between our mappers and custom ones, please follow these APIs. Otherwise, it is up to you, which props you choose.
+
+Standard components are:
 <br />
 
 Wrapped in formGroup: <br/>
@@ -184,8 +186,8 @@ Wizard step <br/>
 |Prop|Type|Description|
 |----|:--:|----------:|
 |title|node/string|Step title|
-|stepKey|string, number|For first step: 1, otherwise anything|
-|nextStep|object/stepKey of next step|See below|
+|name|string, number|Uniq name of the step|
+|nextStep|object/name of next step|See <RouterLink href="/component-example/wizard"><Link href="/component-example/wizard">wizard documentation</Link></RouterLink>|
 |fields|array|An array of form fields|
 
 <ExampleLink to='wizard' />

packages/react-renderer-demo/src/app/pages/renderer/component-mapping.md

@@ -7,26 +7,16 @@ import ListOfContents from '../../src/helpers/list-of-contents';
 <Grid container item>
 <Grid item xs={12} md={10}>
 
-# Introduction
+# ComponentMapper
 
 In order to successfully render a form via FormRenderer you need to assign component mappers. Component mapper is an object of React components,
 where key is a component identifier and value is the Component. The identifiers must be equivalent to `componentTypes` in your schema.
 
-## FormTemplate
+## Creating componentMapper
 
-TODO
-
-## ComponentMapper
-Component mapper defines form inputs which can mutate the form state.
-
-# Creating FormTemplate
-
-
-# Creating componentMapper
-
-Form fields mapper defines components that are rendered from input schema. Each component in mapper must have an unique key,
-which corresponds to `componentType` in input schema. Keys names can be chosen but there are some predefined constants
-which cover most common component types. Predefined components are also automatically enhanced and connected to the form state.
+Component mapper defines components that are rendered from input schema. Each component in mapper must have an unique key,
+which corresponds to `componentType` in the schema. Keys names can be chosen but there are some predefined constants
+which cover most common component types.
 
 ```jsx
 import { componentTypes } from '@data-driven-forms/react-form-renderer';
@@ -48,6 +38,43 @@ const componentTypes = {
 }
 ```
 
+You have two options how to connect your component to the form state.
+
+### useFieldApi
+
+First, you can use `useFieldApi` hook.
+
+This hook needs `name`, in case of special input types which are using checked as the input value (checbkoxes, switches) you have to assign `type: checkbox`. The hook will return all field props, including input and meta. [TODO: LINK TO WHAT IS INPUT AND META]
+
+```jsx
+import { useFieldApi } from '@data-driven-forms/react-form-renderer';
+
+...
+
+const { input, isDisabled, label, helperText, description, meta } = useFieldApi(props);
+```
+
+### FieldProvider
+
+Or you can import `FieldProvider` component from Data Driven Forms. This component needs to obtain `render` or `component` prop.
+
+
+```jsx
+import { FieldProvider } from '@data-driven-forms/react-form-renderer'
+
+<FielProvider component={TextField}>
+
+// or
+
+<FielProvider render={({input, meta, ...props}) => <TextField {...props} input={input} meta={meta}>}>
+```
+
+## Example
+
+Below, you can see an basic implementation of custom component mapper:
+<br />
+
+
 <RawComponent source="component-mapper/form-fields-mapper" />
 </Grid>
 <Grid item xs={false} md={2}>

packages/react-renderer-demo/src/app/pages/renderer/field-array.md

@@ -10,13 +10,15 @@ import ListOfContents from '../../src/helpers/list-of-contents';
 
 # Field Array Provider
 
-Simillarly to <RouterLink href='/renderer/field-provider'><Link href='/renderer/field-provider'>FieldProvider</Link></RouterLink> Data driven forms provide an option how to inlude <a href='https://github.com/final-form/react-final-form-arrays'>React Final Form Arrays</a> in your form.
+Simillarly to <RouterLink href='/renderer/field-provider'><Link href='/renderer/field-provider'>FieldProvider</Link></RouterLink> Data driven forms provide an option how to inlude <a href='https://github.com/final-form/react-final-form-arrays'>React Final Form Arrays</a> in your form. Please visit their documentation to learn about functionality.
 
-<b>Please visit their documentation to learn about functionality.</b>
+## Using FieldArray
 
-## Using FieldArrayProvider
+You have to just import `FieldArray` from Data Driven Forms.
 
-Component mapped to `componentTypes.FIELD_ARRAY` (`field_array`) receives as a prop `FieldArrayProvider`. You can wrap your component into it and they you have an access to all functionallity.
+```jsx
+import { FieldArray } from '@data-driven-forms/react-form-renderer';
+```
 
 <RawComponent source="field-array/form-fields-mapper" />
 

packages/react-renderer-demo/src/app/pages/renderer/field-provider.md

@@ -9,63 +9,51 @@ import ListOfContents from '../../src/helpers/list-of-contents';
 <Grid container item>
 <Grid item xs={12} md={10}>
 
-# Field Provider
-
-## Custom components
+# Custom components
 
 React form renderer is using [react-final-form](https://github.com/final-form/react-final-form) for form state management.
 Most of its features are not directly available for consistency and performance reasons. If you want to create any custom
-components, you can access these features via `FieldProvider` prop.
+components, you can access these features via `FieldProvider` component or `useFieldApi` hook.
 
-FieldProvider is a wrapper component around standard
-[react-final-form Field component](https://final-form.org/docs/react-final-form/api/Field)
-which adds additional methods that will help you to control your form state.
+`FieldProvider` is a wrapper using `useFieldApi` to get the access to the form state.
 
-# Accessing FieldProvider
+`useFieldApi` is a wrapper around [React Final Form useField hook](https://final-form.org/docs/react-final-form/api/useField).
 
-To use Fieldprovider, you first need to register a component to your component mapper.
 You can read more about that in <RouterNav href="/renderer/component-mapping"><Link href="/renderer/component-mapping">Component mapping</Link></RouterNav>.
 
-Each component will receive FieldProvider as a prop. Be aware that pre-defined component types are
-automatically wrapped in FieldProvider. This is done to make it easier to create component mappers for
-standard form components. List of standard components is available <RouterNav href="/renderer/component-api"><Link href="/renderer/component-api">here</Link></RouterNav>.
-
-# Using FieldProvider
+## Implementation of component
 
-## Register component
+Next example shows simple input field with label and error message.
 
 ```jsx
-import NewComponent from './new-component'
-
-const componentMapper = {
-  'new-component': NewComponent
+import React from 'react';
+import { useFieldApi } from '@data-driven-forms/react-form-renderer'
+
+const NewComponent = (props) => {
+  const { input, meta } = useFieldApi(props);
+
+  return (
+    <div>
+      <label>{props.label}</label>
+      <input {...input} />
+      {meta.error && <label>{meta.error}</label>}
+    </div>
+  )
 }
+
+export default NewComponent
 ```
 
-## Implementation of component
+## Register component
 
-Next example shows simple input field with label and error message.
+To be able to use your component in the schema, you first need to register the component in your component mapper.
 
 ```jsx
-import React from 'react';
-
-const NewComponent = ({ FieldProvider, formOptions, name, ...rest }) => (
-  <div>
-    <FieldProvider {...rest} name={name}>
-      {({ input, meta, ...props }) => {
-        return (
-          <div>
-            <label>{props.label}</label>
-            <input {...input} />
-            {meta.error && <label>{meta.error}</label>}
-          </div>
-        )
-      }}
-    </FieldProvider>
-  </div>
-)
+import NewComponent from './new-component'
 
-export default NewComponent
+const componentMapper = {
+  'new-component': NewComponent
+}
 ```
 
 # What are input and meta?
@@ -100,11 +88,23 @@ Meta is a object which contains meta information about field with given name. Th
 }
 ```
 
-# FormOptions
+# useFormApi - formOptions
 
-In addition to FieldProvider, every component will also receive prop `formOptions`.
 This property contains a number of useful methods and attributes that will give you additional level of control
-and informations about the formState.
+and information about the formState.
+
+You can access it from every component by using `useFormApi` hook.
+
+```jsx
+import { useFormApi } from '@data-driven-forms/react-form-renderer';
+
+const Component = (props) => {
+     const formOptions = useFormApi();
+     ...
+}
+```
+
+This hook returns object containing following information:
 
 ```jsx
 {
@@ -120,9 +120,29 @@ and informations about the formState.
 }
 ```
 
-# FormSpy provider
+# FormSpy
+
+[FormSpy](https://final-form.org/docs/react-final-form/api/FormSpy) is exported via Data Driven Forms.
 
-Every component also receives component `FormSpyProvider` as a prop. You can find more info <a href="https://final-form.org/docs/react-final-form/api/FormSpy" rel="noopener noreferrer" target="_blank">here!</a>
+```jsx
+import { FormSpy } from '@data-driven-forms/react-form-renderer';
+```
+
+# FieldArray
+
+[React Final Form Array](https://github.com/final-form/react-final-form-arrays) is exported via Data Driven Forms.
+
+```jsx
+import { FieldArray } from '@data-driven-forms/react-form-renderer';
+```
+
+# Form
+
+For testing purposes, you can also import React Final Form's `Form` component.
+
+```jsx
+import { Form } from '@data-driven-forms/react-form-renderer';
+```
 
 </Grid>
 <Grid item xs={false} md={2}>