MobxSchemaForm is a React component which renders form fields as declared in json schema config object it receives. It supports the following props:
|model||FormStore or modelShape (with at minimum data and dataErrors Object properties)||MobxSchemaForm will create a fields property on this object when it mounts and will delete it when it unmounts. Otherwise MobxSchemaForm just passes the model object down to each formwidget.|
|schema||Object||Describes the data properties of the model|
|schema.type||String||Per json-schema-form standard, this should be "object"|
|schema.title||String||Optional - arbitrary title for this schema - currently not used anywhere|
|schema.properties||Object||Each data property should have a key in this object. mobx-schema-form also supports deep/nested objects which are referenced in "parent.child" format but there are limitations in MobX FormStore when using non-flat schemas.|
|schema.properties[key]||Object||See Data Property Schema.|
|schema.required||Array||Optional unordered array of field names (i.e. keys in schema.properties object) listing data properties that are considered required.|
|form||Array||Ordered list of objects that drives the rendering of form widgets. Supports nesting of form widgets inside fieldsets. See Form Field Metadata for format of each object. Instead of an Object, it's also possible to just have a String with the field name (i.e.schema.properties key) if no metadata is needed.|
|options||Object||Passed to react-schema-form SchemaForm in option prop.|
|options.suppressPropertyTitles (in react-schema-form it's supress, one p)||Boolean||If true, a field's title will not be set to its key when it's not specified in the Data Property Schema.|
|options.formDefaults||Object||Default Form Field Metadata to be used for all form fields. Merged shallowly (i.e. a validations array or validationMessage object in a given field will override the one here completely).|
|options.validators (*)||Object with each key referencing a function. Validator functions have the call signature of validateField().||Use this to define 'named' validator functions that can be referenced by the key in this object in Form Field Metadata optional validations array. Each validator function should return either a validation error message string or a tv4-form error object (i.e. with code and optional message) that will be processed using validationMessage in Form Field Metadata.|
|ignore||Object||Optional object with stringyfied schema paths as keys and true as values for this schema path to be ignored.|
|onModelChange||Function that receives the model key (i.e. the key in form metadata object or the modelKey in the corresponding schema object if defined) and the value||Optional callback that will be called whenever a widget raises an onChange event or a widget is first mounted or dismounted (in which case value will be undefined).|
|mapper||Object with each key referencing a React component/function||Optional. Maps Form Field Metadata types (not Data Property Schema types) to React components that implement the form widget. Allows you to add custom widgets or override default ones.|
|mergeMapper (*)||Boolean||If explicitly set to false (not undefined), provided mapper object will replace the default React-Toolbox-based mapper entirely instead of merging into it. This is useful to prevent MobxSchemaForm from requiring React-Toolbox components completely and allows you to use MobxSchemaForm without an environment configured for SASS-loading as required by React-Toolbox.|
|asArray (**)||Boolean||If true, the component will return an array of rendered fields without wrapping them in a div (requires React 16.0+ if used without a child component (see below)). Otherwise, just like the original react-schema-form <0.5.0, it will wrap the fields in a div with style=width:100% and className=SchemaForm. Note that this array is not really an array of components but a React Fragment and currently cannot be iterated/traversed.|
|className (***)||String||Optional class name for the top-level div. Defaults to "SchemaForm".|
|children (****)||React Element||Optional single child component to which fields are passed as children, so it can further wrap each field if necessary. The Child component will go inside the SchemaForm div unless asArray=true.|
* = feature not present in react-schema-form. ** = new feature in v1.6. *** = new feature in v1.7. **** = new feature in v1.8.
MobxSchemaForm will create a fields property on the model object when MobxSchemaForm mounts (unless it already exists). For each currently mounted form field there will be a key in model.fields. The name of each key is the modelKey in the corresponding schema.properties object if defined or just the schema.propreties key. Each key references a formField object in the formShape format which is a specially merged combination of the Form Field Metadata and the corresponding Data Property Schema.
It is often desired to call model.refresh() when MobxSchemaForm mounts to retrieve from server existing data that needs to be edited in the form. Be sure to do this in componentDidMount() of your form so that model.fields are in place when the FormStore afterRefresh callback runs, so that this callback can do:
const onlyWithValues = true; validateForm(store.fields, store, onlyWithValues);
This runs form-wide validation on already filled fields (though usually server won't return invalid data back) but more importantly it will also re-populate model.data properties that got 'refreshed' with null to defaults defined in the schema.
Note that starting with v1.6, if you mount multiple instances of MobxSchemaForm against the same FormStore model, whole-form validation will validate all fields from all mounted instances that use this model.
MobxSchemaForm will merge options.validators object it receives if any into model.validators.