Customising JSON Forms

How to customise?

Recently, we got a requirement for our app, where we had to render the different components (input box, dropdown etc) in the form on country basis. We decided to use JSON Forms to achieve this flexibility considering we can maintain different schemas per country in db directly render it in FE.

But, while implementing the actual requirements, we came across a few questions on “how to customise” which were not very clear through the official documentations.

We will covering all those those questions and missing documentation.

About

JSON Forms is a declarative framework for efficiently building form-based web UIs. These UIs are targeted at entering, modifying and viewing data and are usually embedded within an application.

We can build a basic form by giving two schemas: UI and json, which will render well aligned UI form for you.

Let’s start!

Q1. How to render your own component with the form rendered by JSON Forms.

Custom Renderers

The basic of custom renderer can be found https://jsonforms.io/docs/tutorial/custom-renderers

We can pass the custom renderers to the `renderers` list props.

For registering a renderer you need to create:

a. Renderer Tester

b. React component (Renderer)

Renderer Tester

import { rankWith, scopeEndsWith } from '@jsonforms/core';
export default rankWith(3, scopeEndsWith('datePicker'));

RankWith function takes two params:

1. Rank [number]: Higher the number, more priority will be given to the associated renderer component.
2. Tester [Tester]: This is function which takes uiSchema and jsonSchema and returns a boolean. If true, your custom renderer will be used to render form element if rank is also higher than other matching renderers.

There are few inbuilt functions which returns testers like

2.a. scopeEndsWith: Checks whether the scope of a control ends with the expected string. (Only applicable for Controls.)

Params:
expected — the expected ending of the reference

2.b. uiTypeIs: Checks whether the given UI schema has the expected type.

Params:
expected — the expected UI schema type

isControl, schemaMatches, schemaSubPathMatches, schemaTypeIs, formatIs, optionIs, scopeEndIs, uiTypeIs, formatIs...

There are two testers combiners as well.

1. and: A tester that allow composing other testers by && them.
   Params:
   testers — the testers to be composed
2. or: A tester that allow composing other testers by || them.
   Params:
   testers — the testers to be composed

Renderer:

It is a simple react component.

While registering if we render it with functions like withJsonFormsControlProps we get access to special props ( ControlProps in this case )

Few important keys for Control Props are:

a: config: Configuration of element

b: uiSchema, schema, data

c. enabled: Whether the rendered element should be enabled.

d. required: True when element is required as per json schema.

e. handleChange: Update handler that emits a data change ….

Q2. How to customise validation in JSON Forms?

JsonForms has a prop called ajv to which we can pass the customised ajv object.

The createAjv method available in jsonforms/core, can be used to create ajv object.

AddFormat

The addFormat method can be used to add any new format.

Now we can use a custom format ‘email’ in our jsonSchema, which ajv can validate on.

Q3. How to add custom error messages in JSON Forms?

There are multiple ways of adding custom error messages:

1. Add keyword with new definition.

We can define our own keyword with it’s definition consisting type, validate function and errors.

2. Add keyword with customise message.

We can pass inline function to addKeyword method and modify the messages by mapping through the vErrors.

In this way we can use the in-build definitions for all the keywords and just modify the error messages.

Q4. How to access property definition from other object in json schema.

$ref

$ref can be used inside jsonSchema when we need to access the definition from any other object outside properties (definitions in this case).

Resources:

1. https://jsonforms.io/docs: You can go through the docs which explains the use-case with example very well.
2. https://jsonforms.io/examples/basic: basic examples for starting.

3. https://jsonforms-editor.netlify.app/ : Playground for trying out online before implementing in your code.

Hope you are ready for customising your form now 😄.

Happy coding!